@mulmobridge/telegram 1.1.0 → 1.3.0

package/README.md

@@ -61,6 +61,7 @@ The bridge enforces a **chat-ID allowlist**. Only messages from listed chat IDs
 - Long-polling (no webhook setup needed)
 - Photo attachment support (downloads and forwards to Claude vision)
 - Long-message chunking (splits replies > 4096 chars)
+- "typing…" while MulmoClaude works on a reply, from receipt until the final reply is sent (including before the first streamed text and while tools run)
 - Server push delivery (Phase B of #268)
 - Graceful shutdown on SIGINT
 

package/dist/api.d.ts

@@ -50,15 +50,20 @@ export interface GetUpdatesOptions {
     timeoutSec?: number | undefined;
     signal?: AbortSignal | undefined;
 }
+export type TelegramChatAction = "typing";
 export interface TelegramApi {
     getUpdates(opts?: GetUpdatesOptions): Promise<TelegramUpdate[]>;
     /** Send a message and return its message_id (needed for editMessageText). */
     sendMessage(chatId: number, text: string): Promise<number>;
     /** Edit an existing message in place. Used for streaming text updates. */
     editMessageText(chatId: number, messageId: number, text: string): Promise<void>;
+    /** Show a chat action such as "typing…" until the next message or about 5 s. */
+    sendChatAction(chatId: number, action: TelegramChatAction): Promise<void>;
     /** Download any file by file_id via the Telegram getFile API.
      *  Returns a data URL (`data:<mime>;base64,...`).
      *  Works for photos, documents, audio, etc. */
     downloadFile(fileId: string, fallbackMime?: string): Promise<string>;
 }
 export declare function createTelegramApi(opts: TelegramApiOptions): TelegramApi;
+/** The description of a `{ ok: false }` Bot API body, or null when the body does not report a failure. */
+export declare function apiFailureDescription(body: unknown): string | null;

package/dist/api.js

@@ -54,6 +54,20 @@ export function createTelegramApi(opts) {
                 return;
             }
         },
+        async sendChatAction(chatId, action) {
+            const res = await fetchImpl(`${base}/sendChatAction`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ chat_id: chatId, action }),
+            });
+            if (!res.ok) {
+                throw new Error(`sendChatAction failed: ${res.status} ${await safeText(res)}`);
+            }
+            const failure = apiFailureDescription(await res.json().catch(() => null));
+            if (failure !== null) {
+                throw new Error(`sendChatAction API error: ${failure}`);
+            }
+        },
         async downloadFile(fileId, fallbackMime = "application/octet-stream") {
             const getFileRes = await fetchImpl(`${base}/getFile?file_id=${encodeURIComponent(fileId)}`);
             if (!getFileRes.ok) {
@@ -79,6 +93,12 @@ export function createTelegramApi(opts) {
         },
     };
 }
