@grinev/opencode-telegram-bot 0.22.1 → 0.22.3

package/.env.example

@@ -105,6 +105,24 @@ OPENCODE_MODEL_ID=big-pickle
 # raw = show assistant replies as plain text
 # MESSAGE_FORMAT_MODE=markdown
 
+# Merge Telegram-split long text messages into one prompt (default: 1500 ms)
+# Text near Telegram's message length limit is buffered for this window (in
+# milliseconds); any immediately following chunks are sent as one prompt.
+# Set to 0 to disable merging and process every message immediately.
+# MESSAGE_MERGE_WINDOW_MS=1500
+
+# Initial runtime settings preset (optional)
+# A JSON object that seeds the bot's default /settings values on first run.
+# Keys not yet persisted in settings.json are initialised to these values;
+# any setting the user has already changed via /settings is left untouched.
+# Supported keys: ttsMode ("off"|"all"|"auto"), compactOutputMode (bool),
+#   showThinkingContent (bool), showAssistantRunFooter (bool),
+#   responseStreamingMode ("edit"|"draft"), sendDiffFileAttachments (bool)
+# The preset is validated at startup: invalid JSON, a non-object value, unknown
+# keys, or wrong value types abort startup with a clear error (fail fast).
+# Example — hide the run footer and enable compact mode by default:
+# INITIAL_SETTINGS_PRESET={"showAssistantRunFooter":false,"compactOutputMode":true}
+
 # Directory Browser Roots (optional)
 # Comma-separated list of paths that /open is allowed to browse.
 # Supports ~ for home directory. Defaults to ~ when not set.
@@ -123,13 +141,26 @@ OPENCODE_MODEL_ID=big-pickle
 # If STT_API_URL is not set, voice messages will get a "not configured" reply.
 # STT_API_URL=
 # STT_API_KEY=
+
+# Document Extractor API (optional)
+# If set, the bot will extract text from PDF, DOCX, PPTX, and other documents
+# using an external API when the current model doesn't natively support them.
+# The API should accept multipart/form-data POST with a "file" field and
+# return JSON with a "text" field containing the extracted content.
+# Only DOC_EXTRACTOR_URL is required; API key is optional for self-hosted setups.
+# DOC_EXTRACTOR_URL=
+# DOC_EXTRACTOR_API_KEY=
 # STT_MODEL=
 # STT_LANGUAGE=
+# STT request format (default: multipart)
+# multipart = standard OpenAI/Groq Whisper form-data upload
+# json      = base64 audio in an `input_audio` JSON body (e.g. OpenRouter)
+# STT_REQUEST_FORMAT=multipart
 # STT_NOTE_PROMPT="The following text is transcribed from voice. It may contain homophone or phonetic errors. Infer the intended meaning from context."
 
 # Text-to-Speech credentials (optional)
 # TTS reply behavior is controlled globally with /tts and persisted in settings.json.
-# Provider: "openai" (default), "elevenlabs", or "google".
+# Provider: "openai" (default), "elevenlabs", "google", or "edge".
 #
 # --- OpenAI-compatible (default) ---
 # Set TTS_API_URL and TTS_API_KEY to any OpenAI-compatible TTS endpoint.
@@ -155,3 +186,10 @@ OPENCODE_MODEL_ID=big-pickle
 # TTS_PROVIDER=google
 # TTS_VOICE=en-US-Studio-O
 # GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+#
+# --- Microsoft Edge TTS ---
+# Uses Microsoft Edge's online Read Aloud service. No API key or account
+# required; only an outbound HTTPS/WebSocket connection to
+# speech.platform.bing.com. Voice list: https://learn.microsoft.com/azure/ai-services/speech-service/language-support
+# TTS_PROVIDER=edge
+# TTS_VOICE=en-US-EmmaMultilingualNeural

package/README.md

