@mulmobridge/telegram 1.2.0 → 1.3.1

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/router.js

@@ -3,7 +3,8 @@
 // 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 { createReplyStream } from "./stream.js";
+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,57 +18,29 @@ 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;
     // One denial reply per chat per bridge lifetime — restart clears.
     const deniedAlreadyNotified = new Set();
-    // Streaming state: while a relay is in flight, chunks accumulate
-    // here. A timer periodically flushes them via editMessageText.
-    let streamChatId = null;
-    let streamMessageId = null;
-    let streamAccumulated = "";
-    let streamDirty = false;
-    let streamTimer = null;
-    function startStream(chatId) {
-        streamChatId = chatId;
-        streamMessageId = null;
-        streamAccumulated = "";
-        streamDirty = false;
-        streamTimer = setInterval(flushStream, STREAM_EDIT_INTERVAL_MS);
-    }
-    function stopStream() {
-        if (streamTimer !== null) {
-            clearInterval(streamTimer);
-            streamTimer = null;
-        }
-        streamChatId = null;
-        streamMessageId = null;
-        streamAccumulated = "";
-        streamDirty = false;
-    }
-    function flushStream() {
-        if (!streamDirty || streamChatId === null)
-            return;
-        streamDirty = false;
-        const chatId = streamChatId;
-        const text = streamAccumulated || "…";
-        if (streamMessageId === null) {
-            // First flush: send a new message
-            api
-                .sendMessage(chatId, text)
-                .then((msgId) => {
-                streamMessageId = msgId;
-            })
-                .catch((err) => {
-                log.error(`[telegram] stream sendMessage failed: ${String(err)}`);
-            });
+    // The reply stream of the request in flight. Chunks carry no chat id; the
+    // polling loop handles one message at a time, so they belong to this one.
+    const inFlight = { stream: null };
+    /** Runs `work` while its streamed chunks are mirrored into the chat. The
+     *  timer is stopped even when `work` throws. */
+    async function streamWhile(chatId, work) {
+        const stream = createReplyStream(api, chatId, log, STREAM_EDIT_INTERVAL_MS);
+        inFlight.stream = stream;
+        try {
+            const result = await work();
+            return { result, streamedMessageId: await stream.finish() };
         }
-        else {
-            // Subsequent flushes: edit existing message
-            api.editMessageText(chatId, streamMessageId, text).catch((err) => {
-                log.error(`[telegram] stream editMessage failed: ${String(err)}`);
-            });
+        finally {
+            stream.stop();
+            if (inFlight.stream === stream)
+                inFlight.stream = null;
         }
     }
     // Download all media from a message. Telegram messages are usually
@@ -132,32 +105,32 @@ 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);
-        // Start streaming: chunks will arrive via handleTextChunk and
-        // be sent/edited in the Telegram chat in real time.
-        startStream(chatId);
-        const ack = await sendToMulmo(String(chatId), messageText, attachments.length > 0 ? attachments : undefined);
-        // Final flush + capture the message id before stopStream clears it.
-        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.
-        if (sentMsgId !== null && ack.ok) {
-            await api.editMessageText(chatId, sentMsgId, ack.reply ?? "").catch(() => { });
-        }
-        else if (sentMsgId === null) {
-            await sendReply(chatId, ack);
+        const { result: ack, streamedMessageId } = await streamWhile(chatId, () => sendToMulmo(String(chatId), messageText, attachments.length > 0 ? attachments : undefined));
+        return () => deliverFinal(chatId, streamedMessageId, ack);
+    }
+    // A streamed reply is completed in place; an error after streaming is sent
+    // as its own message so the partial text is not the last word.
+    async function deliverFinal(chatId, streamedMessageId, ack) {
+        if (streamedMessageId !== null && ack.ok) {
+            await api.editMessageText(chatId, streamedMessageId, ack.reply ?? "").catch(() => { });
+            return;
         }
+        await sendReply(chatId, ack);
     }
     async function handleDenied(msg) {
         const chatId = msg.chat.id;
@@ -199,10 +172,7 @@ export function createMessageRouter(deps) {
             }
         },
         handleTextChunk(chunk) {
-            if (streamChatId === null)
-                return;
-            streamAccumulated += chunk;
-            streamDirty = true;
+            inFlight.stream?.append(chunk);
         },
         deniedAlreadyNotified() {
             return deniedAlreadyNotified;

package/dist/stream.d.ts

@@ -0,0 +1,14 @@
+import type { TelegramApi } from "./api.js";
+interface StreamLog {
+    error: (msg: string) => void;
+}
+export interface ReplyStream {
+    append(chunk: string): void;
+    /** Stops the timer, sends what is pending, and resolves to the id of the
+     *  streamed message — or null when nothing was streamed. */
+    finish(): Promise<number | null>;
+    /** Stops the timer without sending anything more. Safe to call twice. */
+    stop(): void;
+}
+export declare function createReplyStream(api: TelegramApi, chatId: number, log: StreamLog, interval_ms: number): ReplyStream;
+export {};

package/dist/stream.js

@@ -0,0 +1,50 @@
+// One streamed reply: chunks accumulate here and a timer mirrors them into a
+// single Telegram message (sent once, then edited). Created per request so a
+// failed request cannot leave its timer or text behind for the next one.
+export function createReplyStream(api, chatId, log, interval_ms) {
+    const state = { accumulated: "", dirty: false, messageId: null, flushChain: Promise.resolve(), timer: null };
+    async function sendOrEdit(text) {
+        if (state.messageId === null) {
+            state.messageId = await api.sendMessage(chatId, text);
+            return;
+        }
+        await api.editMessageText(chatId, state.messageId, text);
+    }
+    async function flushPending() {
+        if (!state.dirty)
+            return;
+        state.dirty = false;
+        const action = state.messageId === null ? "sendMessage" : "editMessage";
+        try {
+            await sendOrEdit(state.accumulated || "…");
+        }
+        catch (err) {
+            log.error(`[telegram] stream ${action} failed: ${String(err)}`);
+        }
+    }
+    function flush() {
+        state.flushChain = state.flushChain.then(flushPending);
+        return state.flushChain;
+    }
+    function stop() {
+        if (state.timer === null)
+            return;
+        clearInterval(state.timer);
+        state.timer = null;
+    }
+    state.timer = setInterval(() => void flush(), interval_ms);
+    return {
+        append(chunk) {
+            if (state.timer === null)
+                return;
+            state.accumulated += chunk;
+            state.dirty = true;
+        },
+        async finish() {
+            stop();
+            await flush();
+            return state.messageId;
+        },
+        stop,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/telegram",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Telegram bridge for MulmoBridge — connect a Telegram bot to MulmoClaude",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,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.3.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.5.1",
+    "@types/node": "^26.6.5",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/bridges/telegram#readme",