@grinev/opencode-telegram-bot 0.20.2 → 0.20.4

package/.env.example

@@ -12,6 +12,21 @@ TELEGRAM_ALLOWED_USER_ID=
 #   TELEGRAM_PROXY_URL=http://proxy.example.com:8080
 # TELEGRAM_PROXY_URL=
 
+# Telegram Reverse-Proxy mode (optional, alternative to TELEGRAM_PROXY_URL)
+# For corporate networks that block api.telegram.org but allow your own server.
+# Point TELEGRAM_API_ROOT at an HTTPS endpoint that reverse-proxies to
+# https://api.telegram.org (e.g. nginx). Applied to Bot API calls AND file
+# downloads. TELEGRAM_PROXY_SECRET (optional) is sent as the X-Proxy-Secret
+# header so the reverse proxy can authorize callers. See README for an example
+# nginx config.
+# TELEGRAM_API_ROOT=https://tg-proxy.yourdomain.com
+# TELEGRAM_PROXY_SECRET=some-long-random-string
+
+# Force IPv4 for direct Telegram API/file requests (optional, default: false)
+# Enable this if startup fails with "Network request ... failed" in an
+# environment where IPv6 DNS exists but outbound IPv6 connectivity is broken.
+# TELEGRAM_FORCE_IPV4=false
+
 # OpenCode API URL (optional, default: http://localhost:4096)
 # OPENCODE_API_URL=http://localhost:4096
 

package/README.md

@@ -198,6 +198,9 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `TELEGRAM_BOT_TOKEN`                       | Bot token from @BotFather                                                                                             |   Yes    | —                        |
 | `TELEGRAM_ALLOWED_USER_ID`                 | Your numeric Telegram user ID                                                                                         |   Yes    | —                        |
 | `TELEGRAM_PROXY_URL`                       | Proxy URL for Telegram API (SOCKS5/HTTP)                                                                              |    No    | —                        |
+| `TELEGRAM_API_ROOT`                        | Custom Telegram Bot API root URL (e.g. nginx reverse-proxying `api.telegram.org`); applied to API calls and file downloads | No | `https://api.telegram.org` |
+| `TELEGRAM_PROXY_SECRET`                    | Shared secret sent as `X-Proxy-Secret` header on every Bot API request and file download (used with `TELEGRAM_API_ROOT`) | No | —                        |
+| `TELEGRAM_FORCE_IPV4`                      | Force IPv4 for direct Telegram API and file requests; useful when IPv6 DNS works but outbound IPv6 is broken           |    No    | `false`                  |
 | `OPENCODE_API_URL`                         | OpenCode server URL                                                                                                   |    No    | `http://localhost:4096`  |
 | `OPENCODE_AUTO_RESTART_ENABLED`            | Automatically restart a local OpenCode server when health-checks fail                                                 |    No    | `false`                  |
 | `OPENCODE_MONITOR_INTERVAL_SEC`            | Health monitor interval in seconds when OpenCode auto-restart is enabled                                              |    No    | `300`                    |
@@ -239,6 +242,54 @@ When installed via npm, the configuration wizard handles the initial setup. The
 
 Logs are written to `./logs` when running from sources and to the runtime config directory `logs/` folder in `installed` mode. Log rotation depends on runtime mode: `sources` creates one file per bot launch, while `installed` appends to one file per day. Old log files are removed according to `LOG_RETENTION`.
 
