@grinev/opencode-telegram-bot 0.20.1 → 0.20.3

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/bot/handlers/voice.js

@@ -30,7 +30,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 +80,8 @@ 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 apiRoot = (config.telegram.apiRoot ?? "https://api.telegram.org").replace(/\/$/, "");
+        const fileUrl = `${apiRoot}/file/bot${ctx.api.token}/${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,14 @@
+// @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 { config } from "../../config.js";
 import { logger } from "../../utils/logger.js";
-const TELEGRAM_FILE_URL_BASE = "https://api.telegram.org/file/bot";
+const DEFAULT_TELEGRAM_FILE_URL_BASE = "https://api.telegram.org/file/bot";
+function fileUrlBase() {
+    return config.telegram.apiRoot
+        ? `${config.telegram.apiRoot.replace(/\/$/, "")}/file/bot`
+        : DEFAULT_TELEGRAM_FILE_URL_BASE;
+}
 const MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024; // 20MB Telegram limit
 /**
  * Download a photo from Telegram servers
@@ -18,7 +26,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 = `${fileUrlBase()}${config.telegram.token}/${file.file_path}`;
     logger.debug(`[FileDownload] Downloading from ${fileUrl.replace(config.telegram.token, "***")}`);
     const fetchOptions = {};
     // Use proxy if configured
@@ -26,7 +34,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/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/events.js

@@ -32,6 +32,65 @@ function waitWithAbort(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isEventLike(value) {
+    return isRecord(value) && typeof value.type === "string" && isRecord(value.properties);
+}
+function normalizeDirectoryForComparison(directory) {
+    const normalized = directory.replace(/\\/g, "/").replace(/\/+$/, "");
+    return /^[a-z]:/i.test(normalized) ? normalized.toLowerCase() : normalized;
+}
+function isSameDirectory(left, right) {
+    return normalizeDirectoryForComparison(left) === normalizeDirectoryForComparison(right);
+}
+function normalizeGlobalEvent(rawEvent, directory) {
+    if (isEventLike(rawEvent)) {
+        return rawEvent;
+    }
+    if (!isRecord(rawEvent) || !("payload" in rawEvent)) {
+        logger.debug("[Events] Ignoring global event with unknown shape");
+        return null;
+    }
+    const eventDirectory = typeof rawEvent.directory === "string" ? rawEvent.directory : null;
+    if (eventDirectory && !isSameDirectory(eventDirectory, directory)) {
+        return null;
+    }
+    if (!isEventLike(rawEvent.payload)) {
+        logger.debug("[Events] Ignoring global event with unknown payload shape");
+        return null;
+    }
+    return rawEvent.payload;
+}
+function normalizeEvent(rawEvent, source, directory) {
+    if (source === "global") {
+        return normalizeGlobalEvent(rawEvent, directory);
+    }
+    if (!isEventLike(rawEvent)) {
+        logger.debug("[Events] Ignoring legacy event with unknown shape");
+        return null;
+    }
+    return rawEvent;
+}
+async function subscribeToGlobalEventStream(signal) {
+    const globalEvents = opencodeClient.global;
+    if (!globalEvents?.event) {
+        throw new Error("Global event subscription is not available");
+    }
+    const result = await globalEvents.event({ signal });
+    if (!result.stream) {
+        throw new Error(FATAL_NO_STREAM_ERROR);
+    }
+    return { source: "global", stream: result.stream };
+}
+async function subscribeToLegacyEventStream(directory, signal) {
+    const result = await opencodeClient.event.subscribe({ directory }, { signal });
+    if (!result.stream) {
+        throw new Error(FATAL_NO_STREAM_ERROR);
+    }
+    return { source: "legacy", stream: result.stream };
+}
 export async function subscribeToEvents(directory, callback) {
     if (isListening && activeDirectory === directory) {
         eventCallback = callback;
@@ -53,14 +112,33 @@ export async function subscribeToEvents(directory, callback) {
     streamAbortController = controller;
     try {
         let reconnectAttempt = 0;
+        let useLegacyEventsOnce = false;
         while (isListening && activeDirectory === directory && !controller.signal.aborted) {
             try {
-                const result = await opencodeClient.event.subscribe({ directory }, { signal: controller.signal });
-                if (!result.stream) {
-                    throw new Error(FATAL_NO_STREAM_ERROR);
+                let subscription;
+                if (useLegacyEventsOnce) {
+                    useLegacyEventsOnce = false;
+                    subscription = await subscribeToLegacyEventStream(directory, controller.signal);
+                }
+                else {
+                    try {
+                        subscription = await subscribeToGlobalEventStream(controller.signal);
+                        logger.debug(`Using global OpenCode event stream for ${directory}`);
+                    }
+                    catch (error) {
+                        if (controller.signal.aborted || !isListening || activeDirectory !== directory) {
+                            throw error;
+                        }
+                        if (isExpectedOpencodeUnavailableError(error)) {
+                            throw error;
+                        }
+                        logger.warn(`Global event stream unavailable for ${directory}, falling back to project event stream`, error);
+                        subscription = await subscribeToLegacyEventStream(directory, controller.signal);
+                    }
                 }
                 reconnectAttempt = 0;
-                eventStream = result.stream;
+                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`);
@@ -69,6 +147,13 @@ export async function subscribeToEvents(directory, callback) {
                     // 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
@@ -81,7 +166,7 @@ export async function subscribeToEvents(directory, callback) {
                                 listenerGeneration !== generation) {
                                 return;
                             }
-                            callbackSnapshot(event);
+                            callbackSnapshot(normalizedEvent);
                         });
                     }
                 }
@@ -89,6 +174,11 @@ export async function subscribeToEvents(directory, callback) {
                 if (!isListening || activeDirectory !== directory || controller.signal.aborted) {
                     break;
                 }
+                if (subscription.source === "global" && usefulEventCount === 0) {
+                    useLegacyEventsOnce = true;
+                    logger.warn(`Global event stream ended without project events for ${directory}, falling back to project event stream`);
+                    continue;
+                }
                 reconnectAttempt++;
                 const reconnectDelay = getReconnectDelayMs(reconnectAttempt);
                 logger.warn(`Event stream ended for ${directory}, reconnecting in ${reconnectDelay}ms (attempt=${reconnectAttempt})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grinev/opencode-telegram-bot",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "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",