+/** The description of a `{ ok: false }` Bot API body, or null when the body does not report a failure. */
+export function apiFailureDescription(body) {
+    if (typeof body !== "object" || body === null || !("ok" in body) || body.ok !== false)
+        return null;
+    return "description" in body && typeof body.description === "string" ? body.description : "unknown";
+}
 async function safeText(res) {
     try {
         return await res.text();

package/dist/index.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
-// Telegram bridge (issue #321). Polls Telegram for incoming
+// Telegram bridge (issue #321) — the CLI. Polls Telegram for incoming
 // messages and dispatches them through the shared message router,
 // which enforces the chat-ID allowlist, forwards to MulmoClaude,
 // and delivers Phase-B pushes back through sendMessage.
 //
+// The bridge itself lives in `./start.js` so the server can run it
+// in-process (#3080). This file is the env-reading, `process.exit`-calling
+// half that only a CLI wants.
+//
 // Env surface (see docs/message_apps/telegram/README.md):
 //   TELEGRAM_BOT_TOKEN          — BotFather token (required)
 //   TELEGRAM_ALLOWED_CHAT_IDS   — CSV of integer chat IDs (required
@@ -13,95 +17,41 @@
 //   TELEGRAM_POLL_TIMEOUT_SEC   — optional, default 25
 import "dotenv/config";
 import { createBridgeClient, installProcessGuards } from "@mulmobridge/client";
-import { createTelegramApi } from "./api.js";
-import { parseAllowlist } from "./allowlist.js";
-import { createMessageRouter } from "./router.js";
-const TRANSPORT_ID = "telegram";
-function readEnv() {
-    const botToken = process.env.TELEGRAM_BOT_TOKEN;
-    if (!botToken || botToken.trim().length === 0) {
-        console.error("TELEGRAM_BOT_TOKEN is required. See docs/message_apps/telegram/.");
-        process.exit(1);
-    }
-    let allowlist;
+import { readTelegramEnv, startTelegramBridge, TELEGRAM_TRANSPORT_ID as TRANSPORT_ID } from "./start.js";
+async function main() {
+    // `readTelegramEnv` throws; the CLI turns that into the same message and exit
+    // code it printed when the reading lived here.
+    let config;
     try {
-        allowlist = parseAllowlist(process.env.TELEGRAM_ALLOWED_CHAT_IDS);
+        config = readTelegramEnv(process.env);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
-    const pollTimeoutSec = Number(process.env.TELEGRAM_POLL_TIMEOUT_SEC ?? "25");
-    if (!Number.isInteger(pollTimeoutSec) || pollTimeoutSec < 0) {
-        console.error("TELEGRAM_POLL_TIMEOUT_SEC must be a non-negative integer");
-        process.exit(1);
-    }
-    return { botToken, allowlist, pollTimeoutSec };
-}
-async function pollLoop(api, router, opts) {
-    let offset;
-    while (!opts.abortSignal.aborted) {
-        let updates;
-        try {
-            updates = await api.getUpdates({
-                offset,
-                timeoutSec: opts.pollTimeoutSec,
-                signal: opts.abortSignal,
-            });
-        }
-        catch (err) {
-            if (opts.abortSignal.aborted)
-                return;
-            console.error(`[telegram] getUpdates error: ${String(err)}`);
-            // Back off briefly so a broken network doesn't busy-loop.
-            await delay(1000);
-            continue;
-        }
-        for (const update of updates) {
-            offset = update.update_id + 1;
-            if (update.message) {
-                await router.handleMessage(update.message);
-            }
-        }
-    }
-}
-function delay(ms) {
-    return new Promise((r) => setTimeout(r, ms));
-}
-async function main() {
-    const { botToken, allowlist, pollTimeoutSec } = readEnv();
+    const { botToken, allowlist, pollTimeoutSec } = config;
     console.log("MulmoClaude Telegram bridge");
     console.log(`Allowlist: ${allowlist.size() > 0 ? allowlist.snapshot().join(", ") : "(empty — all chats will be denied)"}`);
-    const api = createTelegramApi({ botToken });
-    const client = createBridgeClient({ transportId: TRANSPORT_ID });
-    const router = createMessageRouter({
-        api,
-        allowlist,
-        sendToMulmo: (chatId, text, attachments) => client.send(chatId, text, attachments),
-    });
-    // Server → Telegram streaming text chunks (Phase C of #268).
-    client.onTextChunk((chunk) => {
-        router.handleTextChunk(chunk);
-    });
-    // Server → Telegram async push (Phase B of #268).
-    client.onPush((ev) => {
-        router.handlePush(ev).catch((err) => console.error(`[telegram] handlePush failed: ${String(err)}`));
-    });
-    const abortController = new AbortController();
-    // Installed here rather than at module level because the shutdown work needs
-    // the controller and the socket. `main().catch` still covers the awaited
-    // startup path above, so nothing is unguarded in between.
+    // Guards BEFORE the bridge starts. Splitting the bridge into a library moved
+    // the poll loop's start from `await pollLoop(...)` to inside
+    // `startTelegramBridge`, which would otherwise leave a window where the loop
+    // is running and a signal is still unhandled. The holder is what lets the
+    // shutdown callback reach a handle that does not exist yet.
+    const started = { handle: null };
     installProcessGuards({
         name: TRANSPORT_ID,
         onShutdown: () => {
-            abortController.abort();
-            client.close();
+            started.handle?.close();
         },
     });
-    await pollLoop(api, router, {
+    const handle = startTelegramBridge({
+        botToken,
+        allowlist,
         pollTimeoutSec,
-        abortSignal: abortController.signal,
+        client: createBridgeClient({ transportId: TRANSPORT_ID }),
     });
+    started.handle = handle;
+    await handle.done;
 }
 main().catch((err) => {
     console.error("Fatal:", err);

package/dist/router.js

@@ -3,7 +3,7 @@
 // Telegram API, no real MulmoClaude socket, no env reads). The
 // entrypoint in index.ts is then just: read env → wire real deps →
 // drive the polling loop.
-import { parseDataUrl } from "@mulmobridge/client";
+import { parseDataUrl, replyAfterProcessingIndicator } from "@mulmobridge/client";
 // Telegram caps a single message at 4096 chars. We split long
 // replies naively; pretty formatting (preserve markdown, break on
 // sentence boundaries) is a follow-up.
@@ -17,6 +17,8 @@ const defaultLog = {
 // rate limits. 1 second is conservative; Telegram allows ~30 edits
 // per minute per chat.
 const STREAM_EDIT_INTERVAL_MS = 1000;
+// Telegram shows a chat action for about 5 s, or until the next message.
+const TYPING_REFRESH_MS = 4_000;
 export function createMessageRouter(deps) {
     const { api, allowlist, sendToMulmo } = deps;
     const log = deps.log ?? defaultLog;
@@ -132,12 +134,18 @@ export function createMessageRouter(deps) {
             return;
         const mediaLabel = buildMediaLabel(msg);
         log.info(`[telegram] accepted chat=${chatId} user=@${userLabel(msg)} len=${text.length}${mediaLabel}`);
+        await replyAfterProcessingIndicator(() => api.sendChatAction(chatId, "typing"), { produce: () => relay(msg, chatId, text), post: (deliver) => deliver() }, { refreshMs: TYPING_REFRESH_MS, label: "telegram", log });
+    }
+    /** Everything up to the final reply, run while "typing…" shows; returns the
+     *  step that delivers the reply, which runs once the indicator is down. */
+    async function relay(msg, chatId, text) {
         const { attachments, failed } = await tryDownloadAttachments(msg);
         // Attachment-only message where download failed: bail out instead
         // of sending a query without the actual file.
         if (failed && text.trim().length === 0) {
-            await api.sendMessage(chatId, "Sorry, I could not download the attachment. Please try again.").catch(() => { });
-            return;
+            return async () => {
+                await api.sendMessage(chatId, "Sorry, I could not download the attachment. Please try again.").catch(() => { });
+            };
         }
         // Surface the attachment failure so the user knows the file was lost.
         const messageText = resolveMessageText(text, failed);
@@ -149,9 +157,12 @@ export function createMessageRouter(deps) {
         flushStream();
         const sentMsgId = streamMessageId;
         stopStream();
-        // If streaming sent the text, do a final edit with the full ack
-        // to catch any trailing chunks. If no streaming happened,
-        // send the full reply as a new message.
+        return () => deliverFinal(chatId, sentMsgId, ack);
+    }
+    // If streaming sent the text, do a final edit with the full ack
+    // to catch any trailing chunks. If no streaming happened,
+    // send the full reply as a new message.
+    async function deliverFinal(chatId, sentMsgId, ack) {
         if (sentMsgId !== null && ack.ok) {
             await api.editMessageText(chatId, sentMsgId, ack.reply ?? "").catch(() => { });
         }

package/dist/start.d.ts

@@ -0,0 +1,31 @@
+import type { BridgeClient } from "@mulmobridge/client";
+import { type Allowlist } from "./allowlist.js";
+export declare const TELEGRAM_TRANSPORT_ID = "telegram";
+/** Console-compatible shape, matching `RouterDeps["log"]`. */
+export interface BridgeLog {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+}
+export interface TelegramStartOptions {
+    botToken: string;
+    allowlist: Allowlist;
+    /** Long-poll timeout handed to `getUpdates`. */
+    pollTimeoutSec: number;
+    /** Supplied by the caller so the CLI can pass a socket client and the server
+     *  an in-process one. */
+    client: BridgeClient;
+    log?: BridgeLog;
+}
+export interface BridgeHandle {
+    /** Stops polling and releases the client. Idempotent. */
+    close: () => void;
+    /** Resolves when the poll loop has stopped. The CLI awaits it; a host that
+     *  starts many bridges attaches a rejection handler instead. */
+    done: Promise<void>;
+}
+/** The env this bridge needs, read from an explicit bag rather than
+ *  `process.env` and THROWING rather than exiting, so the server can start it
+ *  in-process (#3080) while the CLI keeps its own exit codes. */
+export declare function readTelegramEnv(env: Record<string, string | undefined>): Omit<TelegramStartOptions, "client" | "log">;
+export declare function startTelegramBridge(opts: TelegramStartOptions): BridgeHandle;

package/dist/start.js

@@ -0,0 +1,82 @@
+// The Telegram bridge as a LIBRARY (#3080): everything the CLI used to do
+// inline, minus the two things a host cannot tolerate — reading `process.env`
+// and calling `process.exit`.
+//
+// Configuration arrives as arguments and failures arrive as thrown errors, so
+// the same code serves `yarn telegram` (which reads env and exits) and the
+// server's in-process registry (which logs and keeps running).
+import { createTelegramApi } from "./api.js";
+import { parseAllowlist } from "./allowlist.js";
+import { createMessageRouter } from "./router.js";
+export const TELEGRAM_TRANSPORT_ID = "telegram";
+const DEFAULT_POLL_TIMEOUT_SEC = 25;
+/** The env this bridge needs, read from an explicit bag rather than
+ *  `process.env` and THROWING rather than exiting, so the server can start it
+ *  in-process (#3080) while the CLI keeps its own exit codes. */
+export function readTelegramEnv(env) {
+    const botToken = env.TELEGRAM_BOT_TOKEN;
+    if (!botToken || botToken.trim().length === 0) {
+        throw new Error("TELEGRAM_BOT_TOKEN is required. See docs/message_apps/telegram/.");
+    }
+    const allowlist = parseAllowlist(env.TELEGRAM_ALLOWED_CHAT_IDS);
+    const pollTimeoutSec = Number(env.TELEGRAM_POLL_TIMEOUT_SEC ?? String(DEFAULT_POLL_TIMEOUT_SEC));
+    if (!Number.isInteger(pollTimeoutSec) || pollTimeoutSec < 0) {
+        throw new Error("TELEGRAM_POLL_TIMEOUT_SEC must be a non-negative integer");
+    }
+    return { botToken, allowlist, pollTimeoutSec };
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const POLL_ERROR_BACKOFF_MS = 1000;
+async function pollLoop(api, router, opts) {
+    let offset;
+    while (!opts.abortSignal.aborted) {
+        let updates;
+        try {
+            updates = await api.getUpdates({ offset, timeoutSec: opts.pollTimeoutSec, signal: opts.abortSignal });
+        }
+        catch (err) {
+            if (opts.abortSignal.aborted)
+                return;
+            opts.log.error(`[telegram] getUpdates error: ${String(err)}`);
+            // Back off briefly so a broken network doesn't busy-loop.
+            await delay(POLL_ERROR_BACKOFF_MS);
+            continue;
+        }
+        for (const update of updates) {
+            offset = update.update_id + 1;
+            if (update.message) {
+                await router.handleMessage(update.message);
+            }
+        }
+    }
+}
+export function startTelegramBridge(opts) {
+    const log = opts.log ?? console;
+    const api = createTelegramApi({ botToken: opts.botToken });
+    const router = createMessageRouter({
+        api,
+        allowlist: opts.allowlist,
+        sendToMulmo: (chatId, text, attachments) => opts.client.send(chatId, text, attachments),
+    });
+    // Server → Telegram streaming text chunks (Phase C of #268).
+    opts.client.onTextChunk((chunk) => {
+        router.handleTextChunk(chunk);
+    });
+    // Server → Telegram async push (Phase B of #268).
+    opts.client.onPush((event) => {
+        router.handlePush(event).catch((err) => log.error(`[telegram] handlePush failed: ${String(err)}`));
+    });
+    const abortController = new AbortController();
+    let closed = false;
+    const done = pollLoop(api, router, { pollTimeoutSec: opts.pollTimeoutSec, abortSignal: abortController.signal, log });
+    return {
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            abortController.abort();
+            opts.client.close();
+        },
+        done,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/telegram",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Telegram bridge for MulmoBridge — connect a Telegram bot to MulmoClaude",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,12 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./start": {
+      "types": "./dist/start.d.ts",
+      "import": "./dist/start.js",
+      "require": "./dist/start.js",
+      "default": "./dist/start.js"
     }
   },
   "bin": {
@@ -23,19 +29,19 @@
   "scripts": {
     "build": "tsc",
     "prepack": "yarn build",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
     "test": "tsx --test test/test_*.ts",
     "lint": "eslint src test"
   },
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/client": "^1.2.0",
-    "@mulmobridge/protocol": "^1.0.1",
-    "dotenv": "^17.0.0"
+    "@mulmobridge/client": "^1.5.0",
+    "@mulmobridge/protocol": "^1.1.0",
+    "dotenv": "^18.0.8"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.5",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/bridges/telegram#readme",