+### 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`.
+
+Set `TELEGRAM_API_ROOT` to your reverse-proxy URL — both Bot API calls and file downloads (including voice/audio files) will use it. Optionally set `TELEGRAM_PROXY_SECRET` so the bot sends an `X-Proxy-Secret` header your proxy can use to authorize callers.
+
+`.env`:
+
+```env
+TELEGRAM_API_ROOT=https://tg-proxy.yourdomain.com
+TELEGRAM_PROXY_SECRET=some-long-random-string
+```
+
+Example nginx config:
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name tg-proxy.yourdomain.com;
+
+    ssl_certificate     /etc/letsencrypt/live/tg-proxy.yourdomain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/tg-proxy.yourdomain.com/privkey.pem;
+
+    access_log off;  # the bot token appears in URL paths
+    client_max_body_size 50m;
+
+    if ($http_x_proxy_secret != "some-long-random-string") { return 403; }
+
+    location / {
+        proxy_pass https://api.telegram.org;
+        proxy_ssl_server_name on;
+        proxy_set_header Host api.telegram.org;
+    }
+}
+```
+
+`TELEGRAM_API_ROOT` and `TELEGRAM_PROXY_URL` are alternative connectivity modes — the former picks the URL the bot connects to (a reverse proxy on your side), while the latter tunnels TCP through a forward proxy. Configure only one of them; the bot rejects using both at startup.
+
+### Force IPv4 for Telegram (Optional)
+
+If the bot fails during startup with errors such as `Network request for 'setMyCommands' failed` or `Network request for 'getWebhookInfo' failed`, and the same machine has broken outbound IPv6 connectivity, force direct Telegram requests to use IPv4:
+
+```env
+TELEGRAM_FORCE_IPV4=true
+```
+
+This affects direct Bot API calls and Telegram file downloads. It is not a replacement for `TELEGRAM_PROXY_URL` or `TELEGRAM_API_ROOT` when Telegram is blocked by the network.
+
 ### Voice and Audio Transcription (Optional)
 
 If `STT_API_URL` and `STT_API_KEY` are set, the bot will:

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

@@ -12,6 +12,7 @@ import { getRuntimePaths } from "../runtime/paths.js";
 import { clearServiceStateFile } from "../service/manager.js";
 import { getServiceStateFilePathFromEnv, isServiceChildProcess } from "../service/runtime.js";
 import { getLogFilePath, initializeLogger, logger } from "../utils/logger.js";
+import { safeBackgroundTask } from "../utils/safe-background-task.js";
 const SHUTDOWN_TIMEOUT_MS = 5000;
 async function getBotVersion() {
     try {
@@ -43,8 +44,13 @@ export async function startBotApp() {
     registerOpenCodeReadyRefreshHandler();
     const bot = createBot();
     await scheduledTaskRuntime.initialize(bot);
-    await opencodeAutoRestartService.start();
-    await notifyOpencodeReadyIfHealthy("startup");
+    safeBackgroundTask({
+        taskName: "app.opencodeStartup",
+        task: async () => {
+            await opencodeAutoRestartService.start();
+            await notifyOpencodeReadyIfHealthy("startup");
+        },
+    });
     let shutdownStarted = false;
     let serviceStateCleared = false;
     let shutdownTimeout = null;

package/dist/bot/handlers/question.js

@@ -8,7 +8,11 @@ import { interactionManager } from "../../interaction/manager.js";
 import { logger } from "../../utils/logger.js";
 import { safeBackgroundTask } from "../../utils/safe-background-task.js";
 import { t } from "../../i18n/index.js";
+import { editRenderedBotPart, sendRenderedBotPart } from "../utils/telegram-text.js";
 const MAX_BUTTON_LENGTH = 60;
+const TELEGRAM_MESSAGE_LIMIT = 4096;
+const TRUNCATION_SUFFIX = "…";
+const QUESTION_EMOJI = "❓";
 function getCallbackMessageId(ctx) {
     const message = ctx.callbackQuery?.message;
     if (!message || !("message_id" in message)) {
@@ -186,12 +190,26 @@ async function updateQuestionMessage(ctx) {
         logger.debug("[QuestionHandler] updateQuestionMessage: no current question");
         return;
     }
-    const text = formatQuestionText(question);
+    const part = formatQuestionDetailsPart(question);
     const keyboard = buildQuestionKeyboard(question, questionManager.getSelectedOptions(questionManager.getCurrentIndex()));
     logger.debug("[QuestionHandler] Updating question message");
     try {
-        await ctx.editMessageText(text, {
-            reply_markup: keyboard,
+        const chatId = ctx.chat?.id;
+        const messageId = getCallbackMessageId(ctx);
+        if (!chatId || messageId === null) {
+            await ctx.editMessageText(part.fallbackText, {
+                reply_markup: keyboard,
+            });
+            return;
+        }
+        await editRenderedBotPart({
+            api: ctx.api,
+            chatId,
+            messageId,
+            part,
+            options: {
+                reply_markup: keyboard,
+            },
         });
     }
     catch (err) {
@@ -205,16 +223,21 @@ export async function showCurrentQuestion(bot, chatId) {
         return;
     }
     logger.debug(`[QuestionHandler] Showing question: ${question.header} - ${question.question}`);
-    const text = formatQuestionText(question);
+    const part = formatQuestionDetailsPart(question);
     const keyboard = buildQuestionKeyboard(question, questionManager.getSelectedOptions(questionManager.getCurrentIndex()));
     logger.debug(`[QuestionHandler] Sending message with keyboard, chatId=${chatId}`);
     try {
-        const message = await bot.sendMessage(chatId, text, {
-            reply_markup: keyboard,
+        const { messageId } = await sendRenderedBotPart({
+            api: bot,
+            chatId,
+            part,
+            options: {
+                reply_markup: keyboard,
+            },
         });
-        logger.debug(`[QuestionHandler] Message sent, messageId=${message.message_id}`);
-        questionManager.addMessageId(message.message_id);
-        questionManager.setActiveMessageId(message.message_id);
+        questionManager.addMessageId(messageId);
+        logger.debug(`[QuestionHandler] Message sent, messageId=${messageId}`);
+        questionManager.setActiveMessageId(messageId);
         syncQuestionInteractionState("callback", questionManager.getCurrentIndex(), questionManager.getActiveMessageId());
         summaryAggregator.stopTypingIndicator();
     }
@@ -335,14 +358,67 @@ async function sendAllAnswersToAgent(bot, chatId) {
         },
     });
 }
-function formatQuestionText(question) {
+function formatQuestionDetailsPart(question) {
     const currentIndex = questionManager.getCurrentIndex();
     const totalQuestions = questionManager.getTotalQuestions();
     const progressText = totalQuestions > 0 ? `${currentIndex + 1}/${totalQuestions}` : "";
-    const headerTitle = [progressText, question.header].filter(Boolean).join(" ");
-    const header = headerTitle ? `${headerTitle}\n\n` : "";
+    const headerTitle = [QUESTION_EMOJI, progressText, question.header].filter(Boolean).join(" ");
+    const textParts = [];
+    const entities = [];
+    if (headerTitle) {
+        textParts.push(headerTitle);
+        entities.push({ type: "bold", offset: 0, length: headerTitle.length });
+    }
     const multiple = question.multiple ? t("question.multi_hint") : "";
-    return `${header}${question.question}${multiple}`;
+    const questionText = `${question.question}${multiple}`;
+    if (questionText) {
+        textParts.push(questionText);
+    }
+    for (const option of question.options) {
+        const optionText = formatOptionDetails(option);
+        const offset = textParts.join("\n\n").length + (textParts.length > 0 ? 2 : 0);
+        if (option.label) {
+            entities.push({ type: "bold", offset, length: option.label.length });
+        }
+        textParts.push(optionText);
+    }
+    const text = textParts.filter(Boolean).join("\n\n");
+    const truncated = truncateQuestionPart(text, entities);
+    return {
+        text: truncated.text,
+        entities: truncated.entities.length > 0 ? truncated.entities : undefined,
+        fallbackText: truncated.text,
+        source: truncated.entities.length > 0 ? "entities" : "plain",
+    };
+}
+function truncateQuestionPart(text, entities) {
+    if (text.length <= TELEGRAM_MESSAGE_LIMIT) {
+        return { text, entities };
+    }
+    const maxBaseLength = TELEGRAM_MESSAGE_LIMIT - TRUNCATION_SUFFIX.length;
+    let endIndex = maxBaseLength;
+    if (endIndex > 0 && isHighSurrogate(text.charCodeAt(endIndex - 1))) {
+        endIndex -= 1;
+    }
+    const truncatedText = `${text.slice(0, endIndex)}${TRUNCATION_SUFFIX}`;
+    const truncatedEntities = entities
+        .filter((entity) => entity.offset < endIndex)
+        .map((entity) => ({
+        ...entity,
+        length: Math.min(entity.length, endIndex - entity.offset),
+    }))
+        .filter((entity) => entity.length > 0);
+    return { text: truncatedText, entities: truncatedEntities };
+}
+function isHighSurrogate(codeUnit) {
+    return codeUnit >= 0xd800 && codeUnit <= 0xdbff;
+}
+function formatOptionDetails(option) {
+    const optionTitle = option.label;
+    if (!option.description) {
+        return optionTitle;
+    }
+    return `${optionTitle} — ${option.description}`;
 }
 function buildQuestionKeyboard(question, selectedOptions) {
     const keyboard = new InlineKeyboard();
@@ -351,7 +427,7 @@ function buildQuestionKeyboard(question, selectedOptions) {
     question.options.forEach((option, index) => {
         const isSelected = selectedOptions.has(index);
         const icon = isSelected ? "✅ " : "";
-        const buttonText = formatButtonText(option.label, option.description, icon);
+        const buttonText = formatButtonText(option.label, icon);
         const callbackData = `question:select:${questionIndex}:${index}`;
         logger.debug(`[QuestionHandler] Button ${index}: "${buttonText}" -> "${callbackData}"`);
         keyboard.text(buttonText, callbackData).row();
@@ -367,11 +443,8 @@ function buildQuestionKeyboard(question, selectedOptions) {
     logger.debug(`[QuestionHandler] Final keyboard: ${JSON.stringify(keyboard.inline_keyboard)}`);
     return keyboard;
 }
-function formatButtonText(label, description, icon) {
+function formatButtonText(label, icon) {
     let text = `${icon}${label}`;
-    if (description && icon === "") {
-        text += ` - ${description}`;
-    }
     if (text.length > MAX_BUTTON_LENGTH) {
         text = text.substring(0, MAX_BUTTON_LENGTH - 3) + "...";
     }

package/dist/bot/handlers/voice.js

@@ -8,6 +8,7 @@ import { isSttConfigured, transcribeAudio } from "../../stt/client.js";
 import { processUserPrompt } from "./prompt.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
+import { buildTelegramFileUrl } from "../utils/telegram-file-url.js";
 const TELEGRAM_DOWNLOAD_TIMEOUT_MS = 30_000;
 const TELEGRAM_DOWNLOAD_MAX_REDIRECTS = 3;
 let telegramDownloadAgent;
@@ -30,7 +31,11 @@ async function downloadTelegramFileByUrl(url, redirectDepth = 0) {
     return new Promise((resolve, reject) => {
         const targetUrl = new URL(url);
         const requestModule = targetUrl.protocol === "http:" ? http : https;
-        const request = requestModule.get(targetUrl, { agent: getTelegramDownloadAgent() }, (response) => {
+        const proxySecret = config.telegram.proxySecret;
+        const request = requestModule.get(targetUrl, {
+            agent: getTelegramDownloadAgent(),
+            ...(proxySecret ? { headers: { "X-Proxy-Secret": proxySecret } } : {}),
+        }, (response) => {
             const statusCode = response.statusCode ?? 0;
             if (statusCode >= 300 && statusCode < 400 && response.headers.location) {
                 response.resume();
@@ -76,7 +81,7 @@ async function downloadTelegramFile(ctx, fileId) {
             logger.error("[Voice] Telegram getFile returned no file_path");
             return null;
         }
-        const fileUrl = `https://api.telegram.org/file/bot${ctx.api.token}/${file.file_path}`;
+        const fileUrl = buildTelegramFileUrl(file.file_path);
         logger.debug(`[Voice] Downloading file: ${file.file_path} (${file.file_size ?? "?"} bytes)`);
         const buffer = await downloadTelegramFileByUrl(fileUrl);
         // Extract filename from file_path (e.g., "voice/file_123.oga" -> "file_123.oga")

