@grinev/opencode-telegram-bot 0.12.1 → 0.13.0

package/.env.example

@@ -40,6 +40,9 @@ OPENCODE_MODEL_ID=big-pickle
 # Maximum number of projects shown in /projects (default: 10)
 # PROJECTS_LIST_LIMIT=10
 
+# Maximum number of commands shown in /commands (default: 10)
+# COMMANDS_LIST_LIMIT=10
+
 # Maximum number of scheduled tasks allowed at once (default: 10)
 # TASK_LIMIT=10
 
@@ -58,6 +61,9 @@ OPENCODE_MODEL_ID=big-pickle
 # Hide tool call service messages (default: false)
 # HIDE_TOOL_CALL_MESSAGES=false
 
+# Stream assistant responses while they are being generated (default: true)
+# RESPONSE_STREAMING=true
+
 # Assistant message formatting mode (default: markdown)
 # markdown = convert assistant replies to Telegram MarkdownV2
 # raw = show assistant replies as plain text

package/README.md

@@ -159,10 +159,12 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `BOT_LOCALE`                    | Bot UI language (supported locale code, e.g. `en`, `de`, `es`, `fr`, `ru`, `zh`)                             |    No    | `en`                     |
 | `SESSIONS_LIST_LIMIT`           | Sessions per page in `/sessions`                                                                             |    No    | `10`                     |
 | `PROJECTS_LIST_LIMIT`           | Projects per page in `/projects`                                                                             |    No    | `10`                     |
+| `COMMANDS_LIST_LIMIT`           | Commands per page in `/commands`                                                                             |    No    | `10`                     |
 | `TASK_LIMIT`                    | Maximum number of scheduled tasks that can exist at once                                                     |    No    | `10`                     |
 | `SERVICE_MESSAGES_INTERVAL_SEC` | Service messages interval (thinking + tool calls); keep `>=2` to avoid Telegram rate limits, `0` = immediate |    No    | `5`                      |
 | `HIDE_THINKING_MESSAGES`        | Hide `💭 Thinking...` service messages                                                                       |    No    | `false`                  |
 | `HIDE_TOOL_CALL_MESSAGES`       | Hide tool-call service messages (`💻 bash ...`, `📖 read ...`, etc.)                                         |    No    | `false`                  |
+| `RESPONSE_STREAMING`            | Stream assistant replies while they are generated across one or more Telegram messages                       |    No    | `true`                   |
 | `MESSAGE_FORMAT_MODE`           | Assistant reply formatting mode: `markdown` (Telegram MarkdownV2) or `raw`                                   |    No    | `markdown`               |
 | `CODE_FILE_MAX_SIZE_KB`         | Max file size (KB) to send as document                                                                       |    No    | `100`                    |
 | `STT_API_URL`                   | Whisper-compatible API base URL (enables voice/audio transcription)                                          |    No    | —                        |

package/dist/bot/commands/commands.js

@@ -11,8 +11,10 @@ import { safeBackgroundTask } from "../../utils/safe-background-task.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 import { foregroundSessionState } from "../../scheduled-task/foreground-state.js";
+import { config } from "../../config.js";
 const COMMANDS_CALLBACK_PREFIX = "commands:";
 const COMMANDS_CALLBACK_SELECT_PREFIX = `${COMMANDS_CALLBACK_PREFIX}select:`;
+const COMMANDS_CALLBACK_PAGE_PREFIX = `${COMMANDS_CALLBACK_PREFIX}page:`;
 const COMMANDS_CALLBACK_CANCEL = `${COMMANDS_CALLBACK_PREFIX}cancel`;
 const COMMANDS_CALLBACK_EXECUTE = `${COMMANDS_CALLBACK_PREFIX}execute`;
 const MAX_INLINE_BUTTON_LABEL_LENGTH = 64;
@@ -21,6 +23,26 @@ function formatExecutingCommandMessage(commandName, args) {
     const argsSuffix = args ? ` ${args}` : "";
     return `${t("commands.executing_prefix")}\n${commandText}${argsSuffix}`;
 }
