@grinev/opencode-telegram-bot 0.20.4 → 0.20.6

package/README.md

@@ -37,7 +37,7 @@ Languages: English (`en`), Deutsch (`de`), Español (`es`), Français (`fr`), Р
 - **Skills Catalog** — browse OpenCode skills from an inline menu and run them immediately or with arguments in the next message
 - **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, and optionally enable spoken replies with `/tts`
-- **File attachments** — send images, PDF documents, and any text-based files to OpenCode (code, logs, configs etc.)
+- **File attachments** — send images, PDF documents, and text-based files to OpenCode, including multiple files in one Telegram album
 - **Scheduled tasks** — schedule prompts to run later or on a recurring interval; see [Scheduled Tasks](#scheduled-tasks)
 - **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

package/dist/bot/commands/abort.js

@@ -5,10 +5,19 @@ import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 import { foregroundSessionState } from "../../scheduled-task/foreground-state.js";
 import { assistantRunState } from "../assistant-run-state.js";
+import { markAttachedSessionIdle } from "../../attach/service.js";
+import { clearPromptResponseMode } from "../handlers/prompt.js";
+import { markUserAbortRequested } from "../utils/abort-error-suppression.js";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function abortLocalStreaming() {
     clearAllInteractionState("abort_command");
 }
+async function releaseAbortBusyState(sessionId, reason) {
+    foregroundSessionState.markIdle(sessionId);
+    assistantRunState.clearRun(sessionId, reason);
+    await markAttachedSessionIdle(sessionId);
+    clearPromptResponseMode(sessionId);
+}
 async function pollSessionStatus(sessionId, directory, maxWaitMs = 5000) {
     const startedAt = Date.now();
     const pollIntervalMs = 500;
@@ -61,6 +70,7 @@ export async function abortCurrentOperation(ctx, options = {}) {
         }
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), 5000);
+        markUserAbortRequested(currentSession.id);
         try {
             const { data: abortResult, error: abortError } = await opencodeClient.session.abort({
                 sessionID: currentSession.id,
@@ -69,12 +79,14 @@ export async function abortCurrentOperation(ctx, options = {}) {
             clearTimeout(timeoutId);
             if (abortError) {
                 logger.warn("[Abort] Abort request failed:", abortError);
+                await releaseAbortBusyState(currentSession.id, "abort_unconfirmed");
                 if (notifyUser && chatId !== null && waitingMessageId !== null) {
                     await ctx.api.editMessageText(chatId, waitingMessageId, t("stop.warn_unconfirmed"));
                 }
                 return;
             }
             if (abortResult !== true) {
+                await releaseAbortBusyState(currentSession.id, "abort_maybe_finished");
                 if (notifyUser && chatId !== null && waitingMessageId !== null) {
                     await ctx.api.editMessageText(chatId, waitingMessageId, t("stop.warn_maybe_finished"));
                 }
@@ -82,8 +94,7 @@ export async function abortCurrentOperation(ctx, options = {}) {
             }
             const finalStatus = await pollSessionStatus(currentSession.id, currentSession.directory, 5000);
             if (finalStatus === "idle" || finalStatus === "not-found") {
-                foregroundSessionState.markIdle(currentSession.id);
-                assistantRunState.clearRun(currentSession.id, "abort_confirmed");
+                await releaseAbortBusyState(currentSession.id, "abort_confirmed");
                 if (notifyUser && chatId !== null && waitingMessageId !== null) {
                     await ctx.api.editMessageText(chatId, waitingMessageId, t("stop.success"));
                 }
@@ -96,6 +107,7 @@ export async function abortCurrentOperation(ctx, options = {}) {
         }
         catch (error) {
             clearTimeout(timeoutId);
+            await releaseAbortBusyState(currentSession.id, "abort_error");
             if (error instanceof Error && error.name === "AbortError") {
                 if (notifyUser && chatId !== null && waitingMessageId !== null) {
                     await ctx.api.editMessageText(chatId, waitingMessageId, t("stop.warn_timeout"));

package/dist/bot/commands/opencode-start.js

@@ -5,6 +5,43 @@ import { opencodeReadyLifecycle } from "../../opencode/ready-lifecycle.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 import { editBotText } from "../utils/telegram-text.js";
+const SERVER_READY_TIMEOUT_MS = 10_000;
+const SERVER_READY_POLL_INTERVAL_MS = 500;
+const HEALTH_CHECK_TIMEOUT_MS = 3_000;
+const HEALTH_CHECK_TIMED_OUT = Symbol("health-check-timed-out");
+async function healthWithTimeout(timeoutMs = HEALTH_CHECK_TIMEOUT_MS) {
+    const controller = new AbortController();
+    let timeout;
+    try {
+        return await Promise.race([
+            opencodeClient.global.health({ signal: controller.signal }),
+            new Promise((resolve) => {
+                timeout = setTimeout(() => {
+                    controller.abort();
+                    resolve(HEALTH_CHECK_TIMED_OUT);
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
+async function getHealthIfAvailable() {
+    try {
+        const result = await healthWithTimeout();
+        if (result === HEALTH_CHECK_TIMED_OUT) {
+            logger.warn(`[Bot] OpenCode health check timed out after ${HEALTH_CHECK_TIMEOUT_MS}ms`);
+            return null;
+        }
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Wait for OpenCode server to become ready by polling health endpoint
  * @param maxWaitMs Maximum time to wait in milliseconds
@@ -12,18 +49,12 @@ import { editBotText } from "../utils/telegram-text.js";
  */
 async function waitForServerReady(maxWaitMs = 10000) {
     const startTime = Date.now();
-    const pollInterval = 500;
     while (Date.now() - startTime < maxWaitMs) {
-        try {
-            const { data, error } = await opencodeClient.global.health();
-            if (!error && data?.healthy) {
-                return true;
-            }
-        }
-        catch {
-            // Server not ready yet
+        const health = await getHealthIfAvailable();
+        if (health?.data?.healthy) {
+            return true;
         }
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        await new Promise((resolve) => setTimeout(resolve, SERVER_READY_POLL_INTERVAL_MS));
     }
     return false;
 }
@@ -40,8 +71,9 @@ export async function opencodeStartCommand(ctx) {
         }
         // Check if server is already accessible.
         try {
-            const { data, error } = await opencodeClient.global.health();
-            if (!error && data?.healthy) {
+            const health = await getHealthIfAvailable();
+            const data = health?.data;
+            if (data?.healthy) {
                 await ctx.reply(t("opencode_start.already_running", { version: data.version || t("common.unknown") }));
                 await opencodeReadyLifecycle.notifyReady("opencode_start_already_running");
                 return;
@@ -67,7 +99,7 @@ export async function opencodeStartCommand(ctx) {
         }
         childProcess.unref();
         logger.info("[Bot] Waiting for OpenCode server to become ready...");
-        const ready = await waitForServerReady(10000);
+        const ready = await waitForServerReady(SERVER_READY_TIMEOUT_MS);
         if (!ready) {
             await editBotText({
                 api: ctx.api,
@@ -79,7 +111,7 @@ export async function opencodeStartCommand(ctx) {
             });
             return;
         }
-        const { data: health } = await opencodeClient.global.health();
+        const health = (await getHealthIfAvailable())?.data;
         await editBotText({
             api: ctx.api,
             chatId: ctx.chat.id,

package/dist/bot/handlers/document.js

@@ -32,6 +32,30 @@ export async function handleDocumentMessage(ctx, deps) {
             await processPrompt(ctx, promptWithFile, deps);
             return;
         }
+        if (mimeType.startsWith("image/")) {
+            const storedModel = getStored();
+            const capabilities = await getCapabilities(storedModel.providerID, storedModel.modelID);
+            if (!supportsInput(capabilities, "image")) {
+                logger.warn(`[Document] Model ${storedModel.providerID}/${storedModel.modelID} doesn't support image input`);
+                await ctx.reply(t("bot.photo_model_no_image"));
+                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 image (${downloadedFile.buffer.length} bytes, ${filename}, ${mimeType}) with prompt`);
+            await processPrompt(ctx, caption, deps, [filePart]);
+            return;
+        }
         if (mimeType === "application/pdf") {
             const storedModel = getStored();
             const capabilities = await getCapabilities(storedModel.providerID, storedModel.modelID);
@@ -56,7 +80,8 @@ export async function handleDocumentMessage(ctx, deps) {
             await processPrompt(ctx, caption, deps, [filePart]);
             return;
         }
-        logger.debug(`[Document] Unsupported document MIME type: ${mimeType}, ignoring`);
+        logger.warn(`[Document] Unsupported document MIME type: ${mimeType}, filename=${filename}`);
+        await ctx.reply(t("bot.file_type_unsupported"));
     }
     catch (err) {
         logger.error("[Document] Error handling document message:", err);

package/dist/bot/handlers/media-group.js

@@ -0,0 +1,220 @@
+import { config } from "../../config.js";
+import { t } from "../../i18n/index.js";
+import { getModelCapabilities, supportsInput } from "../../model/capabilities.js";
+import { getStoredModel } from "../../model/manager.js";
+import { logger } from "../../utils/logger.js";
+import { downloadTelegramFile, isFileSizeAllowed, isTextMimeType, toDataUri, } from "../utils/file-download.js";
+import { processUserPrompt } from "./prompt.js";
+const DEFAULT_MEDIA_GROUP_DEBOUNCE_MS = 1_000;
+export class MediaGroupAttachmentHandler {
+    deps;
+    debounceMs;
+    batches = new Map();
+    constructor(deps, options = {}) {
+        this.deps = deps;
+        this.debounceMs = options.debounceMs ?? DEFAULT_MEDIA_GROUP_DEBOUNCE_MS;
+    }
+    async handle(ctx, next) {
+        const item = this.createPendingItem(ctx);
+        if (!item) {
+            await next();
+            return;
+        }
+        const mediaGroupId = ctx.message?.media_group_id;
+        const chatId = ctx.chat?.id;
+        if (!mediaGroupId || chatId === undefined) {
+            await next();
+            return;
+        }
+        const key = this.getBatchKey(chatId, mediaGroupId);
+        const existingBatch = this.batches.get(key);
+        if (existingBatch) {
+            clearTimeout(existingBatch.timer);
+            existingBatch.items.push(item);
+            existingBatch.timer = this.createFlushTimer(key);
+            return;
+        }
+        this.batches.set(key, {
+            items: [item],
+            timer: this.createFlushTimer(key),
+        });
+    }
+    async flushAll() {
+        const keys = Array.from(this.batches.keys());
+        await Promise.all(keys.map((key) => this.flushBatch(key)));
+    }
+    createPendingItem(ctx) {
+        const message = ctx.message;
+        const mediaGroupId = message?.media_group_id;
+        if (!message || !mediaGroupId || !ctx.chat) {
+            return null;
+        }
+        const baseItem = {
+            ctx,
+            messageId: message.message_id,
+            caption: message.caption || "",
+        };
+        if (message.photo && message.photo.length > 0) {
+            return {
+                ...baseItem,
+                kind: "photo",
+                photos: message.photo,
+            };
+        }
+        if (message.document) {
+            return {
+                ...baseItem,
+                kind: "document",
+                document: message.document,
+            };
+        }
+        return {
+            ...baseItem,
+            kind: "unsupported",
+        };
+    }
+    getBatchKey(chatId, mediaGroupId) {
+        return `${chatId}:${mediaGroupId}`;
+    }
+    createFlushTimer(key) {
+        return setTimeout(() => {
+            void this.flushBatch(key);
+        }, this.debounceMs);
+    }
+    async flushBatch(key) {
+        const batch = this.batches.get(key);
+        if (!batch) {
+            return;
+        }
+        clearTimeout(batch.timer);
+        this.batches.delete(key);
+        const items = [...batch.items].sort((left, right) => left.messageId - right.messageId);
+        const replyCtx = items[0]?.ctx;
+        if (!replyCtx) {
+            return;
+        }
+        logger.info(`[MediaGroup] Processing Telegram media group: key=${key}, items=${items.length}`);
+        try {
+            const validationResult = await this.validateItems(items);
+            if ("reason" in validationResult) {
+                logger.warn(`[MediaGroup] Rejecting media group: key=${key}, reason=${validationResult.reason}`);
+                await replyCtx.reply(t("bot.media_group_not_processed"));
+                return;
+            }
+            await replyCtx.reply(t("bot.files_downloading"));
+            const { promptText, fileParts } = await this.preparePrompt(validationResult.items, items);
+            const processPrompt = this.deps.processPrompt ?? processUserPrompt;
+            logger.info(`[MediaGroup] Sending media group as one prompt: key=${key}, files=${fileParts.length}, textLength=${promptText.length}`);
+            await processPrompt(replyCtx, promptText, this.deps, fileParts);
+        }
+        catch (err) {
+            logger.error(`[MediaGroup] Failed to process media group: key=${key}`, err);
+            await replyCtx.reply(t("bot.media_group_download_error"));
+        }
+    }
+    async validateItems(items) {
+        const storedModel = (this.deps.getStoredModel ?? getStoredModel)();
+        const validItems = [];
+        let needsImageSupport = false;
+        let needsPdfSupport = false;
+        for (const item of items) {
+            if (item.kind === "unsupported") {
+                return { reason: "unsupported_media_kind" };
+            }
+            if (item.kind === "photo") {
+                needsImageSupport = true;
+                const largestPhoto = item.photos[item.photos.length - 1];
+                validItems.push({
+                    kind: "file",
+                    ctx: item.ctx,
+                    messageId: item.messageId,
+                    fileId: largestPhoto.file_id,
+                    mime: "image/jpeg",
+                    filename: `photo-${item.messageId}.jpg`,
+                });
+                continue;
+            }
+            const document = item.document;
+            const mimeType = document.mime_type || "";
+            const filename = document.file_name || "document";
+            if (isTextMimeType(mimeType)) {
+                if (!isFileSizeAllowed(document.file_size, config.files.maxFileSizeKb)) {
+                    return { reason: "text_file_too_large" };
+                }
+                validItems.push({
+                    kind: "text",
+                    ctx: item.ctx,
+                    fileId: document.file_id,
+                    filename,
+                });
+                continue;
+            }
+            if (mimeType.startsWith("image/")) {
+                needsImageSupport = true;
+                validItems.push({
+                    kind: "file",
+                    ctx: item.ctx,
+                    messageId: item.messageId,
+                    fileId: document.file_id,
+                    mime: mimeType,
+                    filename,
+                });
+                continue;
+            }
+            if (mimeType === "application/pdf") {
+                needsPdfSupport = true;
+                validItems.push({
+                    kind: "file",
+                    ctx: item.ctx,
+                    messageId: item.messageId,
+                    fileId: document.file_id,
+                    mime: mimeType,
+                    filename,
+                });
+                continue;
+            }
+            return { reason: `unsupported_document_mime:${mimeType || "unknown"}` };
+        }
+        if (needsImageSupport || needsPdfSupport) {
+            const getCapabilities = this.deps.getModelCapabilities ?? getModelCapabilities;
+            const capabilities = await getCapabilities(storedModel.providerID, storedModel.modelID);
+            if (needsImageSupport && !supportsInput(capabilities, "image")) {
+                return { reason: `model_no_image:${storedModel.providerID}/${storedModel.modelID}` };
+            }
+            if (needsPdfSupport && !supportsInput(capabilities, "pdf")) {
+                return { reason: `model_no_pdf:${storedModel.providerID}/${storedModel.modelID}` };
+            }
+        }
+        return { items: validItems };
+    }
+    async preparePrompt(validItems, originalItems) {
+        const downloadFile = this.deps.downloadFile ?? downloadTelegramFile;
+        const textSections = [];
+        const fileParts = [];
+        for (const item of validItems) {
+            const downloadedFile = await downloadFile(item.ctx.api, item.fileId);
+            if (item.kind === "text") {
+                const textContent = downloadedFile.buffer.toString("utf-8");
+                textSections.push(`--- Content of ${item.filename} ---\n${textContent}\n--- End of file ---`);
+                continue;
+            }
+            fileParts.push({
+                type: "file",
+                mime: item.mime,
+                filename: item.filename,
+                url: toDataUri(downloadedFile.buffer, item.mime),
+            });
+        }
+        const captions = originalItems
+            .map((item) => item.caption.trim())
+            .filter((caption) => caption.length > 0);
+        return {
+            promptText: [...textSections, ...captions].join("\n\n"),
+            fileParts,
+        };
+    }
+}
+export function createMediaGroupAttachmentMiddleware(deps, options = {}) {
+    const handler = new MediaGroupAttachmentHandler(deps, options);
+    return (ctx, next) => handler.handle(ctx, next);
+}

package/dist/bot/handlers/prompt.js

@@ -167,7 +167,8 @@ export async function processUserPrompt(ctx, text, deps, fileParts = [], options
         if (parts.length === 0 || (parts.length > 0 && parts.every((p) => p.type === "file"))) {
             if (fileParts.length > 0) {
                 // Files without text - add a minimal system prompt
-                parts.unshift({ type: "text", text: "See attached file" });
+                const attachmentText = fileParts.length === 1 ? "See attached file" : "See attached files";
+                parts.unshift({ type: "text", text: attachmentText });
             }
         }
         const promptOptions = {

package/dist/bot/index.js

@@ -57,11 +57,13 @@ import { createTelegramBotOptions } from "./telegram-client-options.js";
 import { clearPromptResponseMode, processUserPrompt } from "./handlers/prompt.js";
 import { handleVoiceMessage } from "./handlers/voice.js";
 import { handleDocumentMessage } from "./handlers/document.js";
+import { createMediaGroupAttachmentMiddleware } from "./handlers/media-group.js";
 import { downloadTelegramFile, toDataUri } from "./utils/file-download.js";
 import { reconcileBusyState } from "./utils/busy-reconciliation.js";
 import { finalizeAssistantResponse } from "./utils/finalize-assistant-response.js";
 import { sendTtsResponseForSession } from "./utils/send-tts-response.js";
 import { deliverThinkingMessage } from "./utils/thinking-message.js";
+import { shouldSuppressUserAbortSessionError } from "./utils/abort-error-suppression.js";
 import { editRenderedBotPart, getTelegramRenderedPartSignature, sendRenderedBotPart, } from "./utils/telegram-text.js";
 import { formatAssistantRunFooter } from "./utils/assistant-run-footer.js";
 import { getModelCapabilities, supportsInput } from "../model/capabilities.js";
@@ -592,14 +594,16 @@ async function ensureEventSubscription(directory) {
             return;
         }
         const currentSession = getCurrentSession();
-        if (!currentSession || currentSession.id !== request.sessionID) {
+        const isCurrent = currentSession?.id === request.sessionID;
+        const isSubagent = summaryAggregator.isSubagentSession(request.sessionID);
+        if (!currentSession || (!isCurrent && !isSubagent)) {
             return;
         }
         await Promise.all([
             toolMessageBatcher.flushSession(request.sessionID, "permission_asked"),
             toolCallStreamer.flushSession(request.sessionID, "permission_asked"),
         ]);
-        logger.info(`[Bot] Received permission request from agent: type=${request.permission}, requestID=${request.id}`);
+        logger.info(`[Bot] Received permission request from agent: type=${request.permission}, requestID=${request.id}, subagent=${isSubagent}`);
         await showPermissionRequest(botInstance.api, chatIdInstance, request);
     });
     summaryAggregator.setOnThinking(async (sessionId) => {
@@ -745,6 +749,12 @@ async function ensureEventSubscription(directory) {
             toolCallStreamer.flushSession(sessionId, "session_error"),
         ]);
         const normalizedMessage = message.trim() || t("common.unknown_error");
+        if (shouldSuppressUserAbortSessionError(sessionId, normalizedMessage)) {
+            logger.debug(`[Bot] Suppressed user-initiated abort error: session=${sessionId}`);
+            foregroundSessionState.markIdle(sessionId);
+            await scheduledTaskRuntime.flushDeferredDeliveries();
+            return;
+        }
         const truncatedMessage = normalizedMessage.length > 3500
             ? `${normalizedMessage.slice(0, 3497)}...`
             : normalizedMessage;
@@ -1096,6 +1106,7 @@ export function createBot() {
         chatIdInstance = ctx.chat.id;
         await handleVoiceMessage(ctx, voicePromptDeps);
     });
+    bot.on("message", createMediaGroupAttachmentMiddleware({ bot, ensureEventSubscription }));
     // Photo message handler
     bot.on("message:photo", async (ctx) => {
         logger.debug(`[Bot] Received photo message, chatId=${ctx.chat.id}`);

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

@@ -1,4 +1,5 @@
 import { resolveInteractionGuardDecision } from "../../interaction/guard.js";
+import { reconcileForegroundBusyState } from "../utils/busy-guard.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 function getInteractionBlockedMessage(reason, interactionKind) {
@@ -72,7 +73,11 @@ function getInteractionBlockedMessage(reason, interactionKind) {
     }
 }
 export async function interactionGuardMiddleware(ctx, next) {
-    const decision = resolveInteractionGuardDecision(ctx);
+    let decision = resolveInteractionGuardDecision(ctx);
+    if (!decision.allow && decision.busy) {
+        await reconcileForegroundBusyState();
+        decision = resolveInteractionGuardDecision(ctx);
+    }
     if (decision.allow) {
         await next();
         return;

package/dist/bot/utils/abort-error-suppression.js

@@ -0,0 +1,32 @@
+// Covers abort request timeout, post-abort status polling, and delayed SSE reconnect delivery.
+const USER_ABORT_SUPPRESSION_WINDOW_MS = 90_000;
+const userAbortRequestedAtBySession = new Map();
+function deleteExpiredAbortRequests(now = Date.now()) {
+    for (const [sessionId, requestedAt] of userAbortRequestedAtBySession) {
+        if (now - requestedAt > USER_ABORT_SUPPRESSION_WINDOW_MS) {
+            userAbortRequestedAtBySession.delete(sessionId);
+        }
+    }
+}
+export function markUserAbortRequested(sessionId) {
+    const now = Date.now();
+    deleteExpiredAbortRequests(now);
+    userAbortRequestedAtBySession.set(sessionId, now);
+}
+export function shouldSuppressUserAbortSessionError(sessionId, message) {
+    if (message.trim().toLowerCase() !== "aborted") {
+        return false;
+    }
+    const requestedAt = userAbortRequestedAtBySession.get(sessionId);
+    if (requestedAt === undefined) {
+        return false;
+    }
+    userAbortRequestedAtBySession.delete(sessionId);
+    return Date.now() - requestedAt <= USER_ABORT_SUPPRESSION_WINDOW_MS;
+}
+export function __resetUserAbortErrorSuppressionForTests() {
+    userAbortRequestedAtBySession.clear();
+}
+export function __getUserAbortErrorSuppressionSizeForTests() {
+    return userAbortRequestedAtBySession.size;
+}

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

@@ -1,9 +1,35 @@
 import { foregroundSessionState } from "../../scheduled-task/foreground-state.js";
 import { attachManager } from "../../attach/manager.js";
+import { reconcileBusyStateNow } from "./busy-reconciliation.js";
 import { t } from "../../i18n/index.js";
+import { logger } from "../../utils/logger.js";
 export function isForegroundBusy() {
     return foregroundSessionState.isBusy() || attachManager.isBusy();
 }
+function getBusyDirectories() {
+    const directories = new Set();
+    for (const session of foregroundSessionState.getBusySessions()) {
+        directories.add(session.directory);
+    }
+    const attached = attachManager.getSnapshot();
+    if (attached?.busy) {
+        directories.add(attached.directory);
+    }
+    return [...directories];
+}
+export async function reconcileForegroundBusyState() {
+    if (!isForegroundBusy()) {
+        return;
+    }
+    for (const directory of getBusyDirectories()) {
+        try {
+            await reconcileBusyStateNow(directory);
+        }
+        catch (error) {
+            logger.warn("[BusyGuard] Failed to reconcile foreground busy state", error);
+        }
+    }
+}
 export async function replyBusyBlocked(ctx) {
     const message = t("bot.session_busy");
     if (ctx.callbackQuery) {

package/dist/i18n/de.js

@@ -64,8 +64,12 @@ export const de = {
     "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.files_downloading": "⏳ Lade Dateien herunter...",
     "bot.file_too_large": "⚠️ Datei ist zu groß (max. {maxSizeMb}MB)",
     "bot.file_download_error": "🔴 Datei konnte nicht heruntergeladen werden",
+    "bot.file_type_unsupported": "⚠️ Dieser Dateityp wird nicht unterstützt. Sende ein Bild, PDF oder eine Text-/Code-Datei.",
+    "bot.media_group_not_processed": "⚠️ Eine oder mehrere Dateien in diesem Album können nicht verarbeitet werden. Es wurde nichts an OpenCode gesendet.",
+    "bot.media_group_download_error": "🔴 Eine der Dateien konnte nicht heruntergeladen werden. Es wurde nichts an OpenCode gesendet.",
     "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",

package/dist/i18n/en.js

@@ -64,8 +64,12 @@ export const en = {
     "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.files_downloading": "⏳ Downloading files...",
     "bot.file_too_large": "⚠️ File is too large (max {maxSizeMb}MB)",
     "bot.file_download_error": "🔴 Failed to download file",
+    "bot.file_type_unsupported": "⚠️ This file type is not supported. Send an image, PDF, or text/code file.",
+    "bot.media_group_not_processed": "⚠️ One or more files in this album cannot be processed. Nothing was sent to OpenCode.",
+    "bot.media_group_download_error": "🔴 Failed to download one of the files. Nothing was sent to OpenCode.",
     "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",

package/dist/i18n/es.js

@@ -64,8 +64,12 @@ export const es = {
     "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.files_downloading": "⏳ Descargando archivos...",
     "bot.file_too_large": "⚠️ El archivo es demasiado grande (max {maxSizeMb}MB)",
     "bot.file_download_error": "🔴 No se pudo descargar el archivo",
+    "bot.file_type_unsupported": "⚠️ Este tipo de archivo no es compatible. Envía una imagen, PDF o archivo de texto/código.",
+    "bot.media_group_not_processed": "⚠️ Uno o más archivos de este álbum no se pueden procesar. No se envió nada a OpenCode.",
+    "bot.media_group_download_error": "🔴 No se pudo descargar uno de los archivos. No se envió nada a OpenCode.",
     "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",

package/dist/i18n/fr.js

@@ -64,8 +64,12 @@ export const fr = {
     "bot.photo_download_error": "🔴 Impossible de télécharger la photo",
     "bot.photo_no_caption": "💡 Conseil : ajoutez une légende pour décrire ce que vous voulez faire avec cette photo.",
     "bot.file_downloading": "⏳ Téléchargement du fichier...",
+    "bot.files_downloading": "⏳ Téléchargement des fichiers...",
     "bot.file_too_large": "⚠️ Le fichier est trop volumineux (max {maxSizeMb}MB)",
     "bot.file_download_error": "🔴 Impossible de télécharger le fichier",
+    "bot.file_type_unsupported": "⚠️ Ce type de fichier n'est pas pris en charge. Envoyez une image, un PDF ou un fichier texte/code.",
+    "bot.media_group_not_processed": "⚠️ Un ou plusieurs fichiers de cet album ne peuvent pas être traités. Rien n'a été envoyé à OpenCode.",
+    "bot.media_group_download_error": "🔴 Impossible de télécharger l'un des fichiers. Rien n'a été envoyé à OpenCode.",
     "bot.model_no_pdf": "⚠️ Le modèle actuel ne prend pas en charge les PDF. Envoi du texte uniquement.",
     "bot.text_file_too_large": "⚠️ Le fichier texte est trop volumineux (max {maxSizeKb}KB)",
     "status.header_running": "🟢 Le serveur OpenCode est en cours d'exécution",

package/dist/i18n/ru.js

@@ -64,8 +64,12 @@ export const ru = {
     "bot.photo_download_error": "🔴 Не удалось скачать фото",
     "bot.photo_no_caption": "💡 Совет: Добавьте подпись, чтобы описать, что делать с этим фото.",
     "bot.file_downloading": "⏳ Скачиваю файл...",
+    "bot.files_downloading": "⏳ Скачиваю файлы...",
     "bot.file_too_large": "⚠️ Файл слишком большой (макс. {maxSizeMb}МБ)",
     "bot.file_download_error": "🔴 Не удалось скачать файл",
+    "bot.file_type_unsupported": "⚠️ Этот тип файла не поддерживается. Отправьте изображение, PDF или текстовый/кодовый файл.",
+    "bot.media_group_not_processed": "⚠️ Один или несколько файлов в альбоме нельзя обработать. В OpenCode ничего не отправлено.",
+    "bot.media_group_download_error": "🔴 Не удалось скачать один из файлов. В OpenCode ничего не отправлено.",
     "bot.model_no_pdf": "⚠️ Текущая модель не поддерживает PDF. Отправляю только текст.",
     "bot.text_file_too_large": "⚠️ Текстовый файл слишком большой (макс. {maxSizeKb}КБ)",
     "status.header_running": "🟢 OpenCode Server запущен",

package/dist/i18n/zh.js

@@ -64,8 +64,12 @@ export const zh = {
     "bot.photo_download_error": "🔴 下载照片失败",
     "bot.photo_no_caption": "💡 提示：添加说明文字以描述你希望对这张照片做什么。",
     "bot.file_downloading": "⏳ 正在下载文件...",
+    "bot.files_downloading": "⏳ 正在下载文件...",
     "bot.file_too_large": "⚠️ 文件过大（最大 {maxSizeMb}MB）",
     "bot.file_download_error": "🔴 下载文件失败",
+    "bot.file_type_unsupported": "⚠️ 不支持此文件类型。请发送图片、PDF 或文本/代码文件。",
+    "bot.media_group_not_processed": "⚠️ 此相册中有一个或多个文件无法处理。未向 OpenCode 发送任何内容。",
+    "bot.media_group_download_error": "🔴 无法下载其中一个文件。未向 OpenCode 发送任何内容。",
     "bot.model_no_pdf": "⚠️ 当前模型不支持PDF输入。将仅发送文本。",
     "bot.text_file_too_large": "⚠️ 文本文件过大（最大 {maxSizeKb}KB）",
     "status.header_running": "🟢 OpenCode 服务器正在运行",

package/dist/opencode/events.js

@@ -3,7 +3,9 @@ import { logger } from "../utils/logger.js";
 import { isExpectedOpencodeUnavailableError } from "../utils/opencode-error.js";
 const RECONNECT_BASE_DELAY_MS = 1000;
 const RECONNECT_MAX_DELAY_MS = 15000;
+let sseIdleTimeoutMs = 30_000;
 const FATAL_NO_STREAM_ERROR = "No stream returned from event subscription";
+const SSE_IDLE_TIMEOUT_ERROR = "SSE stream idle timeout";
 let eventStream = null;
 let eventCallback = null;
 let isListening = false;
@@ -32,6 +34,44 @@ function waitWithAbort(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
+function createAttemptAbortController(parentSignal) {
+    const controller = new AbortController();
+    if (parentSignal.aborted) {
+        controller.abort();
+        return { controller, cleanup: () => { } };
+    }
+    const onAbort = () => controller.abort();
+    parentSignal.addEventListener("abort", onAbort, { once: true });
+    return {
+        controller,
+        cleanup: () => parentSignal.removeEventListener("abort", onAbort),
+    };
+}
+function readStreamWithIdleTimeout(stream, signal) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        const onAbort = () => finish({ type: "aborted" });
+        const timeout = setTimeout(() => finish({ type: "timeout" }), sseIdleTimeoutMs);
+        if (signal.aborted) {
+            finish({ type: "aborted" });
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+        stream.next().then((result) => finish({ type: "next", result }), (error) => finish({ type: "error", error }));
+    });
+}
+function isEventStreamIdleTimeoutError(error) {
+    return error instanceof Error && error.message === SSE_IDLE_TIMEOUT_ERROR;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -114,15 +154,17 @@ export async function subscribeToEvents(directory, callback) {
         let reconnectAttempt = 0;
         let useLegacyEventsOnce = false;
         while (isListening && activeDirectory === directory && !controller.signal.aborted) {
+            let attemptAbort = null;
             try {
                 let subscription;
+                attemptAbort = createAttemptAbortController(controller.signal);
                 if (useLegacyEventsOnce) {
                     useLegacyEventsOnce = false;
-                    subscription = await subscribeToLegacyEventStream(directory, controller.signal);
+                    subscription = await subscribeToLegacyEventStream(directory, attemptAbort.controller.signal);
                 }
                 else {
                     try {
-                        subscription = await subscribeToGlobalEventStream(controller.signal);
+                        subscription = await subscribeToGlobalEventStream(attemptAbort.controller.signal);
                         logger.debug(`Using global OpenCode event stream for ${directory}`);
                     }
                     catch (error) {
@@ -133,43 +175,67 @@ export async function subscribeToEvents(directory, callback) {
                             throw error;
                         }
                         logger.warn(`Global event stream unavailable for ${directory}, falling back to project event stream`, error);
-                        subscription = await subscribeToLegacyEventStream(directory, controller.signal);
+                        subscription = await subscribeToLegacyEventStream(directory, attemptAbort.controller.signal);
                     }
                 }
                 reconnectAttempt = 0;
                 eventStream = subscription.stream;
                 let usefulEventCount = 0;
-                for await (const event of eventStream) {
-                    if (!isListening || activeDirectory !== directory || controller.signal.aborted) {
-                        logger.debug(`Event listener stopped or changed directory, breaking loop`);
-                        break;
-                    }
-                    // CRITICAL: Explicitly yield to the event loop BEFORE processing the event
-                    // This allows grammY to handle getUpdates between SSE events
-                    await new Promise((resolve) => setImmediate(resolve));
-                    const normalizedEvent = normalizeEvent(event, subscription.source, directory);
-                    if (!normalizedEvent) {
-                        continue;
-                    }
-                    if (normalizedEvent.type !== "server.connected") {
-                        usefulEventCount++;
-                    }
-                    if (eventCallback) {
-                        // Use setImmediate to avoid blocking the event loop
-                        // and let grammY process incoming Telegram updates
-                        const callbackSnapshot = eventCallback;
-                        setImmediate(() => {
-                            if (streamAbortController !== controller ||
-                                controller.signal.aborted ||
-                                !isListening ||
-                                activeDirectory !== directory ||
-                                listenerGeneration !== generation) {
-                                return;
-                            }
-                            callbackSnapshot(normalizedEvent);
-                        });
+                try {
+                    while (isListening && activeDirectory === directory && !controller.signal.aborted) {
+                        const readResult = await readStreamWithIdleTimeout(eventStream, attemptAbort.controller.signal);
+                        if (readResult.type === "aborted") {
+                            logger.debug(`Event listener stopped or changed directory, breaking loop`);
+                            break;
+                        }
+                        if (readResult.type === "timeout") {
+                            attemptAbort.controller.abort();
+                            const closeStream = eventStream.return?.(undefined);
+                            void closeStream?.catch(() => undefined);
+                            throw new Error(SSE_IDLE_TIMEOUT_ERROR);
+                        }
+                        if (readResult.type === "error") {
+                            throw readResult.error;
+                        }
+                        if (readResult.result.done) {
+                            break;
+                        }
+                        const event = readResult.result.value;
+                        // CRITICAL: Explicitly yield to the event loop BEFORE processing the event
+                        // This allows grammY to handle getUpdates between SSE events
+                        await new Promise((resolve) => setImmediate(resolve));
+                        const normalizedEvent = normalizeEvent(event, subscription.source, directory);
+                        if (!normalizedEvent) {
+                            continue;
+                        }
+                        if (normalizedEvent.type !== "server.connected") {
+                            usefulEventCount++;
+                        }
+                        if (eventCallback) {
+                            // Use setImmediate to avoid blocking the event loop
+                            // and let grammY process incoming Telegram updates
+                            const callbackSnapshot = eventCallback;
+                            setImmediate(() => {
+                                if (streamAbortController !== controller ||
+                                    controller.signal.aborted ||
+                                    !isListening ||
+                                    activeDirectory !== directory ||
+                                    listenerGeneration !== generation) {
+                                    return;
+                                }
+                                try {
+                                    callbackSnapshot(normalizedEvent);
+                                }
+                                catch (error) {
+                                    logger.error("[Events] Callback failed:", error);
+                                }
+                            });
+                        }
                     }
                 }
+                finally {
+                    attemptAbort.cleanup();
+                }
                 eventStream = null;
                 if (!isListening || activeDirectory !== directory || controller.signal.aborted) {
                     break;
@@ -188,6 +254,7 @@ export async function subscribeToEvents(directory, callback) {
                 }
             }
             catch (error) {
+                attemptAbort?.cleanup();
                 eventStream = null;
                 if (controller.signal.aborted || !isListening || activeDirectory !== directory) {
                     logger.info("Event listener aborted");
@@ -199,7 +266,10 @@ export async function subscribeToEvents(directory, callback) {
                 }
                 reconnectAttempt++;
                 const reconnectDelay = getReconnectDelayMs(reconnectAttempt);
-                if (isExpectedOpencodeUnavailableError(error)) {
+                if (isEventStreamIdleTimeoutError(error)) {
+                    logger.warn(`Event stream idle timeout for ${directory}, reconnecting in ${reconnectDelay}ms (attempt=${reconnectAttempt})`);
+                }
+                else if (isExpectedOpencodeUnavailableError(error)) {
                     logger.warn(`Event stream unavailable for ${directory}, reconnecting in ${reconnectDelay}ms (attempt=${reconnectAttempt})`);
                 }
                 else {
@@ -251,3 +321,6 @@ export function stopEventListening() {
     activeDirectory = null;
     logger.info("Event listener stopped");
 }
+export function __setSseIdleTimeoutForTests(timeoutMs) {
+    sseIdleTimeoutMs = timeoutMs;
+}

package/dist/scheduled-task/executor.js

@@ -94,9 +94,26 @@ function findLatestAssistantMessage(messages) {
     }
     return null;
 }
+function getAssistantFinishReason(message) {
+    for (let index = message.parts.length - 1; index >= 0; index -= 1) {
+        const part = message.parts[index];
+        if (part?.type === "step-finish" && typeof part.reason === "string" && part.reason.trim()) {
+            return part.reason.trim();
+        }
+    }
+    if (typeof message.info.finish === "string" && message.info.finish.trim()) {
+        return message.info.finish.trim();
+    }
+    return null;
+}
 function extractAssistantResult(message) {
     if (!message) {
-        return { resultText: null, errorMessage: null, completed: false, message: null };
+        return {
+            resultText: null,
+            errorMessage: null,
+            completed: false,
+            message: null,
+        };
     }
     const errorMessage = extractErrorMessage(message.info.error);
     if (errorMessage) {
@@ -108,10 +125,13 @@ function extractAssistantResult(message) {
         };
     }
     const resultText = collectResponseText(message.parts);
+    const completed = Boolean(message.info.time?.completed);
+    const finishReason = getAssistantFinishReason(message);
+    const awaitingToolCalls = completed && finishReason === "tool-calls";
     return {
-        resultText,
+        resultText: awaitingToolCalls ? null : resultText,
         errorMessage: null,
-        completed: Boolean(message.info.time?.completed),
+        completed: completed && !awaitingToolCalls,
         message,
     };
 }
@@ -120,6 +140,7 @@ function summarizeAssistantParts(parts) {
         id: part.id,
         type: part.type,
         ignored: part.ignored,
+        reason: part.reason,
         ...(typeof part.text === "string" ? { textLength: part.text.length } : {}),
         ...(part.tool ? { tool: part.tool } : {}),
         ...(part.state?.status ? { status: part.state.status } : {}),
@@ -136,6 +157,7 @@ function logEmptyAssistantResponseDiagnostics(taskId, sessionId, directory, mess
                 id: message.info.id,
                 completed: Boolean(message.info.time?.completed),
                 summary: Boolean(message.info.summary),
+                finish: getAssistantFinishReason(message),
                 errorMessage: extractErrorMessage(message.info.error),
                 parts: summarizeAssistantParts(message.parts),
             }

package/dist/summary/aggregator.js

@@ -270,6 +270,12 @@ class SummaryAggregator {
     isTrackedChildSession(sessionId) {
         return this.trackedSessionParents.has(sessionId) && sessionId !== this.currentSessionId;
     }
+    /**
+     * Public check: is this session a tracked subagent (child) of the current root session?
+     */
+    isSubagentSession(sessionId) {
+        return this.isTrackedChildSession(sessionId);
+    }
     getQueue(map, parentSessionId) {
         const existing = map.get(parentSessionId);
         if (existing) {
@@ -1215,11 +1221,13 @@ class SummaryAggregator {
     }
     handlePermissionAsked(event) {
         const request = event.properties;
-        if (request.sessionID !== this.currentSessionId) {
+        const isCurrent = request.sessionID === this.currentSessionId;
+        const isTrackedChild = this.isTrackedChildSession(request.sessionID);
+        if (!isCurrent && !isTrackedChild) {
             logger.debug(`[Aggregator] Ignoring permission.asked for different session: ${request.sessionID} (current: ${this.currentSessionId})`);
             return;
         }
-        logger.info(`[Aggregator] Permission asked: requestID=${request.id}, type=${request.permission}, patterns=${request.patterns.length}`);
+        logger.info(`[Aggregator] Permission asked: requestID=${request.id}, type=${request.permission}, patterns=${request.patterns.length}, subagent=${isTrackedChild}`);
         if (this.onPermissionCallback) {
             const callback = this.onPermissionCallback;
             setImmediate(async () => {

package/package.json

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