@@ -91,7 +91,7 @@ npx @grinev/opencode-telegram-bot@latest
 
 > Quick start is for npm usage. You do not need to clone this repository. If you run this command from the source directory (repository root), it may fail with `opencode-telegram: not found`. To run from sources, use the [Development](#development) section.
 
-On first launch, an interactive wizard will guide you through the configuration — it asks for interface language first, then your bot token, user ID, OpenCode API URL, and optional OpenCode server credentials (username/password). After that, you're ready to go. Open your bot in Telegram and start sending tasks.
+If required configuration is not supplied through process environment variables or an `.env` file, an interactive wizard will guide you through setup. It asks for interface language first, then your bot token, user ID, OpenCode API URL, and optional OpenCode server credentials (username/password). After that, you're ready to go. Open your bot in Telegram and start sending tasks.
 
 #### Alternative: Global Install
 
@@ -199,7 +199,7 @@ For this to work, the console OpenCode instance must be started on the same port
 
 ### Environment Variables
 
-When installed via npm, the configuration wizard handles the initial setup. The `.env` file is stored in your platform's app data directory:
+Configuration can be provided through process environment variables or an `.env` file. Process environment values take precedence. When installed via npm, the configuration wizard handles any missing required values and stores the generated `.env` file in your platform's app data directory:
 
 - **macOS:** `~/Library/Application Support/opencode-telegram-bot/.env`
 - **Windows:** `%APPDATA%\opencode-telegram-bot\.env`
@@ -233,12 +233,17 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `TRACK_BACKGROUND_SESSIONS`                | Track detached/non-current sessions in the current selected project/worktree and send short notifications             |    No    | `true`                   |
 | `RESPONSE_STREAM_THROTTLE_MS`              | Stream update throttle in milliseconds for assistant, thinking, and tool message edits                                |    No    | `1000`                   |
 | `MESSAGE_FORMAT_MODE`                      | Assistant reply formatting mode: `markdown` (Telegram MarkdownV2) or `raw`                                            |    No    | `markdown`               |
+| `MESSAGE_MERGE_WINDOW_MS`                  | Merge Telegram-split long text messages into one prompt after this wait window (ms); `0` disables merging             |    No    | `1500`                   |
+| `INITIAL_SETTINGS_PRESET`                  | JSON object that seeds default `/settings` values on first run (keys not yet persisted); see [Runtime Settings](#runtime-settings) |    No    | `{}`                     |
 | `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    | —                        |
 | `STT_API_KEY`                              | API key for your STT provider                                                                                         |    No    | —                        |
 | `STT_MODEL`                                | STT model name passed to `/audio/transcriptions`                                                                      |    No    | `whisper-large-v3-turbo` |
 | `STT_LANGUAGE`                             | Optional language hint (empty = provider auto-detect)                                                                 |    No    | —                        |
+| `STT_REQUEST_FORMAT`                       | STT request format: `multipart` (standard OpenAI/Groq Whisper) or `json` (base64 `input_audio` body, e.g. OpenRouter) |    No    | `multipart`              |
 | `STT_NOTE_PROMPT`                          | Optional note prepended to the LLM prompt as `[Note: ...]` for voice transcriptions; empty / `false` / `0` disable it |    No    | —                        |
+| `DOC_EXTRACTOR_URL`                        | Document text extraction API URL (enables PDF/DOCX/PPTX extraction)                                                    |    No    | —                        |
+| `DOC_EXTRACTOR_API_KEY`                    | API key for the document extractor (optional for self-hosted extractors)                                                |    No    | —                        |
 | `TTS_PROVIDER`                             | TTS provider: `openai` for OpenAI-compatible APIs, `elevenlabs` for ElevenLabs, or `google` for Google Cloud TTS      |    No    | `openai`                 |
 | `TTS_API_URL`                              | TTS API base URL for OpenAI-compatible APIs or ElevenLabs                                                             |    No    | —                        |
 | `TTS_API_KEY`                              | TTS API key for OpenAI-compatible APIs or ElevenLabs                                                                  |    No    | —                        |
@@ -258,10 +263,17 @@ Runtime preferences are changed from `/settings` and stored in `settings.json`:
 
 - Compact output mode
 - Thinking content display
+- Assistant run footer display
 - Diff file attachments
 - Response streaming mode: `edit` or `draft (experimental)`; applies only to final assistant replies, not thinking messages
 - Audio replies: `off`, `all`, or `auto` when TTS is configured
 
+You can seed the initial defaults for any of these settings without hard-coding them in your Docker image by setting `INITIAL_SETTINGS_PRESET` to a JSON object. Only keys not yet persisted in `settings.json` are affected — settings the user has already changed via `/settings` are left untouched:
+
+```env
+INITIAL_SETTINGS_PRESET={"showAssistantRunFooter":false,"compactOutputMode":true,"ttsMode":"auto"}
+```
+
 ### Reverse Proxy (Optional)
 
 For environments that block `api.telegram.org` but allow your own HTTPS endpoint (corporate networks, restricted regions), you can route Bot API traffic through a reverse proxy you control. This is an alternative to the SOCKS/HTTP forward proxy configured with `TELEGRAM_PROXY_URL`.
@@ -365,6 +377,20 @@ Supported provider examples (Whisper-compatible):
 
 If STT variables are not set, voice/audio transcription is disabled and the bot will ask you to configure STT.
 
+### Document Text Extraction (Optional)
+
+If `DOC_EXTRACTOR_URL` is set, the bot will extract text from PDF, DOCX, PPTX, and other document files using an external API when the current model does not natively support document input.
+
+The API contract is:
+
+- **Endpoint:** `POST {DOC_EXTRACTOR_URL}`
+- **Content-Type:** `multipart/form-data`
+- **Field:** `file` — the document binary
+- **Authorization:** `Bearer {DOC_EXTRACTOR_API_KEY}` (only sent when a key is configured)
+- **Response:** JSON `{ "text": "extracted content..." }`
+
+If the extractor is not configured and the model doesn't support documents, the bot replies with a notice and forwards only the caption text.
+
 ### Model Configuration
 
 The model picker uses OpenCode local model state (`favorite` + `recent`):

package/dist/app/bootstrap/start-bot-app.js

@@ -34,12 +34,27 @@ export async function startBotApp() {
     const version = await getBotVersion();
     const logFilePath = getLogFilePath();
     logger.info(`Starting OpenCode Telegram Bot v${version}...`);
+    logger.info(`Node.js ${process.version} on ${process.platform} ${process.arch}`);
     logger.info(`Config loaded from ${runtimePaths.envFilePath}`);
     if (logFilePath) {
         logger.info(`Logs are written to ${logFilePath}`);
     }
     logger.info(`Allowed User ID: ${config.telegram.allowedUserId}`);
     logger.debug(`[Runtime] Application start mode: ${mode}`);
+    const unhandledRejectionHandler = (reason) => {
+        logger.error("[App] Unhandled promise rejection", reason);
+        void clearManagedServiceState()
+            .catch(() => { })
+            .finally(() => process.exit(1));
+    };
+    const uncaughtExceptionHandler = (error) => {
+        logger.error("[App] Uncaught exception", error);
+        void clearManagedServiceState()
+            .catch(() => { })
+            .finally(() => process.exit(1));
+    };
+    process.on("unhandledRejection", unhandledRejectionHandler);
+    process.on("uncaughtException", uncaughtExceptionHandler);
     await loadSettings();
     await reconcileStoredModelSelection();
     registerOpenCodeReadyRefreshHandler();
@@ -118,6 +133,8 @@ export async function startBotApp() {
         });
     }
     finally {
+        process.off("unhandledRejection", unhandledRejectionHandler);
+        process.off("uncaughtException", uncaughtExceptionHandler);
         process.off("SIGINT", handleSigint);
         process.off("SIGTERM", handleSigterm);
         if (shutdownTimeout) {

package/dist/app/formatters/assistant-run-footer-formatter.js

@@ -16,5 +16,5 @@ function formatDuration(elapsedMs) {
 }
 export function formatAssistantRunFooter({ agent, providerID, modelID, elapsedMs, }) {
     const agentDisplay = getAgentDisplayName(agent);
-    return `${agentDisplay} · 🤖 ${providerID}/${modelID} · 🕒 ${formatDuration(elapsedMs)}`;
+    return `${agentDisplay} · 🧠 ${providerID}/${modelID} · 🕒 ${formatDuration(elapsedMs)}`;
 }

package/dist/app/managers/permission-manager.js

@@ -2,17 +2,66 @@ import { logger } from "../../utils/logger.js";
 class PermissionManager {
     state = {
         requestsByMessageId: new Map(),
+        requestIdsByMessageId: new Map(),
+        messageIdBySignature: new Map(),
     };
+    resolvedRequestIDs = new Set();
+    generation = 0;
+    getRequestSignature(request) {
+        return JSON.stringify({
+            sessionID: request.sessionID,
+            permission: request.permission,
+            patterns: [...request.patterns].sort(),
+        });
+    }
     /**
      * Register a new permission request message
      */
-    startPermission(request, messageId) {
+    startPermission(request, messageId, generation = this.generation) {
         logger.debug(`[PermissionManager] startPermission: id=${request.id}, permission=${request.permission}, messageId=${messageId}`);
-        if (this.state.requestsByMessageId.has(messageId)) {
+        if (generation !== this.generation || this.resolvedRequestIDs.has(request.id)) {
+            logger.debug(`[PermissionManager] Ignoring stale or already resolved request: id=${request.id}`);
+            return false;
+        }
+        const previous = this.state.requestsByMessageId.get(messageId);
+        if (previous) {
             logger.warn(`[PermissionManager] Message ID already tracked, replacing: ${messageId}`);
+            // Drop the replaced request's signature so it cannot later group new
+            // requests behind a message that now shows something else.
+            this.state.messageIdBySignature.delete(this.getRequestSignature(previous));
         }
         this.state.requestsByMessageId.set(messageId, request);
+        this.state.requestIdsByMessageId.set(messageId, [request.id]);
+        this.state.messageIdBySignature.set(this.getRequestSignature(request), messageId);
         logger.info(`[PermissionManager] New permission request: type=${request.permission}, patterns=${request.patterns.join(", ")}, pending=${this.state.requestsByMessageId.size}`);
+        return true;
+    }
+    /**
+     * Attach an equivalent OpenCode request to an already visible Telegram permission message.
+     */
+    addEquivalentRequest(request, generation = this.generation) {
+        if (generation !== this.generation || this.resolvedRequestIDs.has(request.id)) {
+            logger.debug(`[PermissionManager] Ignoring stale or already resolved equivalent request: id=${request.id}`);
+            return null;
+        }
+        const signature = this.getRequestSignature(request);
+        const messageId = this.state.messageIdBySignature.get(signature);
+        if (messageId === undefined) {
+            return null;
+        }
+        const visibleRequest = this.state.requestsByMessageId.get(messageId);
+        if (!visibleRequest) {
+            logger.warn(`[PermissionManager] Dropping orphan permission signature: messageId=${messageId}`);
+            this.state.messageIdBySignature.delete(signature);
+            return null;
+        }
+        const requestIds = this.state.requestIdsByMessageId.get(messageId) ?? [];
+        if (!requestIds.includes(request.id)) {
+            requestIds.push(request.id);
+            this.state.requestIdsByMessageId.set(messageId, requestIds);
+        }
+        logger.info(`[PermissionManager] Merged equivalent permission request: id=${request.id}, messageId=${messageId}, grouped=${requestIds.length}`);
+        return { messageId, request: visibleRequest, count: requestIds.length };
     }
     /**
      * Get permission request by Telegram message ID
@@ -29,6 +78,15 @@ class PermissionManager {
     getRequestID(messageId) {
         return this.getRequest(messageId)?.id ?? null;
     }
+    /**
+     * Get all OpenCode request IDs grouped behind a Telegram message.
+     */
+    getRequestIDs(messageId) {
+        if (messageId === null) {
+            return [];
+        }
+        return [...(this.state.requestIdsByMessageId.get(messageId) ?? [])];
+    }
     /**
      * Get permission type (bash, edit, etc.) by message ID
      */
@@ -72,9 +130,38 @@ class PermissionManager {
             return null;
         }
         this.state.requestsByMessageId.delete(messageId);
+        this.state.requestIdsByMessageId.delete(messageId);
+        this.state.messageIdBySignature.delete(this.getRequestSignature(request));
         logger.debug(`[PermissionManager] Removed permission request: id=${request.id}, messageId=${messageId}, pending=${this.state.requestsByMessageId.size}`);
         return request;
     }
+    /**
+     * Remove all Telegram messages tracking an OpenCode permission request ID
+     */
+    resolveRequest(requestID) {
+        this.resolvedRequestIDs.add(requestID);
+        const removedMessageIds = [];
+        for (const [messageId, request] of this.state.requestsByMessageId) {
+            const requestIds = this.state.requestIdsByMessageId.get(messageId) ?? [request.id];
+            if (!requestIds.includes(requestID)) {
+                continue;
+            }
+            this.state.requestsByMessageId.delete(messageId);
+            this.state.requestIdsByMessageId.delete(messageId);
+            this.state.messageIdBySignature.delete(this.getRequestSignature(request));
+            removedMessageIds.push(messageId);
+        }
+        if (removedMessageIds.length > 0) {
+            logger.debug(`[PermissionManager] Removed resolved permission request: id=${requestID}, messages=${removedMessageIds.length}, pending=${this.state.requestsByMessageId.size}`);
+        }
+        return removedMessageIds;
+    }
+    isResolved(requestID) {
+        return this.resolvedRequestIDs.has(requestID);
+    }
+    getGeneration() {
+        return this.generation;
+    }
     /**
      * Get number of active permission requests
      */
@@ -94,7 +181,11 @@ class PermissionManager {
         logger.debug(`[PermissionManager] Clearing permission state: pending=${this.state.requestsByMessageId.size}`);
         this.state = {
             requestsByMessageId: new Map(),
+            requestIdsByMessageId: new Map(),
+            messageIdBySignature: new Map(),
         };
+        this.resolvedRequestIDs.clear();
+        this.generation++;
     }
 }
 export const permissionManager = new PermissionManager();

package/dist/app/managers/summary-aggregation-manager.js

@@ -60,6 +60,8 @@ class SummaryAggregator {
     onSessionRetryCallback = null;
     onSessionIdleCallback = null;
     onPermissionCallback = null;
+    permissionQueue = Promise.resolve();
+    onPermissionRepliedCallback = null;
     onSessionDiffCallback = null;
     onFileChangeCallback = null;
     onClearedCallback = null;
@@ -139,6 +141,9 @@ class SummaryAggregator {
     setOnPermission(callback) {
         this.onPermissionCallback = callback;
     }
+    setOnPermissionReplied(callback) {
+        this.onPermissionRepliedCallback = callback;
+    }
     setOnSessionDiff(callback) {
         this.onSessionDiffCallback = callback;
     }
@@ -234,7 +239,7 @@ class SummaryAggregator {
                 this.handlePermissionAsked(event);
                 break;
             case "permission.replied":
-                logger.info(`[Aggregator] Permission replied: requestID=${event.properties.requestID}`);
+                this.handlePermissionReplied(event);
                 break;
             default:
                 logger.debug(`[Aggregator] Unhandled event type: ${event.type}`);
@@ -268,6 +273,7 @@ class SummaryAggregator {
         this.pendingChildSessionIdsByParent.clear();
         this.fallbackSubagentCardIdsByParent.clear();
         this.lastSubagentSnapshot = "";
+        this.permissionQueue = Promise.resolve();
         this.messageCount = 0;
         this.lastUpdated = 0;
         if (this.onClearedCallback) {
@@ -1394,12 +1400,30 @@ class SummaryAggregator {
         logger.info(`[Aggregator] Permission asked: requestID=${request.id}, type=${request.permission}, patterns=${request.patterns.length}, subagent=${isTrackedChild}`);
         if (this.onPermissionCallback) {
             const callback = this.onPermissionCallback;
+            this.permissionQueue = this.permissionQueue
+                .then(() => callback(request))
+                .catch((err) => {
+                logger.error("[Aggregator] Error in permission callback:", err);
+            });
+        }
+    }
+    handlePermissionReplied(event) {
+        const { sessionID, requestID } = event.properties;
+        const isCurrent = sessionID === this.currentSessionId;
+        const isTrackedChild = this.isTrackedChildSession(sessionID);
+        if (!isCurrent && !isTrackedChild) {
+            logger.debug(`[Aggregator] Ignoring permission.replied for different session: ${sessionID} (current: ${this.currentSessionId})`);
+            return;
+        }
+        logger.info(`[Aggregator] Permission replied: requestID=${requestID}`);
+        if (this.onPermissionRepliedCallback) {
+            const callback = this.onPermissionRepliedCallback;
             setImmediate(async () => {
                 try {
-                    await callback(request);
+                    await callback(sessionID, requestID);
                 }
                 catch (err) {
-                    logger.error("[Aggregator] Error in permission callback:", err);
+                    logger.error("[Aggregator] Error in permission replied callback:", err);
                 }
             });
         }

package/dist/app/services/document-extractor-service.js

@@ -0,0 +1,47 @@
+import { config } from "../../config.js";
+import { logger } from "../../utils/logger.js";
+const REQUEST_TIMEOUT_MS = 60_000;
+export function isDocExtractorConfigured() {
+    return Boolean(config.docExtractor.apiUrl);
+}
+export async function extractDocument(fileBuffer, mimeType, filename) {
+    if (!isDocExtractorConfigured()) {
+        throw new Error("Document extractor is not configured: DOC_EXTRACTOR_URL is required");
+    }
+    const url = config.docExtractor.apiUrl;
+    const formData = new FormData();
+    formData.append("file", new Blob([new Uint8Array(fileBuffer)], { type: mimeType }), filename);
+    logger.debug(`[DocExtractor] Sending extraction request: url=${url}, mime=${mimeType}, filename=${filename}, size=${fileBuffer.length} bytes`);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const headers = {};
+        if (config.docExtractor.apiKey) {
+            headers["Authorization"] = `Bearer ${config.docExtractor.apiKey}`;
+        }
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: formData,
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => "");
+            throw new Error(`Document extractor API returned HTTP ${response.status}: ${errorBody || response.statusText}`);
+        }
+        const data = (await response.json());
+        if (typeof data.text !== "string") {
+            throw new Error("Document extractor API response does not contain a text field");
+        }
+        return { text: data.text };
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new Error(`Document extractor request timed out after ${REQUEST_TIMEOUT_MS}ms`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}