@grinev/opencode-telegram-bot 0.12.0 → 0.13.0

package/dist/bot/streaming/response-streamer.js

@@ -0,0 +1,284 @@
+import { logger } from "../../utils/logger.js";
+function buildStateKey(sessionId, messageId) {
+    return `${sessionId}:${messageId}`;
+}
+function normalizePayload(payload) {
+    const normalizedParts = payload.parts
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (normalizedParts.length === 0) {
+        return null;
+    }
+    return {
+        parts: normalizedParts,
+        format: payload.format,
+        sendOptions: payload.sendOptions,
+        editOptions: payload.editOptions,
+    };
+}
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function getRetryAfterMs(error) {
+    const message = getErrorMessage(error);
+    if (!/\b429\b/.test(message)) {
+        return null;
+    }
+    const retryMatch = message.match(/retry after\s+(\d+)/i);
+    if (!retryMatch) {
+        return null;
+    }
+    const seconds = Number.parseInt(retryMatch[1], 10);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        return null;
+    }
+    return seconds * 1000;
+}
+function createSignature(text, format) {
+    return `${format}\n${text}`;
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export class ResponseStreamer {
+    throttleMs;
+    sendText;
+    editText;
+    deleteText;
+    states = new Map();
+    constructor(options) {
+        this.throttleMs = Math.max(0, Math.floor(options.throttleMs));
+        this.sendText = options.sendText;
+        this.editText = options.editText;
+        this.deleteText = options.deleteText;
+    }
+    enqueue(sessionId, messageId, payload) {
+        const normalizedPayload = normalizePayload(payload);
+        if (!normalizedPayload) {
+            return;
+        }
+        const state = this.getOrCreateState(sessionId, messageId);
+        state.latestPayload = normalizedPayload;
+        if (state.isBroken) {
+            return;
+        }
+        this.ensureTimer(state);
+    }
+    async complete(sessionId, messageId, payload, options) {
+        const state = this.states.get(buildStateKey(sessionId, messageId));
+        if (!state) {
+            return false;
+        }
+        if (payload) {
+            const normalizedPayload = normalizePayload(payload);
+            if (normalizedPayload) {
+                state.latestPayload = normalizedPayload;
+            }
+        }
+        this.clearTimer(state);
+        await state.task.catch(() => false);
+        if (state.isBroken) {
+            await this.cleanupBrokenStream(state, "complete_broken_stream");
+            this.cancelState(state);
+            this.states.delete(state.key);
+            return false;
+        }
+        if (state.telegramMessageIds.length === 0) {
+            this.cancelState(state);
+            this.states.delete(state.key);
+            return false;
+        }
+        let synced = true;
+        if (options?.flushFinal !== false) {
+            synced = await this.enqueueTask(state, () => this.flushState(state, "complete"));
+            if (!synced && state.isBroken) {
+                await this.cleanupBrokenStream(state, "final_sync_failed_cleanup");
+            }
+        }
+        this.cancelState(state);
+        this.states.delete(state.key);
+        return synced;
+    }
+    clearMessage(sessionId, messageId, reason) {
+        const key = buildStateKey(sessionId, messageId);
+        const state = this.states.get(key);
+        if (!state) {
+            return;
+        }
+        this.cancelState(state);
+        this.states.delete(key);
+        logger.debug(`[ResponseStreamer] Cleared message stream: session=${sessionId}, message=${messageId}, reason=${reason}`);
+    }
+    clearSession(sessionId, reason) {
+        for (const state of Array.from(this.states.values())) {
+            if (state.sessionId !== sessionId) {
+                continue;
+            }
+            this.cancelState(state);
+            this.states.delete(state.key);
+        }
+        logger.debug(`[ResponseStreamer] Cleared session streams: session=${sessionId}, reason=${reason}`);
+    }
+    clearAll(reason) {
+        for (const state of this.states.values()) {
+            this.cancelState(state);
+        }
+        const count = this.states.size;
+        this.states.clear();
+        if (count > 0) {
+            logger.debug(`[ResponseStreamer] Cleared all streams: count=${count}, reason=${reason}`);
+        }
+    }
+    getOrCreateState(sessionId, messageId) {
+        const key = buildStateKey(sessionId, messageId);
+        const existing = this.states.get(key);
+        if (existing) {
+            return existing;
+        }
+        const state = {
+            key,
+            sessionId,
+            messageId,
+            latestPayload: null,
+            lastSentSignatures: [],
+            telegramMessageIds: [],
+            timer: null,
+            task: Promise.resolve(true),
+            cancelled: false,
+            isBroken: false,
+            fatalErrorMessage: null,
+            fatalErrorLogged: false,
+        };
+        this.states.set(key, state);
+        return state;
+    }
+    ensureTimer(state) {
+        if (state.timer || state.cancelled) {
+            return;
+        }
+        if (this.throttleMs === 0) {
+            void this.enqueueTask(state, () => this.flushState(state, "immediate")).catch((error) => {
+                logger.error(`[ResponseStreamer] Immediate stream sync failed: session=${state.sessionId}, message=${state.messageId}`, error);
+            });
+            return;
+        }
+        state.timer = setTimeout(() => {
+            state.timer = null;
+            void this.enqueueTask(state, () => this.flushState(state, "throttle_elapsed")).catch((error) => {
+                logger.error(`[ResponseStreamer] Throttled stream sync failed: session=${state.sessionId}, message=${state.messageId}`, error);
+            });
+        }, this.throttleMs);
+    }
+    clearTimer(state) {
+        if (!state.timer) {
+            return;
+        }
+        clearTimeout(state.timer);
+        state.timer = null;
+    }
+    cancelState(state) {
+        state.cancelled = true;
+        this.clearTimer(state);
+    }
+    enqueueTask(state, task) {
+        const nextTask = state.task.catch(() => false).then(task);
+        state.task = nextTask;
+        return nextTask;
+    }
+    async flushState(state, reason) {
+        if (state.cancelled) {
+            return false;
+        }
+        if (state.isBroken) {
+            return false;
+        }
+        while (!state.cancelled) {
+            const payload = state.latestPayload;
+            if (!payload) {
+                return state.telegramMessageIds.length > 0;
+            }
+            const targetSignatures = payload.parts.map((part) => createSignature(part, payload.format));
+            const unchanged = targetSignatures.length === state.lastSentSignatures.length &&
+                targetSignatures.every((signature, index) => signature === state.lastSentSignatures[index]);
+            if (unchanged) {
+                return state.telegramMessageIds.length > 0;
+            }
+            try {
+                await this.syncMessages(state, payload, targetSignatures);
+                logger.debug(`[ResponseStreamer] Stream synced: session=${state.sessionId}, message=${state.messageId}, reason=${reason}, parts=${payload.parts.length}`);
+                return true;
+            }
+            catch (error) {
+                const retryAfterMs = getRetryAfterMs(error);
+                if (retryAfterMs === null) {
+                    this.markStreamBroken(state, error, reason);
+                    return false;
+                }
+                const delayMs = Math.max(this.throttleMs, retryAfterMs);
+                logger.warn(`[ResponseStreamer] Stream sync rate-limited, retrying in ${delayMs}ms: session=${state.sessionId}, message=${state.messageId}, reason=${reason}`, error);
+                await delay(delayMs);
+            }
+        }
+        return false;
+    }
+    markStreamBroken(state, error, reason) {
+        state.isBroken = true;
+        state.fatalErrorMessage = getErrorMessage(error);
+        if (state.fatalErrorLogged) {
+            return;
+        }
+        state.fatalErrorLogged = true;
+        logger.error(`[ResponseStreamer] Stream marked as broken: session=${state.sessionId}, message=${state.messageId}, reason=${reason}, error=${state.fatalErrorMessage}`, error);
+    }
+    async cleanupBrokenStream(state, reason) {
+        if (state.telegramMessageIds.length === 0) {
+            return;
+        }
+        for (let index = state.telegramMessageIds.length - 1; index >= 0; index--) {
+            const messageId = state.telegramMessageIds[index];
+            if (!messageId) {
+                continue;
+            }
+            try {
+                await this.deleteText(messageId);
+            }
+            catch (error) {
+                logger.warn(`[ResponseStreamer] Failed to delete broken stream message: session=${state.sessionId}, message=${state.messageId}, telegramMessageId=${messageId}, reason=${reason}`, error);
+            }
+        }
+        state.telegramMessageIds = [];
+        state.lastSentSignatures = [];
+        logger.debug(`[ResponseStreamer] Cleaned up broken stream messages: session=${state.sessionId}, message=${state.messageId}, reason=${reason}`);
+    }
+    async syncMessages(state, payload, targetSignatures) {
+        for (let index = 0; index < payload.parts.length; index++) {
+            const text = payload.parts[index];
+            const nextSignature = targetSignatures[index];
+            const currentMessageId = state.telegramMessageIds[index];
+            if (currentMessageId) {
+                if (state.lastSentSignatures[index] === nextSignature) {
+                    continue;
+                }
+                await this.editText(currentMessageId, text, payload.format, payload.editOptions);
+                state.lastSentSignatures[index] = nextSignature;
+                continue;
+            }
+            const messageId = await this.sendText(text, payload.format, payload.sendOptions);
+            state.telegramMessageIds[index] = messageId;
+            state.lastSentSignatures[index] = nextSignature;
+        }
+        for (let index = state.telegramMessageIds.length - 1; index >= payload.parts.length; index--) {
+            const messageId = state.telegramMessageIds[index];
+            if (messageId) {
+                await this.deleteText(messageId);
+            }
+            state.telegramMessageIds.pop();
+            state.lastSentSignatures.pop();
+        }
+    }
+}

package/dist/bot/utils/busy-guard.js

@@ -0,0 +1,15 @@
+import { foregroundSessionState } from "../../scheduled-task/foreground-state.js";
+import { t } from "../../i18n/index.js";
+export function isForegroundBusy() {
+    return foregroundSessionState.isBusy();
+}
+export async function replyBusyBlocked(ctx) {
+    const message = t("interaction.blocked.finish_current");
+    if (ctx.callbackQuery) {
+        await ctx.answerCallbackQuery({ text: message }).catch(() => { });
+        return;
+    }
+    if (ctx.chat) {
+        await ctx.reply(message).catch(() => { });
+    }
+}

package/dist/bot/utils/finalize-assistant-response.js

@@ -0,0 +1,23 @@
+export async function finalizeAssistantResponse({ responseStreaming, sessionId, messageId, messageText, responseStreamer, flushPendingServiceMessages, prepareStreamingPayload, formatSummary, resolveFormat, getReplyKeyboard, sendText, }) {
+    let streamedViaMessages = false;
+    if (responseStreaming) {
+        const preparedStreamPayload = prepareStreamingPayload(messageText);
+        if (preparedStreamPayload) {
+            preparedStreamPayload.sendOptions = undefined;
+            preparedStreamPayload.editOptions = undefined;
+        }
+        streamedViaMessages = await responseStreamer.complete(sessionId, messageId, preparedStreamPayload ?? undefined);
+    }
+    await flushPendingServiceMessages();
+    if (streamedViaMessages) {
+        return true;
+    }
+    const parts = formatSummary(messageText);
+    const format = resolveFormat();
+    for (const part of parts) {
+        const keyboard = getReplyKeyboard();
+        const options = keyboard ? { reply_markup: keyboard } : undefined;
+        await sendText(part, options, format);
+    }
+    return false;
+}

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

@@ -38,41 +38,39 @@ export function isTelegramMarkdownParseError(error) {
 }
 export async function sendMessageWithMarkdownFallback({ api, chatId, text, options, parseMode, }) {
     if (!parseMode) {
-        await api.sendMessage(chatId, text, options);
-        return;
+        return api.sendMessage(chatId, text, options);
     }
     const markdownOptions = {
         ...(options || {}),
         parse_mode: parseMode,
     };
     try {
-        await api.sendMessage(chatId, text, markdownOptions);
+        return await api.sendMessage(chatId, text, markdownOptions);
     }
     catch (error) {
         if (!isTelegramMarkdownParseError(error)) {
             throw error;
         }
         logger.warn("[Bot] Markdown parse failed, retrying assistant message in raw mode", error);
-        await api.sendMessage(chatId, text, options);
+        return api.sendMessage(chatId, text, options);
     }
 }
 export async function editMessageWithMarkdownFallback({ api, chatId, messageId, text, options, parseMode, }) {
     if (!parseMode) {
-        await api.editMessageText(chatId, messageId, text, options);
-        return;
+        return api.editMessageText(chatId, messageId, text, options);
     }
     const markdownOptions = {
         ...(options || {}),
         parse_mode: parseMode,
     };
     try {
-        await api.editMessageText(chatId, messageId, text, markdownOptions);
+        return await api.editMessageText(chatId, messageId, text, markdownOptions);
     }
     catch (error) {
         if (!isTelegramMarkdownParseError(error)) {
             throw error;
         }
         logger.warn("[Bot] Markdown parse failed, retrying edited message in raw mode", error);
-        await api.editMessageText(chatId, messageId, text, options);
+        return api.editMessageText(chatId, messageId, text, options);
     }
 }

package/dist/bot/utils/thinking-message.js

@@ -0,0 +1,12 @@
+import { t } from "../../i18n/index.js";
+export function deliverThinkingMessage(sessionId, batcher, options) {
+    if (options.hideThinkingMessages) {
+        return;
+    }
+    const message = t("bot.thinking");
+    if (options.responseStreaming) {
+        batcher.sendTextNow(sessionId, message, "thinking_started_streaming");
+        return;
+    }
+    batcher.enqueue(sessionId, message);
+}

package/dist/config.js

@@ -85,11 +85,13 @@ export const config = {
     bot: {
         sessionsListLimit: getOptionalPositiveIntEnvVar("SESSIONS_LIST_LIMIT", 10),
         projectsListLimit: getOptionalPositiveIntEnvVar("PROJECTS_LIST_LIMIT", 10),
+        commandsListLimit: getOptionalPositiveIntEnvVar("COMMANDS_LIST_LIMIT", 10),
         taskLimit: getOptionalPositiveIntEnvVar("TASK_LIMIT", 10),
         locale: getOptionalLocaleEnvVar("BOT_LOCALE", "en"),
         serviceMessagesIntervalSec: getOptionalNonNegativeIntEnvVarFromKeys(["SERVICE_MESSAGES_INTERVAL_SEC", "TOOL_MESSAGES_INTERVAL_SEC"], 5),
         hideThinkingMessages: getOptionalBooleanEnvVar("HIDE_THINKING_MESSAGES", false),
         hideToolCallMessages: getOptionalBooleanEnvVar("HIDE_TOOL_CALL_MESSAGES", false),
+        responseStreaming: getOptionalBooleanEnvVar("RESPONSE_STREAMING", true),
         messageFormatMode: getOptionalMessageFormatModeEnvVar("MESSAGE_FORMAT_MODE", "markdown"),
     },
     files: {

package/dist/i18n/de.js

@@ -216,6 +216,7 @@ export const de = {
     "pinned.line.project": "Projekt: {project}",
     "pinned.line.model": "Modell: {model}",
     "pinned.line.context": "Kontext: {used} / {limit} ({percent}%)",
+    "pinned.line.cost": "Kosten: {cost} ausgegeben",
     "pinned.files.title": "Dateien ({count}):",
     "pinned.files.item": "  {path}{diff}",
     "pinned.files.more": "  ... und {count} mehr",
@@ -297,6 +298,11 @@ export const de = {
     "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.",
+    "commands.select_page": "Wähle einen OpenCode-Befehl (Seite {page}):",
+    "commands.button.prev_page": "⬅️ Zurück",
+    "commands.button.next_page": "Weiter ➡️",
+    "commands.page_empty_callback": "Keine Befehle auf dieser Seite",
+    "commands.page_load_error_callback": "Diese Seite konnte nicht geladen werden. Bitte versuche es erneut.",
     "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

@@ -216,6 +216,7 @@ export const en = {
     "pinned.line.project": "Project: {project}",
     "pinned.line.model": "Model: {model}",
     "pinned.line.context": "Context: {used} / {limit} ({percent}%)",
+    "pinned.line.cost": "Cost: {cost} spent",
     "pinned.files.title": "Files ({count}):",
     "pinned.files.item": "  {path}{diff}",
     "pinned.files.more": "  ... and {count} more",
@@ -297,6 +298,11 @@ export const en = {
     "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.",
+    "commands.select_page": "Choose an OpenCode command (page {page}):",
+    "commands.button.prev_page": "⬅️ Prev",
+    "commands.button.next_page": "Next ➡️",
+    "commands.page_empty_callback": "No commands on this page",
+    "commands.page_load_error_callback": "Cannot load this page. Please try again.",
     "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

@@ -216,6 +216,7 @@ export const es = {
     "pinned.line.project": "Proyecto: {project}",
     "pinned.line.model": "Modelo: {model}",
     "pinned.line.context": "Contexto: {used} / {limit} ({percent}%)",
+    "pinned.line.cost": "Costo: {cost} gastado",
     "pinned.files.title": "Archivos ({count}):",
     "pinned.files.item": "  {path}{diff}",
     "pinned.files.more": "  ... y {count} más",
@@ -297,6 +298,11 @@ export const es = {
     "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.",
+    "commands.select_page": "Elige un comando de OpenCode (página {page}):",
+    "commands.button.prev_page": "⬅️ Anterior",
+    "commands.button.next_page": "Siguiente ➡️",
+    "commands.page_empty_callback": "No hay comandos en esta página",
+    "commands.page_load_error_callback": "No se pudo cargar esta página. Por favor, inténtalo de nuevo.",
     "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/fr.js

@@ -216,6 +216,7 @@ export const fr = {
     "pinned.line.project": "Projet : {project}",
     "pinned.line.model": "Modèle : {model}",
     "pinned.line.context": "Contexte : {used} / {limit} ({percent}%)",
+    "pinned.line.cost": "Coût : {cost} dépensé",
     "pinned.files.title": "Fichiers ({count}) :",
     "pinned.files.item": "  {path}{diff}",
     "pinned.files.more": "  ... et encore {count}",
@@ -297,6 +298,11 @@ export const fr = {
     "commands.executing_prefix": "⚡ Exécution de la commande :",
     "commands.arguments_empty": "⚠️ Les arguments ne peuvent pas être vides. Envoyez du texte ou appuyez sur Exécuter.",
     "commands.execute_error": "🔴 Impossible d'exécuter la commande OpenCode.",
+    "commands.select_page": "Choisissez une commande OpenCode (page {page}) :",
+    "commands.button.prev_page": "⬅️ Précédent",
+    "commands.button.next_page": "Suivant ➡️",
+    "commands.page_empty_callback": "Aucune commande sur cette page",
+    "commands.page_load_error_callback": "Impossible de charger cette page. Veuillez réessayer.",
     "cmd.description.rename": "Renommer la session actuelle",
     "cli.usage": "Utilisation :\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nNotes :\n  - Sans commande, `start` est utilisé par défaut\n  - `--mode` n'est actuellement pris en charge que pour `start`",
     "cli.placeholder.status": "La commande `status` est actuellement un placeholder. Les vraies vérifications d'état seront ajoutées dans la couche service (Phase 5).",

package/dist/i18n/ru.js

@@ -216,6 +216,7 @@ export const ru = {
     "pinned.line.project": "Проект: {project}",
     "pinned.line.model": "Модель: {model}",
     "pinned.line.context": "Контекст: {used} / {limit} ({percent}%)",
+    "pinned.line.cost": "Стоимость: {cost} потрачено",
     "pinned.files.title": "Файлы ({count}):",
     "pinned.files.item": "  {path}{diff}",
     "pinned.files.more": "  ... и еще {count}",
@@ -297,6 +298,11 @@ export const ru = {
     "commands.executing_prefix": "⚡ Выполнение команды:",
     "commands.arguments_empty": "⚠️ Аргументы не могут быть пустыми. Отправьте текст или нажмите Выполнить.",
     "commands.execute_error": "🔴 Не удалось выполнить команду OpenCode.",
+    "commands.select_page": "Выберите команду OpenCode (страница {page}):",
+    "commands.button.prev_page": "⬅️ Назад",
+    "commands.button.next_page": "Вперёд ➡️",
+    "commands.page_empty_callback": "На этой странице нет команд",
+    "commands.page_load_error_callback": "Не удалось загрузить эту страницу. Пожалуйста, попробуйте снова.",
     "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

@@ -216,6 +216,7 @@ export const zh = {
     "pinned.line.project": "项目: {project}",
     "pinned.line.model": "模型: {model}",
     "pinned.line.context": "上下文: {used} / {limit} ({percent}%)",
+    "pinned.line.cost": "费用: {cost}",
     "pinned.files.title": "文件（{count}）：",
     "pinned.files.item": "  {path}{diff}",
     "pinned.files.more": "  ... 还有 {count} 个",
@@ -297,10 +298,15 @@ export const zh = {
     "commands.executing_prefix": "⚡ 执行命令:",
     "commands.arguments_empty": "⚠️ 参数不能为空。请发送文本或点击执行。",
     "commands.execute_error": "🔴 执行 OpenCode 命令失败。",
+    "commands.select_page": "请选择一个 OpenCode 命令（第 {page} 页）：",
+    "commands.button.prev_page": "⬅️ 上一页",
+    "commands.button.next_page": "下一页 ➡️",
+    "commands.page_empty_callback": "这一页没有命令",
+    "commands.page_load_error_callback": "无法加载此页面。请重试。",
     "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）添加。",
-    "cli.placeholder.stop": "命令 `stop` 目前是占位符。真实的后台进程停止将会在 service 层（阶段 5）添加。",
+    "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` 命令当前为占位符。实际状态检查将在服务层中添加（第5阶段）。",
+    "cli.placeholder.stop": "`stop` 命令当前为占位符。实际后台进程停止功能将在服务层中添加（第5阶段）。",
     "cli.placeholder.unavailable": "命令不可用。",
     "cli.error.prefix": "CLI 错误：{message}",
     "cli.args.unknown_command": "未知命令：{value}",

package/dist/interaction/busy.js

@@ -0,0 +1,8 @@
+export const BUSY_ALLOWED_COMMANDS = ["/abort", "/status", "/help"];
+const BUSY_ALLOWED_COMMAND_SET = new Set(BUSY_ALLOWED_COMMANDS);
+export function isBusyAllowedCommand(command) {
+    return Boolean(command && BUSY_ALLOWED_COMMAND_SET.has(command));
+}
+export function allowsBusyInteraction(kind) {
+    return kind === "question" || kind === "permission";
+}

package/dist/interaction/guard.js

@@ -1,4 +1,6 @@
 import { interactionManager } from "./manager.js";
+import { allowsBusyInteraction, isBusyAllowedCommand } from "./busy.js";
+import { foregroundSessionState } from "../scheduled-task/foreground-state.js";
 function normalizeIncomingCommand(text) {
     const trimmed = text.trim();
     if (!trimmed.startsWith("/")) {
@@ -40,21 +42,33 @@ function getExpectedInputBlockReason(expectedInput) {
             return "expected_text";
     }
 }
-function createAllowDecision(inputType, state, command) {
+function createAllowDecision(inputType, state, command, busy) {
     return {
         allow: true,
         inputType,
         state,
         command,
+        busy,
     };
 }
-function createBlockDecision(inputType, state, reason, command) {
+function createBlockDecision(inputType, state, reason, command, busy) {
     return {
         allow: false,
         inputType,
         state,
         reason,
         command,
+        busy,
+    };
+}
+function createBusyBlockDecision(inputType, state, reason, command) {
+    return {
+        allow: false,
+        inputType,
+        state,
+        reason,
+        command,
+        busy: true,
     };
 }
 function isAllowedRenameCancelCallback(ctx, state) {
@@ -69,13 +83,35 @@ function isAllowedTaskCallback(ctx, state) {
 export function resolveInteractionGuardDecision(ctx) {
     const state = interactionManager.getSnapshot();
     const { inputType, command } = classifyIncomingInput(ctx);
+    const isBusy = foregroundSessionState.isBusy();
+    if (state && interactionManager.isExpired()) {
+        interactionManager.clear("expired");
+        return createBlockDecision(inputType, state, "expired", command, isBusy);
+    }
+    if (isBusy) {
+        if (inputType === "command") {
+            if (isBusyAllowedCommand(command)) {
+                return createAllowDecision(inputType, state, command, true);
+            }
+            return createBusyBlockDecision(inputType, state, "command_not_allowed", command);
+        }
+        if (state && allowsBusyInteraction(state.kind)) {
+            if (state.expectedInput === "mixed") {
+                if (inputType === "callback" || inputType === "text") {
+                    return createAllowDecision(inputType, state, command, true);
+                }
+                return createBusyBlockDecision(inputType, state, "expected_text", command);
+            }
+            if (state.expectedInput === inputType) {
+                return createAllowDecision(inputType, state, command, true);
+            }
+            return createBusyBlockDecision(inputType, state, getExpectedInputBlockReason(state.expectedInput), command);
+        }
+        return createBusyBlockDecision(inputType, state, "expected_text", command);
+    }
     if (!state) {
         return createAllowDecision(inputType, null, command);
     }
-    if (interactionManager.isExpired()) {
-        interactionManager.clear("expired");
-        return createBlockDecision(inputType, state, "expired", command);
-    }
     if (inputType === "command") {
         if (command === "/start") {
             return createAllowDecision(inputType, state, command);