cursor-telegram-mcp 0.5.0 → 0.7.0

package/dist/install.js

@@ -0,0 +1,231 @@
+/**
+ * `cursor-telegram-mcp install` / `uninstall` — always-on worker on macOS.
+ *
+ * Generates a per-user launchd agent (no hardcoded paths) so the background
+ * worker starts at login, restarts if it crashes, and keeps the Mac awake
+ * enough to deliver Telegram messages. Designed for the npm-distributed
+ * package: the plist points at the Node that is running this command and the
+ * installed CLI, and config is read from `<configDir>/config.json` (written by
+ * `setup`), so nothing is tied to a checkout location.
+ *
+ * macOS only for now; on other platforms it prints guidance and exits.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, platform, tmpdir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const LABEL = "com.cursor-telegram.worker";
+const WATCHDOG_LABEL = "com.cursor-telegram.watchdog";
+/** Older label used by the in-repo dev scripts; booted out on install to avoid a double-run. */
+const LEGACY_LABEL = "com.cursor-remote-chat.worker";
+/** How often (seconds) the watchdog checks worker /health. */
+const WATCHDOG_INTERVAL_SEC = 120;
+function plistPath(label = LABEL) {
+    return join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+}
+function logPaths() {
+    const dir = join(homedir(), "Library", "Logs");
+    return {
+        out: join(dir, "cursor-telegram-worker.log"),
+        err: join(dir, "cursor-telegram-worker.err.log"),
+    };
+}
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/** Absolute path to the installed CLI entry (dist/cli.js) running this code. */
+function cliEntry() {
+    return fileURLToPath(import.meta.url).replace(/install\.js$/, "cli.js");
+}
+/**
+ * Whether this package lives in a stable location. `npx -y cursor-telegram-mcp`
+ * runs from an ephemeral cache that npm may garbage-collect, which would leave
+ * the launch agent pointing at a path that disappears. A global install
+ * (`npm i -g`) is durable. We refuse to install a launch agent from an
+ * ephemeral path unless explicitly forced.
+ */
+function isDurableInstall() {
+    const p = fileURLToPath(import.meta.url);
+    if (p.includes(`${sep}_npx${sep}`))
+        return false;
+    if (p.startsWith(tmpdir()))
+        return false;
+    return true;
+}
+function buildProgramArguments() {
+    const node = process.execPath;
+    const cli = cliEntry();
+    const caffeinate = "/usr/bin/caffeinate";
+    // caffeinate -ims keeps the system + display awake while the worker runs so
+    // Telegram delivery is never blocked by idle sleep (AC power still required
+    // for a fully closed-lid Mac, which we document in the README).
+    if (existsSync(caffeinate)) {
+        return [caffeinate, "-ims", node, cli, "worker"];
+    }
+    return [node, cli, "worker"];
+}
+function buildPlist() {
+    const args = buildProgramArguments();
+    const { out, err } = logPaths();
+    const nodeDir = dirname(process.execPath);
+    const pathEnv = [nodeDir, "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"].join(":");
+    const argXml = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argXml}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(homedir())}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(pathEnv)}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(out)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(err)}</string>
+</dict>
+</plist>
+`;
+}
+function buildWatchdogPlist() {
+    const node = process.execPath;
+    const cli = cliEntry();
+    const nodeDir = dirname(process.execPath);
+    const pathEnv = [nodeDir, "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"].join(":");
+    const { out, err } = logPaths();
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${WATCHDOG_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(node)}</string>
+    <string>${xmlEscape(cli)}</string>
+    <string>watchdog</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(pathEnv)}</string>
+    <key>TG_WORKER_LABEL</key>
+    <string>${LABEL}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StartInterval</key>
+  <integer>${WATCHDOG_INTERVAL_SEC}</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(out)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(err)}</string>
+</dict>
+</plist>
+`;
+}
+function domain() {
+    return `gui/${process.getuid?.() ?? 501}`;
+}
+function launchctl(args) {
+    try {
+        execFileSync("launchctl", args, { stdio: "ignore" });
+    }
+    catch {
+        // bootout of a non-loaded agent is expected to fail; callers tolerate it
+    }
+}
+function requireMac() {
+    if (platform() !== "darwin") {
+        process.stderr.write("Always-on install is macOS only for now.\n" +
+            "On other systems, run `cursor-telegram-mcp worker` under your own\n" +
+            "process manager (systemd, pm2, a login item, etc.).\n");
+        process.exit(1);
+    }
+}
+export function runInstall() {
+    requireMac();
+    if (!isDurableInstall() && process.env.TG_FORCE_INSTALL !== "1") {
+        process.stderr.write([
+            "This looks like a temporary (npx) copy, which npm may delete later —",
+            "an always-on launch agent must point at a stable install.",
+            "",
+            "Install it globally first, then run install:",
+            "  npm i -g cursor-telegram-mcp",
+            "  cursor-telegram-mcp install",
+            "",
+            "(Set TG_FORCE_INSTALL=1 to override, not recommended.)",
+            "",
+        ].join("\n"));
+        process.exit(1);
+    }
+    const path = plistPath();
+    mkdirSync(dirname(path), { recursive: true });
+    mkdirSync(join(homedir(), "Library", "Logs"), { recursive: true });
+    writeFileSync(path, buildPlist(), "utf8");
+    // Avoid two workers fighting over the port: stop any previous/legacy agent.
+    launchctl(["bootout", domain(), path]);
+    launchctl(["bootout", domain(), join(homedir(), "Library", "LaunchAgents", `${LEGACY_LABEL}.plist`)]);
+    execFileSync("launchctl", ["bootstrap", domain(), path], { stdio: "inherit" });
+    // Watchdog: restarts the worker if it ever goes unreachable or its poll loop
+    // wedges, so the bot is never silently offline while the Mac is on.
+    const wdPath = plistPath(WATCHDOG_LABEL);
+    writeFileSync(wdPath, buildWatchdogPlist(), "utf8");
+    launchctl(["bootout", domain(), wdPath]);
+    execFileSync("launchctl", ["bootstrap", domain(), wdPath], { stdio: "inherit" });
+    const { out } = logPaths();
+    process.stdout.write([
+        `Installed always-on worker: ${path}`,
+        `Installed watchdog (every ${WATCHDOG_INTERVAL_SEC}s): ${wdPath}`,
+        `Logs: ${out}`,
+        "",
+        "It will start now and at every login. To stop it:",
+        "  cursor-telegram-mcp uninstall",
+        "",
+        "Tip: keep the Mac on AC power so it never fully sleeps.",
+        "",
+    ].join("\n"));
+}
+export function runUninstall() {
+    requireMac();
+    const wdPath = plistPath(WATCHDOG_LABEL);
+    launchctl(["bootout", domain(), wdPath]);
+    if (existsSync(wdPath))
+        rmSync(wdPath);
+    const path = plistPath();
+    launchctl(["bootout", domain(), path]);
+    if (existsSync(path))
+        rmSync(path);
+    process.stdout.write("Uninstalled always-on worker and watchdog.\n");
+}
+// Only act when invoked directly as the `install`/`uninstall` subcommand, so
+// other modules (e.g. setup) can import runInstall() without side effects.
+const sub = process.argv[2];
+if (sub === "install" || sub === "uninstall") {
+    if (sub === "uninstall")
+        runUninstall();
+    else
+        runInstall();
+}