package/dist/bot/index.js

@@ -2,8 +2,6 @@ import { Bot, InputFile } from "grammy";
 import { promises as fs } from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import { SocksProxyAgent } from "socks-proxy-agent";
-import { HttpsProxyAgent } from "https-proxy-agent";
 import { config } from "../config.js";
 import { authMiddleware } from "./middleware/auth.js";
 import { interactionGuardMiddleware } from "./middleware/interaction-guard.js";
@@ -55,6 +53,7 @@ import { withTelegramRateLimitRetry } from "../utils/telegram-rate-limit-retry.j
 import { pinnedMessageManager } from "../pinned/manager.js";
 import { t } from "../i18n/index.js";
 import { getCurrentProject } from "../settings/manager.js";
+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";
@@ -838,25 +837,7 @@ export function createBot() {
         clearInterval(heartbeatTimer);
         heartbeatTimer = null;
     }
-    const botOptions = {};
-    if (config.telegram.proxyUrl) {
-        const proxyUrl = config.telegram.proxyUrl;
-        let agent;
-        if (proxyUrl.startsWith("socks")) {
-            agent = new SocksProxyAgent(proxyUrl);
-            logger.info(`[Bot] Using SOCKS proxy: ${proxyUrl.replace(/\/\/.*@/, "//***@")}`);
-        }
-        else {
-            agent = new HttpsProxyAgent(proxyUrl);
-            logger.info(`[Bot] Using HTTP/HTTPS proxy: ${proxyUrl.replace(/\/\/.*@/, "//***@")}`);
-        }
-        botOptions.client = {
-            baseFetchConfig: {
-                agent,
-                compress: true,
-            },
-        };
-    }
+    const botOptions = createTelegramBotOptions(config.telegram);
     const bot = new Bot(config.telegram.token, botOptions);
     botInstance = bot;
     chatIdInstance = config.telegram.allowedUserId;