+export function buildCommandPageCallback(page) {
+    return `${COMMANDS_CALLBACK_PAGE_PREFIX}${page}`;
+}
+export function parseCommandPageCallback(data) {
+    if (!data.startsWith(COMMANDS_CALLBACK_PAGE_PREFIX)) {
+        return null;
+    }
+    const rawPage = data.slice(COMMANDS_CALLBACK_PAGE_PREFIX.length);
+    const page = Number(rawPage);
+    if (!Number.isInteger(page) || page < 0) {
+        return null;
+    }
+    return page;
+}
+export function formatCommandsSelectText(page) {
+    if (page === 0) {
+        return t("commands.select");
+    }
+    return t("commands.select_page", { page: page + 1 });
+}
 function normalizeDirectoryForCommandApi(directory) {
     return directory.replace(/\\/g, "/");
 }
@@ -40,13 +62,37 @@ function formatCommandButtonLabel(command) {
     }
     return `${rawLabel.slice(0, MAX_INLINE_BUTTON_LABEL_LENGTH - 3)}...`;
 }
-function buildCommandsListKeyboard(commands) {
+export function calculateCommandsPaginationRange(totalCommands, page, pageSize) {
+    const safePageSize = Math.max(1, pageSize);
+    const totalPages = Math.max(1, Math.ceil(totalCommands / safePageSize));
+    const normalizedPage = Math.min(Math.max(0, page), totalPages - 1);
+    const startIndex = normalizedPage * safePageSize;
+    const endIndex = Math.min(startIndex + safePageSize, totalCommands);
+    return {
+        page: normalizedPage,
+        totalPages,
+        startIndex,
+        endIndex,
+    };
+}
+function buildCommandsListKeyboard(commands, page, pageSize) {
     const keyboard = new InlineKeyboard();
-    commands.forEach((command, index) => {
+    const { page: normalizedPage, totalPages, startIndex, endIndex, } = calculateCommandsPaginationRange(commands.length, page, pageSize);
+    commands.slice(startIndex, endIndex).forEach((command, index) => {
+        const globalIndex = startIndex + index;
         keyboard
-            .text(formatCommandButtonLabel(command), `${COMMANDS_CALLBACK_SELECT_PREFIX}${index}`)
+            .text(formatCommandButtonLabel(command), `${COMMANDS_CALLBACK_SELECT_PREFIX}${globalIndex}`)
             .row();
     });
+    if (totalPages > 1) {
+        if (normalizedPage > 0) {
+            keyboard.text(t("commands.button.prev_page"), buildCommandPageCallback(normalizedPage - 1));
+        }
+        if (normalizedPage < totalPages - 1) {
+            keyboard.text(t("commands.button.next_page"), buildCommandPageCallback(normalizedPage + 1));
+        }
+        keyboard.row();
+    }
     keyboard.text(t("commands.button.cancel"), COMMANDS_CALLBACK_CANCEL);
     return keyboard;
 }
@@ -94,12 +140,16 @@ function parseCommandsMetadata(state) {
         if (!commands) {
             return null;
         }
+        const page = typeof state.metadata.page === "number" && Number.isInteger(state.metadata.page)
+            ? Math.max(0, state.metadata.page)
+            : 0;
         return {
             flow,
             stage,
             messageId,
             projectDirectory,
             commands,
+            page,
         };
     }
     if (stage === "confirm") {
@@ -270,8 +320,9 @@ export async function commandsCommand(ctx) {
             await ctx.reply(t("commands.empty"));
             return;
         }
-        const keyboard = buildCommandsListKeyboard(commands);
-        const message = await ctx.reply(t("commands.select"), {
+        const pageSize = config.bot.commandsListLimit;
+        const keyboard = buildCommandsListKeyboard(commands, 0, pageSize);
+        const message = await ctx.reply(formatCommandsSelectText(0), {
             reply_markup: keyboard,
         });
         interactionManager.start({
@@ -283,6 +334,7 @@ export async function commandsCommand(ctx) {
                 messageId: message.message_id,
                 projectDirectory: currentProject.worktree,
                 commands,
+                page: 0,
             },
         });
     }
@@ -324,6 +376,36 @@ export async function handleCommandsCallback(ctx, deps) {
             });
             return true;
         }
+        const page = parseCommandPageCallback(data);
+        if (page !== null) {
+            if (metadata.stage !== "list") {
+                await ctx.answerCallbackQuery({ text: t("callback.processing_error"), show_alert: true });
+                return true;
+            }
+            const pageSize = config.bot.commandsListLimit;
+            const { page: normalizedPage, totalPages } = calculateCommandsPaginationRange(metadata.commands.length, page, pageSize);
+            if (page >= totalPages || page < 0) {
+                await ctx.answerCallbackQuery({ text: t("commands.page_empty_callback") });
+                return true;
+            }
+            const keyboard = buildCommandsListKeyboard(metadata.commands, normalizedPage, pageSize);
+            await ctx.editMessageText(formatCommandsSelectText(normalizedPage), {
+                reply_markup: keyboard,
+            });
+            await ctx.answerCallbackQuery();
+            interactionManager.transition({
+                expectedInput: "callback",
+                metadata: {
+                    flow: "commands",
+                    stage: "list",
+                    messageId: metadata.messageId,
+                    projectDirectory: metadata.projectDirectory,
+                    commands: metadata.commands,
+                    page: normalizedPage,
+                },
+            });
+            return true;
+        }
         const commandIndex = parseSelectIndex(data);
         if (commandIndex === null || metadata.stage !== "list") {
             await ctx.answerCallbackQuery({ text: t("callback.processing_error"), show_alert: true });

package/dist/bot/commands/new.js

@@ -10,10 +10,15 @@ import { getStoredAgent } from "../../agent/manager.js";
 import { getStoredModel } from "../../model/manager.js";
 import { formatVariantForButton } from "../../variant/manager.js";
 import { createMainKeyboard } from "../utils/keyboard.js";
+import { isForegroundBusy, replyBusyBlocked } from "../utils/busy-guard.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 export async function newCommand(ctx) {
     try {
+        if (isForegroundBusy()) {
+            await replyBusyBlocked(ctx);
+            return;
+        }
         const currentProject = getCurrentProject();
         if (!currentProject) {
             await ctx.reply(t("new.project_not_selected"));

package/dist/bot/commands/projects.js

@@ -12,6 +12,7 @@ import { formatVariantForButton } from "../../variant/manager.js";
 import { clearAllInteractionState } from "../../interaction/cleanup.js";
 import { createMainKeyboard } from "../utils/keyboard.js";
 import { appendInlineMenuCancelButton, ensureActiveInlineMenu, replyWithInlineMenu, } from "../handlers/inline-menu.js";
+import { isForegroundBusy, replyBusyBlocked } from "../utils/busy-guard.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 import { config } from "../../config.js";
@@ -108,6 +109,10 @@ function buildProjectsMenuView(projects, page) {
 }
 export async function projectsCommand(ctx) {
     try {
+        if (isForegroundBusy()) {
+            await replyBusyBlocked(ctx);
+            return;
+        }
         await syncSessionDirectoryCache();
         const projects = await getProjects();
         if (projects.length === 0) {
@@ -131,6 +136,10 @@ export async function handleProjectSelect(ctx) {
     if (!callbackQuery?.data) {
         return false;
     }
+    if (isForegroundBusy()) {
+        await replyBusyBlocked(ctx);
+        return true;
+    }
     const page = parseProjectPageCallback(callbackQuery.data);
     if (page !== null) {
         const isActiveMenu = await ensureActiveInlineMenu(ctx, "project");

package/dist/bot/commands/sessions.js

@@ -7,6 +7,7 @@ import { summaryAggregator } from "../../summary/aggregator.js";
 import { pinnedMessageManager } from "../../pinned/manager.js";
 import { keyboardManager } from "../../keyboard/manager.js";
 import { appendInlineMenuCancelButton, ensureActiveInlineMenu, replyWithInlineMenu, } from "../handlers/inline-menu.js";
+import { isForegroundBusy, replyBusyBlocked } from "../utils/busy-guard.js";
 import { logger } from "../../utils/logger.js";
 import { safeBackgroundTask } from "../../utils/safe-background-task.js";
 import { config } from "../../config.js";
@@ -85,6 +86,10 @@ function buildSessionsKeyboard(pageData, pageSize) {
 }
 export async function sessionsCommand(ctx) {
     try {
+        if (isForegroundBusy()) {
+            await replyBusyBlocked(ctx);
+            return;
+        }
         const pageSize = config.bot.sessionsListLimit;
         const currentProject = getCurrentProject();
         if (!currentProject) {
@@ -118,6 +123,10 @@ export async function handleSessionSelect(ctx) {
     if (!callbackQuery?.data || !callbackQuery.data.startsWith(SESSION_CALLBACK_PREFIX)) {
         return false;
     }
+    if (isForegroundBusy()) {
+        await replyBusyBlocked(ctx);
+        return true;
+    }
     const page = parseSessionPageCallback(callbackQuery.data);
     const sessionId = parseSessionIdCallback(callbackQuery.data);
     const isActiveMenu = await ensureActiveInlineMenu(ctx, "session");

package/dist/bot/index.js

@@ -36,7 +36,7 @@ import { clearAllInteractionState } from "../interaction/cleanup.js";
 import { keyboardManager } from "../keyboard/manager.js";
 import { subscribeToEvents } from "../opencode/events.js";
 import { summaryAggregator } from "../summary/aggregator.js";
-import { formatSummary, formatToolInfo, getAssistantParseMode } from "../summary/formatter.js";
+import { formatSummary, formatSummaryWithMode, formatToolInfo, getAssistantParseMode, } from "../summary/formatter.js";
 import { ToolMessageBatcher } from "../summary/tool-message-batcher.js";
 import { getCurrentSession } from "../session/manager.js";
 import { ingestSessionInfoForCache } from "../session/cache-manager.js";
@@ -48,15 +48,21 @@ 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 { finalizeAssistantResponse } from "./utils/finalize-assistant-response.js";
+import { deliverThinkingMessage } from "./utils/thinking-message.js";
 import { sendBotText } from "./utils/telegram-text.js";
 import { getModelCapabilities, supportsInput } from "../model/capabilities.js";
 import { getStoredModel } from "../model/manager.js";
 import { foregroundSessionState } from "../scheduled-task/foreground-state.js";
 import { scheduledTaskRuntime } from "../scheduled-task/runtime.js";
+import { ResponseStreamer } from "./streaming/response-streamer.js";
+import { editMessageWithMarkdownFallback, sendMessageWithMarkdownFallback, } from "./utils/send-with-markdown-fallback.js";
 let botInstance = null;
 let chatIdInstance = null;
 let commandsInitialized = false;
 const TELEGRAM_DOCUMENT_CAPTION_MAX_LENGTH = 1024;
+const RESPONSE_STREAM_THROTTLE_MS = 200;
+const RESPONSE_STREAM_TEXT_LIMIT = 3800;
 const SESSION_RETRY_PREFIX = "🔁";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -77,6 +83,16 @@ function prepareDocumentCaption(caption) {
     }
     return `${normalizedCaption.slice(0, TELEGRAM_DOCUMENT_CAPTION_MAX_LENGTH - 3)}...`;
 }
+function prepareStreamingPayload(messageText) {
+    const parts = formatSummaryWithMode(messageText, config.bot.messageFormatMode, RESPONSE_STREAM_TEXT_LIMIT);
+    if (parts.length === 0) {
+        return null;
+    }
+    return {
+        parts,
+        format: config.bot.messageFormatMode === "markdown" ? "markdown_v2" : "raw",
+    };
+}
 const toolMessageBatcher = new ToolMessageBatcher({
     intervalSeconds: 5,
     sendText: async (sessionId, text) => {
@@ -118,6 +134,59 @@ const toolMessageBatcher = new ToolMessageBatcher({
         }
     },
 });
+const responseStreamer = new ResponseStreamer({
+    throttleMs: RESPONSE_STREAM_THROTTLE_MS,
+    sendText: async (text, format, options) => {
+        if (!botInstance || !chatIdInstance || chatIdInstance <= 0) {
+            throw new Error("Bot context missing for streamed send");
+        }
+        const parseMode = format === "markdown_v2" ? "MarkdownV2" : undefined;
+        const sentMessage = await sendMessageWithMarkdownFallback({
+            api: botInstance.api,
+            chatId: chatIdInstance,
+            text,
+            options,
+            parseMode,
+        });
+        return sentMessage.message_id;
+    },
+    editText: async (messageId, text, format, options) => {
+        if (!botInstance || !chatIdInstance || chatIdInstance <= 0) {
+            throw new Error("Bot context missing for streamed edit");
+        }
+        const parseMode = format === "markdown_v2" ? "MarkdownV2" : undefined;
+        try {
+            await editMessageWithMarkdownFallback({
+                api: botInstance.api,
+                chatId: chatIdInstance,
+                messageId,
+                text,
+                options,
+                parseMode,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+            if (errorMessage.includes("message is not modified")) {
+                return;
+            }
+            throw error;
+        }
+    },
+    deleteText: async (messageId) => {
+        if (!botInstance || !chatIdInstance || chatIdInstance <= 0) {
+            throw new Error("Bot context missing for streamed delete");
+        }
+        await botInstance.api.deleteMessage(chatIdInstance, messageId).catch((error) => {
+            const errorMessage = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+            if (errorMessage.includes("message to delete not found") ||
+                errorMessage.includes("message identifier is not specified")) {
+                return;
+            }
+            throw error;
+        });
+    },
+});
 async function ensureCommandsInitialized(ctx, next) {
     if (commandsInitialized || !ctx.from || ctx.from.id !== config.telegram.allowedUserId) {
         await next();
@@ -149,37 +218,73 @@ async function ensureEventSubscription(directory) {
         return;
     }
     toolMessageBatcher.setIntervalSeconds(config.bot.serviceMessagesIntervalSec);
+    summaryAggregator.setTypingIndicatorEnabled(true);
     summaryAggregator.setOnCleared(() => {
         toolMessageBatcher.clearAll("summary_aggregator_clear");
+        responseStreamer.clearAll("summary_aggregator_clear");
     });
-    summaryAggregator.setOnComplete(async (sessionId, messageText) => {
+    summaryAggregator.setOnPartial((sessionId, messageId, messageText) => {
+        if (!config.bot.responseStreaming) {
+            return;
+        }
+        if (!botInstance || !chatIdInstance) {
+            return;
+        }
+        const currentSession = getCurrentSession();
+        if (!currentSession || currentSession.id !== sessionId) {
+            return;
+        }
+        const preparedStreamPayload = prepareStreamingPayload(messageText);
+        if (!preparedStreamPayload) {
+            return;
+        }
+        preparedStreamPayload.sendOptions = undefined;
+        preparedStreamPayload.editOptions = undefined;
+        responseStreamer.enqueue(sessionId, messageId, preparedStreamPayload);
+    });
+    summaryAggregator.setOnComplete(async (sessionId, messageId, messageText) => {
         if (!botInstance || !chatIdInstance) {
             logger.error("Bot or chat ID not available for sending message");
+            responseStreamer.clearMessage(sessionId, messageId, "bot_context_missing");
             foregroundSessionState.markIdle(sessionId);
             return;
         }
         const currentSession = getCurrentSession();
         if (currentSession?.id !== sessionId) {
+            responseStreamer.clearMessage(sessionId, messageId, "session_mismatch");
             foregroundSessionState.markIdle(sessionId);
             await scheduledTaskRuntime.flushDeferredDeliveries();
             return;
         }
-        await toolMessageBatcher.flushSession(sessionId, "assistant_message_completed");
+        const botApi = botInstance.api;
+        const chatId = chatIdInstance;
         try {
-            const parts = formatSummary(messageText);
-            const assistantParseMode = getAssistantParseMode();
-            const assistantMessageFormat = assistantParseMode === "MarkdownV2" ? "markdown_v2" : "raw";
-            logger.debug(`[Bot] Sending completed message to Telegram (chatId=${chatIdInstance}, parts=${parts.length})`);
-            for (let i = 0; i < parts.length; i++) {
-                const keyboard = getCurrentReplyKeyboard();
-                const options = keyboard ? { reply_markup: keyboard } : undefined;
-                await sendBotText({
-                    api: botInstance.api,
-                    chatId: chatIdInstance,
-                    text: parts[i],
-                    options,
-                    format: assistantMessageFormat,
-                });
+            const streamedViaMessages = await finalizeAssistantResponse({
+                responseStreaming: config.bot.responseStreaming,
+                sessionId,
+                messageId,
+                messageText,
+                responseStreamer,
+                flushPendingServiceMessages: () => toolMessageBatcher.flushSession(sessionId, "assistant_message_completed"),
+                prepareStreamingPayload,
+                formatSummary,
+                resolveFormat: () => (getAssistantParseMode() === "MarkdownV2" ? "markdown_v2" : "raw"),
+                getReplyKeyboard: getCurrentReplyKeyboard,
+                sendText: async (text, options, format) => {
+                    await sendBotText({
+                        api: botApi,
+                        chatId,
+                        text,
+                        options: options,
+                        format,
+                    });
+                },
+            });
+            if (streamedViaMessages) {
+                logger.debug(`[Bot] Final assistant message already streamed (session=${sessionId}, message=${messageId})`);
+                foregroundSessionState.markIdle(sessionId);
+                await scheduledTaskRuntime.flushDeferredDeliveries();
+                return;
             }
         }
         catch (err) {
@@ -282,9 +387,6 @@ async function ensureEventSubscription(directory) {
         await showPermissionRequest(botInstance.api, chatIdInstance, request);
     });
     summaryAggregator.setOnThinking(async (sessionId) => {
-        if (config.bot.hideThinkingMessages) {
-            return;
-        }
         if (!botInstance || !chatIdInstance) {
             return;
         }
@@ -293,7 +395,10 @@ async function ensureEventSubscription(directory) {
             return;
         }
         logger.debug("[Bot] Agent started thinking");
-        toolMessageBatcher.enqueue(sessionId, t("bot.thinking"));
+        deliverThinkingMessage(sessionId, toolMessageBatcher, {
+            responseStreaming: config.bot.responseStreaming,
+            hideThinkingMessages: config.bot.hideThinkingMessages,
+        });
     });
     summaryAggregator.setOnTokens(async (tokens) => {
         if (!pinnedMessageManager.isInitialized()) {
@@ -345,10 +450,12 @@ async function ensureEventSubscription(directory) {
         }
         const currentSession = getCurrentSession();
         if (!currentSession || currentSession.id !== sessionId) {
+            responseStreamer.clearSession(sessionId, "session_error_not_current");
             foregroundSessionState.markIdle(sessionId);
             await scheduledTaskRuntime.flushDeferredDeliveries();
             return;
         }
+        responseStreamer.clearSession(sessionId, "session_error");
         await toolMessageBatcher.flushSession(sessionId, "session_error");
         const normalizedMessage = message.trim() || t("common.unknown_error");
         const truncatedMessage = normalizedMessage.length > 3500

package/dist/bot/middleware/interaction-guard.js

@@ -77,8 +77,12 @@ export async function interactionGuardMiddleware(ctx, next) {
         await next();
         return;
     }
-    const message = getInteractionBlockedMessage(decision.reason, decision.state?.kind);
-    logger.debug(`[InteractionGuard] Blocked input: interactionKind=${decision.state?.kind || "none"}, inputType=${decision.inputType}, reason=${decision.reason || "unknown"}, command=${decision.command || "-"}`);
+    const message = decision.busy
+        ? decision.state?.kind === "question" || decision.state?.kind === "permission"
+            ? getInteractionBlockedMessage(decision.reason, decision.state.kind)
+            : t("interaction.blocked.finish_current")
+        : getInteractionBlockedMessage(decision.reason, decision.state?.kind);
+    logger.debug(`[InteractionGuard] Blocked input: interactionKind=${decision.state?.kind || "none"}, inputType=${decision.inputType}, reason=${decision.reason || "unknown"}, command=${decision.command || "-"}, busy=${decision.busy ? "yes" : "no"}`);
     if (ctx.callbackQuery) {
         await ctx.answerCallbackQuery({ text: message }).catch(() => { });
         return;