package/dist/parseInbound.js

@@ -5,6 +5,18 @@
  * /ask or /plan on any line. Reply-to HITL answers should bypass splitting
  * (caller passes the full text as a single answer).
  */
+/**
+ * Parse an explicit question target prefix like "Q-3 ...", "Q3 ...", "#3 ..."
+ * or "@Q-3 ...". Returns the normalized question id ("Q-3") and the remaining
+ * answer text, or null when the text doesn't start with such a prefix. Used to
+ * let a Telegram reply target a specific pending question when several are open.
+ */
+export function parseTargetId(text) {
+    const m = text.match(/^\s*@?\s*(?:q-?|#)(\d+)\b[\s:.\-]*([\s\S]*)$/i);
+    if (!m)
+        return null;
+    return { id: `Q-${m[1]}`, rest: (m[2] ?? "").trim() };
+}
 /** Standard plan-approval footer sent after Plan (C-n). */
 const APPROVAL_FOOTER_RE = /^\s*reply\s+yes\s+to\s+run\b[\s\S]*\bno\s+to\s+cancel\.?\s*$/i;
 /** True when text is (or ends with) the plan YES/NO footer — not a new task. */
@@ -18,7 +30,9 @@ export function isPlanApprovalFooter(text) {
     const last = lines[lines.length - 1] ?? "";
     return APPROVAL_FOOTER_RE.test(last);
 }
-const STATUS_RE = /^\s*status\s*$/i;
+const STATUS_RE = /^\s*\/?status\s*$/i;
+const PENDING_RE = /^\s*\/?(pending|questions)\s*$/i;
+const RESET_RE = /^\s*\/?(reset|new)\s*$/i;
 const YES_WORDS = "yes|yea|yeah|y|approve|approved|ok|okay|go|do it|כן|אישור|בצע";
 const NO_WORDS = "no|n|cancel|stop|reject|nope|לא|ביטול|עצור";
 const YES_ONLY_RE = new RegExp(`^\\s*(${YES_WORDS})\\s*[!.]?\\s*$`, "i");
@@ -52,6 +66,10 @@ function parseCommandLine(part) {
 function classifyPart(part) {
     if (STATUS_RE.test(part))
         return [{ kind: "status" }];
+    if (PENDING_RE.test(part))
+        return [{ kind: "pending" }];
+    if (RESET_RE.test(part))
+        return [{ kind: "reset" }];
     if (YES_ONLY_RE.test(part))
         return [{ kind: "approve" }];
     if (NO_ONLY_RE.test(part))
@@ -85,9 +103,23 @@ export function splitInboundMessage(text) {
     if (isPlanApprovalFooter(trimmed)) {
         return [{ kind: "approval_footer" }];
     }
-    const segments = [];
+    const raw = [];
     for (const part of splitParts(trimmed)) {
-        segments.push(...classifyPart(part));
+        raw.push(...classifyPart(part));
+    }
+    // Coalesce consecutive plain segments into ONE task. Without this, a single
+    // multi-line free-text paste is split per line into many separate plan tasks
+    // (the cause of a runaway where one paste spawned C-1..C-n). Explicit /ask
+    // and /plan commands and leading approve/reject stay as their own segments.
+    const segments = [];
+    for (const seg of raw) {
+        const prev = segments[segments.length - 1];
+        if (seg.kind === "plain" && prev && prev.kind === "plain") {
+            prev.text = `${prev.text}\n${seg.text}`;
+        }
+        else {
+            segments.push(seg);
+        }
     }
     return segments;
 }

package/dist/setup.js

@@ -9,7 +9,9 @@
  */
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
+import { platform } from "node:os";
 import { configFilePath, readFileConfig, writeFileConfig } from "./config.js";
+import { runInstall } from "./install.js";
 async function tg(token, method, params) {
     const res = await fetch(`https://api.telegram.org/bot${token}/${method}`, {
         method: "POST",
@@ -101,21 +103,39 @@ async function main() {
             out("Skipped. Notifications and questions still work; enable later by re-running setup.");
         }
         out("");
-        out("Done. Config saved to:");
+        out("Config saved to:");
         out(`  ${configFilePath()}`);
         out("");
-        out("Add this to your project's .cursor/mcp.json (or Cursor Settings -> MCP):");
+        out("Step 4 (recommended): keep your bot online whenever your computer is on.");
+        out("This runs a tiny background worker that starts at login and restarts");
+        out("itself if it ever stops - no need to open Cursor or run anything.");
+        if (platform() === "darwin") {
+            const yes = (await rl.question("Install the always-on service now? [Y/n]: ")).trim().toLowerCase();
+            if (yes === "" || yes === "y" || yes === "yes") {
+                try {
+                    runInstall();
+                }
+                catch (err) {
+                    out(`Could not install the service automatically: ${String(err)}`);
+                    out("You can run it later with: cursor-telegram-mcp install");
+                }
+            }
+            else {
+                out("Skipped. Enable it later with: cursor-telegram-mcp install");
+            }
+        }
+        else {
+            out("On Linux/Windows, run `cursor-telegram-mcp worker` under your service");
+            out("manager (systemd / Task Scheduler) so it starts at boot.");
+        }
+        out("");
+        out("Optional: to let Cursor agents message you, add this to a project's");
+        out(".cursor/mcp.json (or Cursor Settings -> MCP), then reload MCP:");
         out("");
-        out('  {');
-        out('    "mcpServers": {');
-        out('      "telegram": {');
-        out('        "command": "npx",');
-        out('        "args": ["-y", "cursor-telegram-mcp"]');
-        out('      }');
-        out('    }');
-        out('  }');
+        out('  { "mcpServers": { "telegram": { "command": "npx",');
+        out('      "args": ["-y", "cursor-telegram-mcp"] } } }');
         out("");
-        out("Then reload MCP in Cursor. The worker auto-starts with the MCP server.");
+        out("You're set - text your bot to test it.");
     }
     finally {
         rl.close();

package/dist/store.js

@@ -1,26 +1,49 @@
+/**
+ * Pending-question store with optional disk persistence.
+ *
+ * When a `persistPath` is given, the store is loaded on construction and saved
+ * (debounced) on every change, so pending questions survive a worker restart and
+ * remain answerable. Without a path it behaves as a pure in-memory store.
+ * Answered questions are kept briefly so a poll that arrives after the reply can
+ * still read it, then pruned to bound memory (and to bound the persisted file).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 /** Keep answered questions this long after they are answered, then prune. */
 const ANSWERED_TTL_MS = 60 * 60_000;
+/** Debounce window for writing the persisted store to disk. */
+const SAVE_DEBOUNCE_MS = 200;
 export class QuestionStore {
     nextId = 1;
     questions = new Map();
+    persistPath;
+    saveTimer;
+    constructor(opts = {}) {
+        this.persistPath = opts.persistPath;
+        this.load();
+    }
     /** Create a new pending question. */
-    addQuestion(projectLabel, question) {
+    addQuestion(projectLabel, question, agentLabel) {
         this.prune();
         const record = {
             id: `Q-${this.nextId++}`,
             projectLabel,
+            agentLabel: agentLabel && agentLabel !== "" ? agentLabel : undefined,
             question,
             status: "pending",
             createdAt: Date.now(),
         };
         this.questions.set(record.id, record);
+        this.scheduleSave();
         return record;
     }
     /** Attach the outgoing Telegram message id to a question. */
     setSentMessageId(id, messageId) {
         const record = this.questions.get(id);
-        if (record)
+        if (record) {
             record.sentMessageId = messageId;
+            this.scheduleSave();
+        }
     }
     /** Look up a single question by id. */
     get(id) {
@@ -42,40 +65,102 @@ export class QuestionStore {
     }
     /**
      * Match an inbound message to a pending question and record the answer.
-     * Prefers an exact reply-to match; otherwise answers the oldest pending
-     * question (FIFO). Returns the answered record, or null if nothing matched.
+     * Resolution order: an explicit `targetId` > an exact reply-to (swipe) match >
+     * the sole pending question. When more than one question is pending and there
+     * is no target or reply-to, returns null so the caller can disambiguate (we no
+     * longer silently answer the oldest). A `targetId` that is not pending also
+     * returns null. `answerText` overrides the recorded answer (used when the id
+     * prefix has been stripped from the inbound text).
      */
-    matchAndAnswer(incoming) {
+    matchAndAnswer(incoming, opts = {}) {
         const pendings = [...this.questions.values()]
             .filter((q) => q.status === "pending")
             .sort((a, b) => a.createdAt - b.createdAt);
         if (pendings.length === 0)
             return null;
         let target;
-        if (incoming.quotedMessageId) {
+        if (opts.targetId) {
+            target = pendings.find((q) => q.id === opts.targetId);
+            if (!target)
+                return null; // unknown / already-answered target
+        }
+        else if (incoming.quotedMessageId) {
             target = pendings.find((q) => q.sentMessageId && q.sentMessageId === incoming.quotedMessageId);
         }
-        if (!target)
-            target = pendings[0];
+        if (!target) {
+            if (pendings.length === 1)
+                target = pendings[0];
+            else
+                return null; // ambiguous: caller disambiguates
+        }
         target.status = "answered";
-        target.answer = incoming.text;
+        target.answer = opts.answerText ?? incoming.text;
         if (incoming.attachments.length > 0) {
             target.answerAttachments = incoming.attachments;
         }
         target.answeredAt = incoming.timestamp || Date.now();
+        this.scheduleSave();
         return target;
     }
     /** Drop answered questions older than the TTL. */
     prune() {
         const cutoff = Date.now() - ANSWERED_TTL_MS;
+        let removed = false;
         for (const [id, q] of this.questions) {
             if (q.status === "answered" && (q.answeredAt ?? q.createdAt) < cutoff) {
                 this.questions.delete(id);
+                removed = true;
+            }
+        }
+        if (removed)
+            this.scheduleSave();
+    }
+    /** Load persisted questions (best-effort) on startup. */
+    load() {
+        if (!this.persistPath)
+            return;
+        try {
+            const data = JSON.parse(readFileSync(this.persistPath, "utf8"));
+            if (Array.isArray(data.questions)) {
+                for (const q of data.questions) {
+                    if (q && typeof q.id === "string")
+                        this.questions.set(q.id, q);
+                }
             }
+            if (typeof data.nextId === "number" && data.nextId > this.nextId) {
+                this.nextId = data.nextId;
+            }
+            this.prune();
+        }
+        catch {
+            // No (or unreadable) persisted state: start fresh.
+        }
+    }
+    /** Debounced write so bursts of changes coalesce into one disk write. */
+    scheduleSave() {
+        if (!this.persistPath || this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = undefined;
+            this.saveNow();
+        }, SAVE_DEBOUNCE_MS);
+        this.saveTimer.unref?.();
+    }
+    /** Write the current state to disk now (best-effort). */
+    saveNow() {
+        if (!this.persistPath)
+            return;
+        try {
+            mkdirSync(dirname(this.persistPath), { recursive: true });
+            const data = { nextId: this.nextId, questions: [...this.questions.values()] };
+            writeFileSync(this.persistPath, JSON.stringify(data), "utf8");
+        }
+        catch {
+            // Best-effort persistence: a failed write must not break the worker.
         }
     }
 }
-/** Build a fresh in-memory store. */
-export function createStore() {
-    return new QuestionStore();
+/** Build a store, optionally backed by a JSON file at `opts.persistPath`. */
+export function createStore(opts = {}) {
+    return new QuestionStore(opts);
 }

package/dist/telegram.js

@@ -59,6 +59,8 @@ export class TelegramClient {
     stopping = false;
     offset = 0;
     me = null;
+    /** Last time getUpdates returned successfully (ms epoch); liveness signal. */
+    lastPollOkAt = Date.now();
     constructor(opts) {
         this.opts = opts;
         this.logger = opts.logger ?? silentLogger();
@@ -70,23 +72,46 @@ export class TelegramClient {
     isOpen() {
         return this.open;
     }
+    /**
+     * Milliseconds since getUpdates last returned successfully. A large value
+     * while `open` means the poll loop is stuck (e.g. a stale socket after the
+     * Mac slept) even though the connection looks up — used by /health and the
+     * watchdog to detect a silently-offline worker.
+     */
+    lastPollAgeMs() {
+        return Date.now() - this.lastPollOkAt;
+    }
     username() {
         return this.me?.username;
     }
     onIncoming(handler) {
         this.handlers.push(handler);
     }
-    async call(method, params) {
-        const res = await fetch(`${this.base}/${method}`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify(params ?? {}),
-        });
-        const data = (await res.json());
-        if (!data.ok) {
-            throw new Error(`Telegram ${method} failed: ${data.description ?? `HTTP ${res.status}`}`);
+    /**
+     * Call a Bot API method with a hard client-side timeout. Without this, a
+     * socket left half-open by a sleep/wake could make `fetch` hang forever and
+     * silently take the bot offline. On timeout the call rejects (AbortError) and
+     * the caller retries.
+     */
+    async call(method, params, timeoutMs = 20_000) {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), timeoutMs);
+        try {
+            const res = await fetch(`${this.base}/${method}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(params ?? {}),
+                signal: ac.signal,
+            });
+            const data = (await res.json());
+            if (!data.ok) {
+                throw new Error(`Telegram ${method} failed: ${data.description ?? `HTTP ${res.status}`}`);
+            }
+            return data.result;
+        }
+        finally {
+            clearTimeout(timer);
         }
-        return data.result;
     }
     async connect() {
         await mkdir(this.mediaDir, { recursive: true });
@@ -100,13 +125,19 @@ export class TelegramClient {
         sweep.unref?.();
     }
     async pollLoop() {
+        // Abort getUpdates a bit after the server-side long-poll window so a dead
+        // socket (e.g. after sleep/wake) can't wedge the loop indefinitely.
+        const pollTimeoutMs = (GETUPDATES_LONG_POLL_SEC + 15) * 1000;
+        let backoffMs = 1000;
         while (!this.stopping) {
             try {
                 const updates = await this.call("getUpdates", {
                     offset: this.offset,
                     timeout: GETUPDATES_LONG_POLL_SEC,
                     allowed_updates: ["message"],
-                });
+                }, pollTimeoutMs);
+                this.lastPollOkAt = Date.now();
+                backoffMs = 1000;
                 for (const update of updates) {
                     this.offset = update.update_id + 1;
                     const msg = await this.toIncoming(update.message);
@@ -118,8 +149,9 @@ export class TelegramClient {
             catch (err) {
                 if (this.stopping)
                     break;
-                this.logger.warn(`getUpdates error (retrying): ${String(err)}`);
-                await new Promise((r) => setTimeout(r, 3000));
+                this.logger.warn(`getUpdates error (retry in ${backoffMs}ms): ${String(err)}`);
+                await new Promise((r) => setTimeout(r, backoffMs));
+                backoffMs = Math.min(backoffMs * 2, 30_000);
             }
         }
     }
@@ -145,10 +177,18 @@ export class TelegramClient {
             throw new Error(`Attachment too large (${file.file_size} bytes, max ${this.maxAttachmentBytes})`);
         }
         const url = `https://api.telegram.org/file/bot${this.opts.botToken}/${file.file_path}`;
-        const res = await fetch(url);
-        if (!res.ok)
-            throw new Error(`Download failed: HTTP ${res.status}`);
-        const buf = Buffer.from(await res.arrayBuffer());
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 60_000);
+        let buf;
+        try {
+            const res = await fetch(url, { signal: ac.signal });
+            if (!res.ok)
+                throw new Error(`Download failed: HTTP ${res.status}`);
+            buf = Buffer.from(await res.arrayBuffer());
+        }
+        finally {
+            clearTimeout(timer);
+        }
         if (buf.length > this.maxAttachmentBytes) {
             throw new Error(`Attachment too large (${buf.length} bytes, max ${this.maxAttachmentBytes})`);
         }