@grinev/opencode-telegram-bot 0.10.1 → 0.11.1

package/README.md

@@ -26,14 +26,17 @@ 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`)
 
+Planned features currently in development are listed in [Current Task List](PRODUCT.md#current-task-list).
+
 ## Prerequisites
 
 - **Node.js 20+** — [download](https://nodejs.org)
@@ -70,7 +73,7 @@ npx @grinev/opencode-telegram-bot
 
 > Quick start is for npm usage. You do not need to clone this repository. If you run this command from the source directory (repository root), it may fail with `opencode-telegram: not found`. To run from sources, use the [Development](#development) section.
 
-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.
+On first launch, an interactive wizard will guide you through the configuration — it asks for interface language first, then your bot token, user ID, OpenCode API URL, and optional OpenCode server credentials (username/password). After that, you're ready to go. Open your bot in Telegram and start sending tasks.
 
 #### Alternative: Global Install
 
@@ -103,6 +106,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/app/start-bot-app.js

@@ -5,6 +5,7 @@ import { loadSettings } from "../settings/manager.js";
 import { processManager } from "../process/manager.js";
 import { warmupSessionDirectoryCache } from "../session/cache-manager.js";
 import { getRuntimeMode } from "../runtime/mode.js";
+import { getRuntimePaths } from "../runtime/paths.js";
 import { logger } from "../utils/logger.js";
 async function getBotVersion() {
     try {
@@ -20,8 +21,10 @@ async function getBotVersion() {
 }
 export async function startBotApp() {
     const mode = getRuntimeMode();
+    const runtimePaths = getRuntimePaths();
     const version = await getBotVersion();
     logger.info(`Starting OpenCode Telegram Bot v${version}...`);
+    logger.info(`Config loaded from ${runtimePaths.envFilePath}`);
     logger.info(`Allowed User ID: ${config.telegram.allowedUserId}`);
     logger.debug(`[Runtime] Application start mode: ${mode}`);
     await loadSettings();

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/commands/status.js

@@ -4,7 +4,6 @@ import { getCurrentProject } from "../../settings/manager.js";
 import { fetchCurrentAgent } from "../../agent/manager.js";
 import { getAgentDisplayName } from "../../agent/types.js";
 import { fetchCurrentModel } from "../../model/manager.js";
-import { formatModelForDisplay } from "../../model/types.js";
 import { processManager } from "../../process/manager.js";
 import { keyboardManager } from "../../keyboard/manager.js";
 import { pinnedMessageManager } from "../../pinned/manager.js";
@@ -42,7 +41,7 @@ export async function statusCommand(ctx) {
         message += `${t("status.line.mode", { mode: agentDisplay })}\n`;
         // Add model information
         const currentModel = fetchCurrentModel();
-        const modelDisplay = formatModelForDisplay(currentModel.providerID, currentModel.modelID);
+        const modelDisplay = `🤖 ${currentModel.providerID}/${currentModel.modelID}`;
         message += `${t("status.line.model", { model: modelDisplay })}\n`;
         const currentProject = getCurrentProject();
         if (currentProject) {

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";
@@ -120,7 +122,7 @@ async function ensureCommandsInitialized(ctx, next) {
             },
         });
         commandsInitialized = true;
-        logger.info(`[Bot] Commands initialized for authorized user (chat_id=${ctx.chat.id})`);
+        logger.debug(`[Bot] Commands initialized for authorized user (chat_id=${ctx.chat.id})`);
     }
     catch (err) {
         logger.error("[Bot] Failed to set commands:", err);
@@ -383,7 +385,7 @@ async function ensureEventSubscription(directory) {
 export function createBot() {
     clearAllInteractionState("bot_startup");
     toolMessageBatcher.setIntervalSeconds(config.bot.serviceMessagesIntervalSec);
-    logger.info(`[ToolBatcher] Service messages interval: ${config.bot.serviceMessagesIntervalSec}s`);
+    logger.debug(`[ToolBatcher] Service messages interval: ${config.bot.serviceMessagesIntervalSec}s`);
     const botOptions = {};
     if (config.telegram.proxyUrl) {
         const proxyUrl = config.telegram.proxyUrl;
@@ -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)) {
@@ -575,7 +584,7 @@ export function createBot() {
         },
         onSuccess: (result) => {
             if (result.success) {
-                logger.info("[Bot] Cleared global commands (default and all_private_chats scopes)");
+                logger.debug("[Bot] Cleared global commands (default and all_private_chats scopes)");
                 return;
             }
             logger.warn("[Bot] Could not clear global commands:", result.error);
@@ -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/config.js

@@ -2,7 +2,7 @@ import dotenv from "dotenv";
 import { getRuntimePaths } from "./runtime/paths.js";
 import { normalizeLocale } from "./i18n/index.js";
 const runtimePaths = getRuntimePaths();
-dotenv.config({ path: runtimePaths.envFilePath });
+dotenv.config({ path: runtimePaths.envFilePath, quiet: true });
 function getEnvVar(key, required = true) {
     const value = process.env[key];
     if (required && !value) {

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,23 +49,28 @@ 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",
     "status.line.health": "Status: {health}",
     "status.line.version": "Version: {version}",
-    "status.line.managed_yes": "Vom Bot verwaltet: Ja",
-    "status.line.managed_no": "Vom Bot verwaltet: Nein",
+    "status.line.managed_yes": "Vom Bot gestartet: Ja",
+    "status.line.managed_no": "Vom Bot gestartet: Nein",
     "status.line.pid": "PID: {pid}",
     "status.line.uptime_sec": "Betriebszeit: {seconds} s",
     "status.line.mode": "Modus: {mode}",
     "status.line.model": "Modell: {model}",
     "status.agent_not_set": "nicht gesetzt",
-    "status.project_selected": "🏗 Projekt: {project}",
-    "status.project_not_selected": "🏗 Projekt: nicht ausgewählt",
+    "status.project_selected": "Projekt: {project}",
+    "status.project_not_selected": "Projekt: nicht ausgewählt",
     "status.project_hint": "Nutze /projects, um ein Projekt auszuwahlen",
-    "status.session_selected": "📋 Aktuelle Sitzung: {title}",
-    "status.session_not_selected": "📋 Aktuelle Sitzung: nicht ausgewählt",
+    "status.session_selected": "Aktuelle Sitzung: {title}",
+    "status.session_not_selected": "Aktuelle Sitzung: nicht ausgewählt",
     "status.session_hint": "Nutze /sessions zur Auswahl oder /new zum Erstellen",
     "status.server_unavailable": "🔴 OpenCode-Server ist nicht verfügbar\n\nNutze /opencode_start, um den Server zu starten.",
     "projects.empty": "📭 Keine Projekte gefunden.\n\nÖffne ein Verzeichnis in OpenCode und erstelle mindestens eine Sitzung, dann erscheint es hier.",
@@ -222,6 +228,8 @@ export const de = {
     "runtime.wizard.ask_user_id": "Gib deine Telegram User ID ein (du bekommst sie bei @userinfobot).\n> ",
     "runtime.wizard.user_id_invalid": "Gib eine positive ganze Zahl ein (> 0).\n",
     "runtime.wizard.ask_api_url": "OpenCode API URL eingeben (optional).\nEnter drücken für Standard: {defaultUrl}\n> ",
+    "runtime.wizard.ask_server_username": "OpenCode-Server-Benutzername eingeben (optional).\nEnter drücken für Standard: {defaultUsername}\n> ",
+    "runtime.wizard.ask_server_password": "OpenCode-Server-Passwort eingeben (optional).\nEnter drücken, um es leer zu lassen.\n> ",
     "runtime.wizard.api_url_invalid": "Gib eine gültige URL (http/https) ein oder drücke Enter für Standard.\n",
     "runtime.wizard.start": "OpenCode Telegram Bot Einrichtung.\n",
     "runtime.wizard.saved": "Konfiguration gespeichert:\n- {envPath}\n- {settingsPath}\n",
@@ -238,6 +246,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,23 +49,28 @@ 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",
     "status.line.health": "Status: {health}",
     "status.line.version": "Version: {version}",
-    "status.line.managed_yes": "Managed by bot: Yes",
-    "status.line.managed_no": "Managed by bot: No",
+    "status.line.managed_yes": "Started by bot: Yes",
+    "status.line.managed_no": "Started by bot: No",
     "status.line.pid": "PID: {pid}",
     "status.line.uptime_sec": "Uptime: {seconds} sec",
     "status.line.mode": "Mode: {mode}",
     "status.line.model": "Model: {model}",
     "status.agent_not_set": "not set",
-    "status.project_selected": "🏗 Project: {project}",
-    "status.project_not_selected": "🏗 Project: not selected",
+    "status.project_selected": "Project: {project}",
+    "status.project_not_selected": "Project: not selected",
     "status.project_hint": "Use /projects to select a project",
-    "status.session_selected": "📋 Current session: {title}",
-    "status.session_not_selected": "📋 Current session: not selected",
+    "status.session_selected": "Current session: {title}",
+    "status.session_not_selected": "Current session: not selected",
     "status.session_hint": "Use /sessions to select one or /new to create one",
     "status.server_unavailable": "🔴 OpenCode Server is unavailable\n\nUse /opencode_start to start the server.",
     "projects.empty": "📭 No projects found.\n\nOpen a directory in OpenCode and create at least one session, then it will appear here.",
@@ -222,6 +228,8 @@ export const en = {
     "runtime.wizard.ask_user_id": "Enter your Telegram User ID (you can get it from @userinfobot).\n> ",
     "runtime.wizard.user_id_invalid": "Enter a positive integer (> 0).\n",
     "runtime.wizard.ask_api_url": "Enter OpenCode API URL (optional).\nPress Enter to use default: {defaultUrl}\n> ",
+    "runtime.wizard.ask_server_username": "Enter OpenCode server username (optional).\nPress Enter to use default: {defaultUsername}\n> ",
+    "runtime.wizard.ask_server_password": "Enter OpenCode server password (optional).\nPress Enter to keep it empty.\n> ",
     "runtime.wizard.api_url_invalid": "Enter a valid URL (http/https) or press Enter for default.\n",
     "runtime.wizard.start": "OpenCode Telegram Bot setup.\n",
     "runtime.wizard.saved": "Configuration saved:\n- {envPath}\n- {settingsPath}\n",
@@ -238,6 +246,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,23 +49,28 @@ 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",
     "status.line.health": "Estado: {health}",
     "status.line.version": "Versión: {version}",
-    "status.line.managed_yes": "Administrado por el bot: Sí",
-    "status.line.managed_no": "Administrado por el bot: No",
+    "status.line.managed_yes": "Iniciado por el bot: Sí",
+    "status.line.managed_no": "Iniciado por el bot: No",
     "status.line.pid": "PID: {pid}",
     "status.line.uptime_sec": "Tiempo activo: {seconds} s",
     "status.line.mode": "Modo: {mode}",
     "status.line.model": "Modelo: {model}",
     "status.agent_not_set": "no configurado",
-    "status.project_selected": "🏗 Proyecto: {project}",
-    "status.project_not_selected": "🏗 Proyecto: no seleccionado",
+    "status.project_selected": "Proyecto: {project}",
+    "status.project_not_selected": "Proyecto: no seleccionado",
     "status.project_hint": "Usa /projects para seleccionar un proyecto",
-    "status.session_selected": "📋 Sesión actual: {title}",
-    "status.session_not_selected": "📋 Sesión actual: no seleccionada",
+    "status.session_selected": "Sesión actual: {title}",
+    "status.session_not_selected": "Sesión actual: no seleccionada",
     "status.session_hint": "Usa /sessions para elegir una o /new para crear una",
     "status.server_unavailable": "🔴 OpenCode Server no está disponible\n\nUsa /opencode_start para iniciar el servidor.",
     "projects.empty": "📭 No se encontraron proyectos.\n\nAbre un directorio en OpenCode y crea al menos una sesión; entonces aparecerá aquí.",
@@ -222,6 +228,8 @@ export const es = {
     "runtime.wizard.ask_user_id": "Introduce tu Telegram User ID (puedes obtenerlo de @userinfobot).\n> ",
     "runtime.wizard.user_id_invalid": "Introduce un entero positivo (> 0).\n",
     "runtime.wizard.ask_api_url": "Introduce la URL de la API de OpenCode (opcional).\nPulsa Enter para usar el valor por defecto: {defaultUrl}\n> ",
+    "runtime.wizard.ask_server_username": "Introduce el nombre de usuario del servidor OpenCode (opcional).\nPulsa Enter para usar el valor por defecto: {defaultUsername}\n> ",
+    "runtime.wizard.ask_server_password": "Introduce la contrasena del servidor OpenCode (opcional).\nPulsa Enter para dejarla vacia.\n> ",
     "runtime.wizard.api_url_invalid": "Introduce una URL válida (http/https) o pulsa Enter para usar el valor por defecto.\n",
     "runtime.wizard.start": "Configuración de OpenCode Telegram Bot.\n",
     "runtime.wizard.saved": "Configuración guardada:\n- {envPath}\n- {settingsPath}\n",
@@ -238,6 +246,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,23 +49,28 @@ 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",
     "status.line.health": "Статус: {health}",
     "status.line.version": "Версия: {version}",
-    "status.line.managed_yes": "Управляется ботом: Да",
-    "status.line.managed_no": "Управляется ботом: Нет",
+    "status.line.managed_yes": "Запущен ботом: Да",
+    "status.line.managed_no": "Запущен ботом: Нет",
     "status.line.pid": "PID: {pid}",
     "status.line.uptime_sec": "Uptime: {seconds} сек",
     "status.line.mode": "Режим: {mode}",
     "status.line.model": "Модель: {model}",
     "status.agent_not_set": "не установлен",
-    "status.project_selected": "🏗 Проект: {project}",
-    "status.project_not_selected": "🏗 Проект: не выбран",
+    "status.project_selected": "Проект: {project}",
+    "status.project_not_selected": "Проект: не выбран",
     "status.project_hint": "Используйте /projects для выбора проекта",
-    "status.session_selected": "📋 Текущая сессия: {title}",
-    "status.session_not_selected": "📋 Текущая сессия: не выбрана",
+    "status.session_selected": "Текущая сессия: {title}",
+    "status.session_not_selected": "Текущая сессия: не выбрана",
     "status.session_hint": "Используйте /sessions для выбора или /new для создания",
     "status.server_unavailable": "🔴 OpenCode Server недоступен\n\nИспользуйте /opencode_start для запуска сервера.",
     "projects.empty": "📭 Проектов нет.\n\nОткройте директорию в OpenCode и создайте хотя бы одну сессию, после этого она появится здесь.",
@@ -202,14 +208,14 @@ export const ru = {
     "keyboard.variant": "💭 {name}",
     "keyboard.variant_default": "💡 Default",
     "keyboard.updated": "⌨️ Клавиатура обновлена",
-    "pinned.default_session_title": "new session",
-    "pinned.unknown": "Unknown",
-    "pinned.line.project": "Project: {project}",
-    "pinned.line.model": "Model: {model}",
-    "pinned.line.context": "Context: {used} / {limit} ({percent}%)",
-    "pinned.files.title": "Files ({count}):",
+    "pinned.default_session_title": "новая сессия",
+    "pinned.unknown": "Неизвестно",
+    "pinned.line.project": "Проект: {project}",
+    "pinned.line.model": "Модель: {model}",
+    "pinned.line.context": "Контекст: {used} / {limit} ({percent}%)",
+    "pinned.files.title": "Файлы ({count}):",
     "pinned.files.item": "  {path}{diff}",
-    "pinned.files.more": "  ... and {count} more",
+    "pinned.files.more": "  ... и еще {count}",
     "tool.todo.overflow": "*(ещё {count} задач)*",
     "tool.file_header.write": "Write File/Path: {path}\n============================================================\n\n",
     "tool.file_header.edit": "Edit File/Path: {path}\n============================================================\n\n",
@@ -222,6 +228,8 @@ export const ru = {
     "runtime.wizard.ask_user_id": "Введите ваш Telegram User ID (можно узнать у @userinfobot).\n> ",
     "runtime.wizard.user_id_invalid": "Введите положительное целое число (> 0).\n",
     "runtime.wizard.ask_api_url": "Введите URL OpenCode API (опционально).\nНажмите Enter для значения по умолчанию: {defaultUrl}\n> ",
+    "runtime.wizard.ask_server_username": "Введите логин OpenCode сервера (опционально).\nНажмите Enter для значения по умолчанию: {defaultUsername}\n> ",
+    "runtime.wizard.ask_server_password": "Введите пароль OpenCode сервера (опционально).\nНажмите Enter, чтобы оставить пустым.\n> ",
     "runtime.wizard.api_url_invalid": "Введите корректный URL (http/https) или нажмите Enter для значения по умолчанию.\n",
     "runtime.wizard.start": "Настройка OpenCode Telegram Bot.\n",
     "runtime.wizard.saved": "Конфигурация сохранена:\n- {envPath}\n- {settingsPath}\n",
@@ -238,6 +246,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,23 +49,28 @@ 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": "不健康",
     "status.line.health": "状态：{health}",
     "status.line.version": "版本：{version}",
-    "status.line.managed_yes": "由机器人管理：是",
-    "status.line.managed_no": "由机器人管理：否",
+    "status.line.managed_yes": "由机器人启动：是",
+    "status.line.managed_no": "由机器人启动：否",
     "status.line.pid": "PID：{pid}",
     "status.line.uptime_sec": "运行时间：{seconds} 秒",
     "status.line.mode": "模式：{mode}",
     "status.line.model": "模型：{model}",
     "status.agent_not_set": "未设置",
-    "status.project_selected": "🏗 项目：{project}",
-    "status.project_not_selected": "🏗 项目：未选择",
+    "status.project_selected": "项目：{project}",
+    "status.project_not_selected": "项目：未选择",
     "status.project_hint": "使用 /projects 选择项目",
-    "status.session_selected": "📋 当前会话：{title}",
-    "status.session_not_selected": "📋 当前会话：未选择",
+    "status.session_selected": "当前会话：{title}",
+    "status.session_not_selected": "当前会话：未选择",
     "status.session_hint": "使用 /sessions 选择一个会话，或 /new 创建",
     "status.server_unavailable": "🔴 OpenCode 服务器不可用\n\n使用 /opencode_start 启动服务器。",
     "projects.empty": "📭 未找到项目。\n\n在 OpenCode 中打开一个目录并至少创建一个会话，然后它会出现在这里。",
@@ -222,6 +228,8 @@ export const zh = {
     "runtime.wizard.ask_user_id": "请输入你的 Telegram User ID（可从 @userinfobot 获取）。\n> ",
     "runtime.wizard.user_id_invalid": "请输入一个正整数（> 0）。\n",
     "runtime.wizard.ask_api_url": "请输入 OpenCode API URL（可选）。\n按 Enter 使用默认值：{defaultUrl}\n> ",
+    "runtime.wizard.ask_server_username": "请输入 OpenCode 服务器用户名（可选）。\n按 Enter 使用默认值：{defaultUsername}\n> ",
+    "runtime.wizard.ask_server_password": "请输入 OpenCode 服务器密码（可选）。\n按 Enter 保持为空。\n> ",
     "runtime.wizard.api_url_invalid": "请输入有效 URL（http/https），或按 Enter 使用默认值。\n",
     "runtime.wizard.start": "OpenCode Telegram Bot 设置。\n",
     "runtime.wizard.saved": "配置已保存：\n- {envPath}\n- {settingsPath}\n",
@@ -238,6 +246,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/dist/runtime/bootstrap.js

@@ -7,6 +7,7 @@ import dotenv from "dotenv";
 import { getRuntimePaths } from "./paths.js";
 import { getLocale, getLocaleOptions, resolveSupportedLocale, setRuntimeLocale, t, } from "../i18n/index.js";
 const DEFAULT_API_URL = "http://localhost:4096";
+const DEFAULT_SERVER_USERNAME = "opencode";
 const FALLBACK_MODEL_PROVIDER = "opencode";
 const FALLBACK_MODEL_ID = "big-pickle";
 function isPositiveInteger(value) {
@@ -64,6 +65,8 @@ export function buildEnvFileContent(existingContent, values) {
         ["TELEGRAM_BOT_TOKEN", values.TELEGRAM_BOT_TOKEN],
         ["TELEGRAM_ALLOWED_USER_ID", values.TELEGRAM_ALLOWED_USER_ID],
         ["OPENCODE_API_URL", values.OPENCODE_API_URL],
+        ["OPENCODE_SERVER_USERNAME", values.OPENCODE_SERVER_USERNAME],
+        ["OPENCODE_SERVER_PASSWORD", values.OPENCODE_SERVER_PASSWORD],
         ["OPENCODE_MODEL_PROVIDER", values.OPENCODE_MODEL_PROVIDER],
         ["OPENCODE_MODEL_ID", values.OPENCODE_MODEL_ID],
     ];
@@ -242,6 +245,23 @@ async function askApiUrl() {
         return apiUrl;
     }
 }
+async function askServerUsername() {
+    const prompt = t("runtime.wizard.ask_server_username", {
+        defaultUsername: DEFAULT_SERVER_USERNAME,
+    });
+    const username = await askVisible(prompt);
+    if (!username) {
+        return DEFAULT_SERVER_USERNAME;
+    }
+    return username;
+}
+async function askServerPassword() {
+    const password = await askHidden(t("runtime.wizard.ask_server_password"));
+    if (!password) {
+        return undefined;
+    }
+    return password;
+}
 async function collectWizardValues() {
     const locale = await askLocale();
     setRuntimeLocale(locale);
@@ -258,12 +278,16 @@ async function collectWizardValues() {
     const token = await askToken();
     const allowedUserId = await askAllowedUserId();
     const apiUrl = await askApiUrl();
+    const serverUsername = await askServerUsername();
+    const serverPassword = await askServerPassword();
     process.stdout.write("\n");
     return {
         locale,
         token,
         allowedUserId,
         apiUrl,
+        serverUsername,
+        serverPassword,
     };
 }
 function ensureInteractiveTty() {
@@ -294,6 +318,8 @@ async function runWizardAndPersist(runtimePaths) {
         TELEGRAM_BOT_TOKEN: wizardValues.token,
         TELEGRAM_ALLOWED_USER_ID: wizardValues.allowedUserId,
         OPENCODE_API_URL: wizardValues.apiUrl,
+        OPENCODE_SERVER_USERNAME: wizardValues.serverUsername,
+        OPENCODE_SERVER_PASSWORD: wizardValues.serverPassword,
         OPENCODE_MODEL_PROVIDER: provider,
         OPENCODE_MODEL_ID: modelId,
     };

package/package.json

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