@mulmobridge/telegram 1.0.2 → 1.2.0

package/README.md

@@ -28,15 +28,17 @@ yarn telegram
 |---|---|---|---|
 | `TELEGRAM_BOT_TOKEN` | Yes | BotFather token | - |
 | `TELEGRAM_ALLOWED_CHAT_IDS` | Yes | Comma-separated integer chat IDs | empty (deny all) |
-| `MULMOCLAUDE_API_URL` | No | Server URL | `http://localhost:3001` |
+| `MULMOCLAUDE_API_URL` | No | Server URL | auto (`.server-port`; waits if nothing is published) |
 | `MULMOCLAUDE_AUTH_TOKEN` | No | Bearer token override | reads from file |
 | `TELEGRAM_POLL_TIMEOUT_SEC` | No | Long-poll timeout | `25` |
 
 ### Auth token persistence across server restarts
 
-The MulmoClaude server regenerates a fresh bearer token on every startup and writes it to `~/mulmoclaude/.session-token`. The bridge reads that file once at launch and keeps the token in memory — so if the server restarts while the bridge is running, the bridge keeps using the **old** token and every API call returns **401**, silently.
+The MulmoClaude server regenerates a fresh bearer token on every startup and writes it to `<workspace>/.session-token` (`$MULMOCLAUDE_WORKSPACE_PATH`, or `~/mulmoclaude` when unset), alongside the port it bound in `.server-port`.
 
-**Fix**: set `MULMOCLAUDE_AUTH_TOKEN` to the same long random value on **both** the server and the bridge. The server uses it verbatim instead of regenerating, so the token survives restarts and the bridge stays authenticated.
+**The bridge follows a restart on its own.** When the connection fails it re-reads both files, and if the server came back as a different generation — new token, new port, or both — it rebuilds its socket against it (#3078). You do not have to restart the bridge.
+
+Pinning the token is still useful when the bridge runs **on a different machine** from the server, where it cannot read the workspace at all: set `MULMOCLAUDE_AUTH_TOKEN` to the same long random value on both sides. The server then uses it verbatim instead of regenerating.
 
 ```bash
 # Server (one-time setup — same value across restarts)

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
@@ -12,92 +16,42 @@
 //   MULMOCLAUDE_AUTH_TOKEN      — optional override
 //   TELEGRAM_POLL_TIMEOUT_SEC   — optional, default 25
 import "dotenv/config";
-import { createBridgeClient } 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 { createBridgeClient, installProcessGuards } from "@mulmobridge/client";
+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),
+    // 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: () => {
+            started.handle?.close();
+        },
     });
-    // 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();
-    process.on("SIGINT", () => {
-        console.log("\nShutting down...");
-        abortController.abort();
-        client.close();
-        process.exit(0);
-    });
-    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/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.0.2",
+  "version": "1.2.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": {
@@ -30,12 +36,12 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/client": "^1.0.2",
+    "@mulmobridge/client": "^1.3.0",
     "@mulmobridge/protocol": "^1.0.1",
     "dotenv": "^17.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.5.1",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/bridges/telegram#readme",