package/dist/bot/telegram-client-options.js

@@ -0,0 +1,63 @@
+// @ts-expect-error — node-fetch v2 ships no TS types and we avoid adding @types/node-fetch
+import nodeFetch from "node-fetch";
+import { Agent as HttpsAgent } from "https";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { SocksProxyAgent } from "socks-proxy-agent";
+import { logger } from "../utils/logger.js";
+export function createTelegramIpv4Agent() {
+    return new HttpsAgent({ family: 4, keepAlive: true });
+}
+export function createTelegramBotOptions(telegram) {
+    const botOptions = {};
+    if (telegram.apiRoot || telegram.proxySecret) {
+        botOptions.client = botOptions.client ?? {};
+        if (telegram.apiRoot) {
+            botOptions.client.apiRoot = telegram.apiRoot;
+            logger.info(`[Bot] Using custom Telegram API root: ${telegram.apiRoot}`);
+        }
+        if (telegram.proxySecret) {
+            // Inject the shared-secret header via a custom fetch wrapper instead of
+            // baseFetchConfig.headers, because grammY's client spreads
+            // `{...baseFetchConfig, ...config}` and the per-request config.headers
+            // (Content-Type/Length) wipes out anything we put on baseFetchConfig.
+            // Plain-object headers merge (not the Headers class) keeps this compatible
+            // with node-fetch v2's init shape and avoids the DOM lib HeadersInit type.
+            const proxySecret = telegram.proxySecret;
+            botOptions.client.fetch = ((url, init) => {
+                const existing = init?.headers ?? {};
+                const merged = { ...existing, "X-Proxy-Secret": proxySecret };
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return nodeFetch(url, { ...(init ?? {}), headers: merged });
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            });
+            logger.info(`[Bot] Sending X-Proxy-Secret header to Telegram API root`);
+        }
+    }
+    if (telegram.proxyUrl) {
+        const proxyUrl = telegram.proxyUrl;
+        let agent;
+        if (proxyUrl.startsWith("socks")) {
+            agent = new SocksProxyAgent(proxyUrl);
+            logger.info(`[Bot] Using SOCKS proxy: ${proxyUrl.replace(/\/\/.*@/, "//***@")}`);
+        }
+        else {
+            agent = new HttpsProxyAgent(proxyUrl);
+            logger.info(`[Bot] Using HTTP/HTTPS proxy: ${proxyUrl.replace(/\/\/.*@/, "//***@")}`);
+        }
+        botOptions.client = botOptions.client ?? {};
+        botOptions.client.baseFetchConfig = {
+            agent,
+            compress: true,
+        };
+    }
+    else if (telegram.forceIpv4) {
+        botOptions.client = botOptions.client ?? {};
+        botOptions.client.baseFetchConfig = {
+            ...(botOptions.client.baseFetchConfig ?? {}),
+            agent: createTelegramIpv4Agent(),
+            compress: true,
+        };
+        logger.info(`[Bot] Forcing IPv4 for Telegram API requests`);
+    }
+    return botOptions;
+}

package/dist/bot/utils/file-download.js

@@ -1,6 +1,9 @@
-import { config } from "../../config.js";
+// @ts-expect-error — node-fetch v2 ships no TS types and we avoid adding @types/node-fetch
+import nodeFetch from "node-fetch";
+import { Agent as HttpsAgent } from "https";
 import { logger } from "../../utils/logger.js";
-const TELEGRAM_FILE_URL_BASE = "https://api.telegram.org/file/bot";
+import { config } from "../../config.js";
+import { buildTelegramFileUrl } from "./telegram-file-url.js";
 const MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024; // 20MB Telegram limit
 /**
  * Download a photo from Telegram servers
@@ -18,7 +21,7 @@ export async function downloadTelegramFile(api, fileId) {
         const sizeMb = (file.file_size / (1024 * 1024)).toFixed(2);
         throw new Error(`File too large: ${sizeMb}MB (max 20MB)`);
     }
-    const fileUrl = `${TELEGRAM_FILE_URL_BASE}${config.telegram.token}/${file.file_path}`;
+    const fileUrl = buildTelegramFileUrl(file.file_path);
     logger.debug(`[FileDownload] Downloading from ${fileUrl.replace(config.telegram.token, "***")}`);
     const fetchOptions = {};
     // Use proxy if configured
@@ -26,7 +29,17 @@ export async function downloadTelegramFile(api, fileId) {
         const { HttpsProxyAgent } = await import("https-proxy-agent");
         fetchOptions.agent = new HttpsProxyAgent(config.telegram.proxyUrl);
     }
-    const response = await fetch(fileUrl, fetchOptions);
+    else if (config.telegram.forceIpv4) {
+        fetchOptions.agent = new HttpsAgent({ family: 4, keepAlive: true });
+    }
+    // Send shared secret when custom API root expects it
+    if (config.telegram.proxySecret) {
+        fetchOptions.headers = {
+            ...fetchOptions.headers,
+            "X-Proxy-Secret": config.telegram.proxySecret,
+        };
+    }
+    const response = await nodeFetch(fileUrl, fetchOptions);
     if (!response.ok) {
         throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
     }

package/dist/bot/utils/telegram-file-url.js

@@ -0,0 +1,11 @@
+import { config } from "../../config.js";
+const DEFAULT_TELEGRAM_API_ROOT = "https://api.telegram.org";
+export function telegramFileUrlBase() {
+    const apiRoot = config.telegram.apiRoot
+        ? config.telegram.apiRoot.replace(/\/+$/, "")
+        : DEFAULT_TELEGRAM_API_ROOT;
+    return `${apiRoot}/file/bot`;
+}
+export function buildTelegramFileUrl(filePath) {
+    return `${telegramFileUrlBase()}${config.telegram.token}/${filePath}`;
+}

package/dist/config.js

@@ -62,12 +62,33 @@ function getOptionalTtsProviderEnvVar(key, defaultValue) {
     }
     return defaultValue;
 }
-export const config = {
-    telegram: {
+export function buildTelegramConfig() {
+    const proxyUrl = getEnvVar("TELEGRAM_PROXY_URL", false);
+    // grammY rejects an apiRoot ending with `/`, so normalize once at config
+    // load instead of leaking the concern into every consumer.
+    const apiRoot = getEnvVar("TELEGRAM_API_ROOT", false).replace(/\/+$/, "");
+    const proxySecret = getEnvVar("TELEGRAM_PROXY_SECRET", false);
+    const forceIpv4 = getOptionalBooleanEnvVar("TELEGRAM_FORCE_IPV4", false);
+    if (proxyUrl && apiRoot) {
+        throw new Error("TELEGRAM_PROXY_URL and TELEGRAM_API_ROOT are alternative connectivity modes and cannot be used together. " +
+            "TELEGRAM_PROXY_URL tunnels TCP through a SOCKS/HTTP forward proxy; " +
+            "TELEGRAM_API_ROOT routes API calls through an HTTPS reverse proxy. Pick one.");
+    }
+    if (proxySecret && !apiRoot) {
+        throw new Error("TELEGRAM_PROXY_SECRET requires TELEGRAM_API_ROOT to be set. " +
+            "Without a custom API root, the secret header would be sent to api.telegram.org.");
+    }
+    return {
         token: getEnvVar("TELEGRAM_BOT_TOKEN"),
         allowedUserId: parseInt(getEnvVar("TELEGRAM_ALLOWED_USER_ID"), 10),
-        proxyUrl: getEnvVar("TELEGRAM_PROXY_URL", false),
-    },
+        proxyUrl,
+        apiRoot,
+        proxySecret,
+        forceIpv4,
+    };
+}
+export const config = {
+    telegram: buildTelegramConfig(),
     opencode: {
         apiUrl: getEnvVar("OPENCODE_API_URL", false) || "http://localhost:4096",
         username: getEnvVar("OPENCODE_SERVER_USERNAME", false) || "opencode",

package/dist/opencode/auto-restart.js

@@ -5,12 +5,35 @@ import { opencodeReadyLifecycle } from "./ready-lifecycle.js";
 import { resolveLocalOpencodeTarget, startLocalOpencodeServer, } from "./process.js";
 const SERVER_READY_TIMEOUT_MS = 10000;
 const SERVER_READY_POLL_INTERVAL_MS = 500;
+const HEALTH_CHECK_TIMEOUT_MS = 3000;
+const HEALTH_CHECK_TIMED_OUT = Symbol("health-check-timed-out");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function withTimeout(promise, timeoutMs) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timeout = setTimeout(() => resolve(HEALTH_CHECK_TIMED_OUT), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
 async function isOpencodeServerHealthy() {
     try {
-        const { data, error } = await opencodeClient.global.health();
+        const result = await withTimeout(opencodeClient.global.health(), HEALTH_CHECK_TIMEOUT_MS);
+        if (result === HEALTH_CHECK_TIMED_OUT) {
+            logger.warn(`[OpenCodeAutoRestart] Health-check timed out after ${HEALTH_CHECK_TIMEOUT_MS}ms`);
+            return false;
+        }
+        const { data, error } = result;
         return !error && data?.healthy === true;
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grinev/opencode-telegram-bot",
-  "version": "0.20.2",
+  "version": "0.20.4",
   "description": "Telegram bot client for OpenCode to run and monitor coding tasks from chat.",
   "type": "module",
   "main": "./dist/index.js",
@@ -59,6 +59,7 @@
     "grammy": "^1.39.2",
     "https-proxy-agent": "^7.0.6",
     "mdast-util-to-string": "^4.0.0",
+    "node-fetch": "^2.7.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "socks-proxy-agent": "^8.0.5",