cursor-telegram-mcp 0.5.0

package/dist/worker.js

@@ -0,0 +1,667 @@
+/**
+ * Background Telegram worker (long-running, local, single-user).
+ *
+ * Owns the single Telegram bot connection (long polling) and an in-memory
+ * pending-question store, and exposes a tiny HTTP API on localhost that the
+ * thin MCP server calls. Running it in its own process means the bot stays
+ * connected across Cursor / MCP reloads, and you can restart it from a terminal
+ * (`npm run worker`).
+ *
+ * Alive only while your laptop is awake (and the worker is running).
+ *
+ * If CURSOR_API_KEY is set, the worker also runs in "command mode": a message
+ * you text the bot (that isn't answering an open question) can be /ask (read-only
+ * Q&A), /plan (plan-then-approve), or plain text (same as /plan) -> you reply
+ * YES to execute a plan or NO to cancel. Everything runs locally.
+ *
+ * Run with `npm run worker`. Requires TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID.
+ *
+ * API (JSON, localhost only):
+ *   GET  /health                       -> { ok, connected, target, pending, commandMode, queue }
+ *   POST /notify   { summary, project } -> { ok } | 429 { error, waitMs } | 503
+ *   POST /ask      { question, project }-> { id } | 429 | 503
+ *   POST /mirror   { question, project } -> { id, mirrored } | 429 | 503
+ *   GET  /response/:id                 -> { id, status, answer?, attachments?, elapsedMin } | 404
+ *                                      optional ?waitMs=N long-polls until answered or N ms
+ */
+import { createServer } from "node:http";
+import { notifyAnswered, waitForAnswer } from "./answerWaiters.js";
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getConfig } from "./config.js";
+import { createStore } from "./store.js";
+import { createCommandRunner } from "./agentRunner.js";
+import { toPlainTelegram } from "./formatTelegram.js";
+import { splitInboundMessage } from "./parseInbound.js";
+import { splitMessage } from "./splitMessage.js";
+import { createTaskQueue } from "./taskQueue.js";
+import { TelegramClient, createStderrLogger, } from "./telegram.js";
+/** Stale command sessions (awaiting approval too long) are swept after this. */
+const COMMAND_TTL_MS = 60 * 60_000;
+/** How often to check whether the worker's own source changed on disk. */
+const UPDATE_CHECK_MS = 15_000;
+/** Directory holding this worker's source (for self-update detection). */
+const SRC_DIR = dirname(fileURLToPath(import.meta.url));
+/**
+ * Newest mtime among the worker's TypeScript source files. Used to notice when
+ * a command-mode task has edited the worker's own code, so it can relaunch on
+ * the latest version (under a KeepAlive supervisor like launchd) while idle.
+ */
+function sourceFingerprint() {
+    let latest = 0;
+    try {
+        for (const f of readdirSync(SRC_DIR)) {
+            if (!f.endsWith(".ts"))
+                continue;
+            const m = statSync(join(SRC_DIR, f)).mtimeMs;
+            if (m > latest)
+                latest = m;
+        }
+    }
+    catch {
+        // If the directory can't be read, just skip self-update.
+    }
+    return latest;
+}
+/** Heartbeat interval while planning or executing a command session. */
+const HEARTBEAT_MS = 60_000;
+/** Last-resort clamp for a single unbreakable line. */
+const HARD_CLAMP = 4096;
+function log(msg) {
+    process.stderr.write(`[worker] ${msg}\n`);
+}
+/** Sanitize a project label to a short, single-line token. */
+function cleanProject(raw) {
+    const s = String(raw ?? "").trim().replace(/\s+/g, " ");
+    return s === "" ? "default" : s.slice(0, 48);
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+async function readJson(req) {
+    return new Promise((resolve, reject) => {
+        let raw = "";
+        req.on("data", (chunk) => {
+            raw += chunk;
+            if (raw.length > 1_000_000)
+                reject(new Error("Body too large"));
+        });
+        req.on("end", () => {
+            if (raw.trim() === "")
+                return resolve({});
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                reject(new Error("Invalid JSON body"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+function isReplyToQuestion(msg, store) {
+    if (!msg.quotedMessageId || store.pendingCount() === 0)
+        return false;
+    const pendings = store.listPending();
+    return pendings.some((q) => q.sentMessageId && q.sentMessageId === msg.quotedMessageId);
+}
+function isCommandLike(segments) {
+    return segments.some((s) => s.kind === "ask" ||
+        s.kind === "plan" ||
+        s.kind === "ask_empty" ||
+        s.kind === "plan_empty" ||
+        s.kind === "status" ||
+        s.kind === "approve" ||
+        s.kind === "reject" ||
+        s.kind === "approval_footer");
+}
+async function main() {
+    // Make sure the Cursor CLI (`cursor-agent`, used by command mode) is findable
+    // even when launched by a GUI/launchd context with a minimal PATH.
+    const localBin = join(homedir(), ".local", "bin");
+    const pathParts = (process.env.PATH ?? "").split(delimiter);
+    if (!pathParts.includes(localBin)) {
+        process.env.PATH = `${localBin}${delimiter}${process.env.PATH ?? ""}`;
+    }
+    const config = getConfig();
+    if (config.chatId === "") {
+        log("TELEGRAM_CHAT_ID is not set. Run `npm run login` to find it, then set it in .env.");
+    }
+    const store = createStore();
+    const taskQueue = createTaskQueue();
+    const runner = createCommandRunner({
+        apiKey: config.cursorApiKey,
+        cwd: config.agentCwd,
+        model: config.agentModel,
+        settingSources: config.agentLoadSettings ? ["all"] : [],
+    });
+    const commandMode = runner.enabled;
+    log(commandMode
+        ? `Command mode ON (model ${config.agentModel}, cwd ${config.agentCwd}). /ask, /plan, or plain text to plan.`
+        : "Command mode OFF (set CURSOR_API_KEY to text tasks to the bot).");
+    const client = new TelegramClient({
+        botToken: config.botToken,
+        logger: createStderrLogger("warn"),
+        onReady: () => log(`Telegram connected as @${client.username() ?? "?"}. Target chat: ${config.chatId}`),
+    });
+    /** Recent mirror dedupe: question hash -> timestamp. */
+    const recentMirrors = new Map();
+    const MIRROR_DEDUPE_MS = 5 * 60_000;
+    /** Photo-only message waiting for a caption. */
+    let pendingPhotoAttachments;
+    let lastSendAt = 0;
+    async function waitSendGap() {
+        const elapsed = Date.now() - lastSendAt;
+        if (elapsed < config.minSendGapMs) {
+            await new Promise((r) => setTimeout(r, config.minSendGapMs - elapsed));
+        }
+    }
+    async function send(text) {
+        const plain = toPlainTelegram(text);
+        const chunks = splitMessage(plain);
+        let firstId;
+        try {
+            for (let i = 0; i < chunks.length; i++) {
+                let chunk = chunks[i];
+                if (chunk.length > HARD_CLAMP) {
+                    chunk = chunk.slice(0, HARD_CLAMP - 20) + "\n\n[...truncated]";
+                }
+                if (chunks.length > 1) {
+                    chunk = `(${i + 1}/${chunks.length})\n${chunk}`;
+                }
+                if (i > 0)
+                    await waitSendGap();
+                const id = await client.sendText(config.chatId, chunk);
+                lastSendAt = Date.now();
+                if (i === 0)
+                    firstId = id;
+            }
+            return firstId;
+        }
+        catch (err) {
+            log(`Failed to send Telegram message: ${String(err)}`);
+            return undefined;
+        }
+    }
+    function isWorkerBusy() {
+        return runner.latestActiveSession() != null;
+    }
+    async function runApproved(id) {
+        log(`Approved ${id}; executing...`);
+        await send(`Working on ${id}...`);
+        let heartbeat;
+        const clearHeartbeat = () => {
+            if (heartbeat) {
+                clearInterval(heartbeat);
+                heartbeat = undefined;
+            }
+        };
+        try {
+            const session = await runner.approve(id, (s) => {
+                heartbeat = setInterval(() => {
+                    void send(`Still working on ${s.id}...`);
+                }, HEARTBEAT_MS);
+                heartbeat.unref?.();
+            });
+            log(`Execution ${id} -> ${session.status}`);
+            if (session.status === "done") {
+                await send(`Done (${id})\n\n${session.result ?? ""}`);
+            }
+            else if (session.status === "error") {
+                await send(`Command ${id} failed:\n${session.error ?? "unknown error"}`);
+            }
+        }
+        finally {
+            clearHeartbeat();
+        }
+    }
+    function formatStatus() {
+        const lines = [];
+        lines.push(`Command mode: ${commandMode ? "ON" : "OFF"}`);
+        const pending = store.listPending();
+        if (pending.length === 0) {
+            lines.push("Pending questions: none");
+        }
+        else {
+            lines.push(`Pending questions: ${pending.length} (${pending.map((q) => q.id).join(", ")})`);
+        }
+        const awaiting = runner.listAwaitingApproval();
+        if (awaiting.length === 0) {
+            lines.push("Awaiting approval: none");
+        }
+        else {
+            lines.push(`Awaiting approval: ${awaiting.map((s) => s.id).join(", ")}`);
+        }
+        const active = runner.latestActiveSession();
+        if (active) {
+            lines.push(`Active: ${active.status} ${active.id}`);
+        }
+        const activeAsks = runner.listActiveAsks();
+        if (activeAsks.length > 0) {
+            lines.push(`Active asks: ${activeAsks.map((s) => s.id).join(", ")}`);
+        }
+        lines.push(`Queued tasks: ${taskQueue.preview()}`);
+        if (commandMode) {
+            lines.push("Commands: /ask question, /plan task, plain text plans too");
+        }
+        return lines.join("\n");
+    }
+    async function runPlanTask(task, attachments) {
+        log(`New task received; planning...`);
+        await send(`Planning your request...`);
+        let heartbeat;
+        const clearHeartbeat = () => {
+            if (heartbeat) {
+                clearInterval(heartbeat);
+                heartbeat = undefined;
+            }
+        };
+        let session;
+        try {
+            session = await runner.plan(task, (s) => {
+                heartbeat = setInterval(() => {
+                    void send(`Still planning ${s.id}...`);
+                }, HEARTBEAT_MS);
+                heartbeat.unref?.();
+            }, attachments);
+        }
+        catch (err) {
+            clearHeartbeat();
+            const errText = String(err);
+            log(`Plan error: ${errText}`);
+            await send(`Planning failed:\n${errText}`);
+            return;
+        }
+        clearHeartbeat();
+        log(`Plan ${session.id} -> ${session.status}`);
+        if (session.status === "awaiting_approval") {
+            await send(`Plan (${session.id})\n\n${session.plan ?? ""}\n\nReply YES to run it or NO to cancel.`);
+        }
+        else {
+            await send(`Could not plan that (${session.id}):\n${session.error ?? "unknown error"}`);
+        }
+    }
+    async function runAskQuestion(question, attachments) {
+        log(`Ask received; answering...`);
+        await send(`Answering...`);
+        let heartbeat;
+        const clearHeartbeat = () => {
+            if (heartbeat) {
+                clearInterval(heartbeat);
+                heartbeat = undefined;
+            }
+        };
+        let session;
+        try {
+            session = await runner.ask(question, (s) => {
+                heartbeat = setInterval(() => {
+                    void send(`Still answering ${s.id}...`);
+                }, HEARTBEAT_MS);
+                heartbeat.unref?.();
+            }, attachments);
+        }
+        catch (err) {
+            clearHeartbeat();
+            const errText = String(err);
+            log(`Ask error: ${errText}`);
+            await send(`Could not answer:\n${errText}`);
+            return;
+        }
+        clearHeartbeat();
+        log(`Ask ${session.id} -> ${session.status}`);
+        if (session.status === "done") {
+            await send(`Ask (${session.id})\n\n${session.answer ?? ""}`);
+        }
+        else {
+            await send(`Could not answer (${session.id}):\n${session.error ?? "unknown error"}`);
+        }
+    }
+    async function processQueueItem(item) {
+        if (item.kind === "ask") {
+            await runAskQuestion(item.text, item.attachments);
+        }
+        else {
+            await runPlanTask(item.text, item.attachments);
+        }
+    }
+    let draining = false;
+    async function drainQueue() {
+        if (draining)
+            return;
+        draining = true;
+        try {
+            while (!isWorkerBusy()) {
+                const next = taskQueue.dequeue();
+                if (!next)
+                    break;
+                log(`Dequeuing ${next.kind}: ${next.text.slice(0, 60)}...`);
+                await send(`Starting queued ${next.kind}...`);
+                await processQueueItem(next);
+            }
+        }
+        finally {
+            draining = false;
+        }
+    }
+    async function enqueueOrRun(item, run) {
+        if (isWorkerBusy()) {
+            const pos = taskQueue.enqueue(item);
+            await send(`Queued (#${pos}): ${item.kind} — will run when current work finishes.`);
+            return;
+        }
+        await run();
+    }
+    async function handleSegment(seg, attachments) {
+        switch (seg.kind) {
+            case "status":
+                await send(formatStatus());
+                return;
+            case "approve": {
+                if (!commandMode)
+                    return;
+                const awaiting = runner.latestAwaitingApproval();
+                if (!awaiting) {
+                    await send("No plan awaiting approval.");
+                    return;
+                }
+                if (isWorkerBusy()) {
+                    await send(`BUSY: ${runner.latestActiveSession()?.status} ${runner.latestActiveSession()?.id}. Wait for it to finish.`);
+                    return;
+                }
+                await send(`Approved ${awaiting.id}.`);
+                await runApproved(awaiting.id);
+                await drainQueue();
+                return;
+            }
+            case "reject": {
+                if (!commandMode)
+                    return;
+                const awaiting = runner.latestAwaitingApproval();
+                if (!awaiting) {
+                    await send("No plan awaiting approval.");
+                    return;
+                }
+                runner.reject(awaiting.id);
+                await send(`Cancelled ${awaiting.id}.`);
+                return;
+            }
+            case "approval_footer": {
+                if (!commandMode)
+                    return;
+                const awaiting = runner.latestAwaitingApproval();
+                if (!awaiting) {
+                    await send("No plan awaiting approval.");
+                    return;
+                }
+                await send(`Plan ${awaiting.id} is awaiting approval. Reply YES to run it or NO to cancel.`);
+                return;
+            }
+            case "ask_empty":
+                await send("Usage: /ask your question here");
+                return;
+            case "plan_empty":
+                await send("Usage: /plan your task here");
+                return;
+            case "ask":
+                if (!commandMode)
+                    return;
+                await enqueueOrRun({ kind: "ask", text: seg.text, attachments: attachments.length > 0 ? attachments : undefined }, async () => {
+                    await runAskQuestion(seg.text, attachments.length > 0 ? attachments : undefined);
+                    await drainQueue();
+                });
+                return;
+            case "plan":
+                if (!commandMode)
+                    return;
+                await enqueueOrRun({ kind: "plan", text: seg.text, attachments: attachments.length > 0 ? attachments : undefined }, async () => {
+                    await runPlanTask(seg.text, attachments.length > 0 ? attachments : undefined);
+                    await drainQueue();
+                });
+                return;
+            case "plain":
+                if (!commandMode)
+                    return;
+                await enqueueOrRun({ kind: "plan", text: seg.text, attachments: attachments.length > 0 ? attachments : undefined }, async () => {
+                    await runPlanTask(seg.text, attachments.length > 0 ? attachments : undefined);
+                    await drainQueue();
+                });
+                return;
+        }
+    }
+    let incomingChain = Promise.resolve();
+    async function handleIncoming(msg) {
+        if (msg.photoOnly && msg.attachments.length > 0) {
+            pendingPhotoAttachments = msg.attachments;
+            await send("Photo received. Send a caption or /ask / /plan command with your message.");
+            return;
+        }
+        let attachments = msg.attachments;
+        if (pendingPhotoAttachments && pendingPhotoAttachments.length > 0) {
+            attachments = [...pendingPhotoAttachments, ...attachments];
+            pendingPhotoAttachments = undefined;
+        }
+        const text = msg.text.trim();
+        if (text === "" && attachments.length === 0)
+            return;
+        if (isReplyToQuestion(msg, store)) {
+            const matched = store.matchAndAnswer(msg);
+            if (matched) {
+                log(`Recorded answer for ${matched.id} [${matched.projectLabel}].`);
+                notifyAnswered(matched.id);
+                await send(`Answer recorded for ${matched.id}.`);
+            }
+            return;
+        }
+        if (store.pendingCount() > 0 && !isCommandLike(splitInboundMessage(text))) {
+            const matched = store.matchAndAnswer(msg);
+            if (matched) {
+                log(`Recorded answer for ${matched.id} [${matched.projectLabel}].`);
+                notifyAnswered(matched.id);
+                await send(`Answer recorded for ${matched.id}.`);
+                return;
+            }
+        }
+        const segments = splitInboundMessage(text);
+        if (segments.length === 0 && attachments.length === 0)
+            return;
+        if (segments.length === 0 && attachments.length > 0) {
+            await send("Send a caption or command with your photo.");
+            pendingPhotoAttachments = attachments;
+            return;
+        }
+        for (const seg of segments) {
+            await handleSegment(seg, attachments);
+        }
+    }
+    client.onIncoming((msg) => {
+        if (!TelegramClient.sameChat(msg.fromChatId, config.chatId))
+            return;
+        incomingChain = incomingChain
+            .then(() => handleIncoming(msg))
+            .catch((err) => log(`handleIncoming error: ${String(err)}`));
+    });
+    function rateGuard() {
+        const elapsed = Date.now() - lastSendAt;
+        return elapsed < config.minSendGapMs
+            ? { ok: false, waitMs: config.minSendGapMs - elapsed }
+            : { ok: true, waitMs: 0 };
+    }
+    function dedupeMirrorKey(project, question) {
+        return `${project}::${question.slice(0, 200)}`;
+    }
+    async function mirrorQuestion(project, question) {
+        const key = dedupeMirrorKey(project, question);
+        const now = Date.now();
+        const last = recentMirrors.get(key);
+        if (last != null && now - last < MIRROR_DEDUPE_MS) {
+            const existing = store.listPending().find((q) => q.question === question && q.projectLabel === project);
+            return { id: existing?.id ?? "deduped", mirrored: false };
+        }
+        recentMirrors.set(key, now);
+        const record = store.addQuestion(project, question);
+        const text = `[${project}] ${record.id}\n${question}\n\nReply to this message to answer.`;
+        const sentId = await send(text);
+        if (sentId)
+            store.setSentMessageId(record.id, sentId);
+        return { id: record.id, mirrored: true };
+    }
+    const server = createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? "/", `http://${config.workerHost}`);
+            const path = url.pathname;
+            const method = req.method ?? "GET";
+            if (method === "GET" && path === "/health") {
+                return sendJson(res, 200, {
+                    ok: true,
+                    connected: client.isOpen(),
+                    target: config.chatId,
+                    pending: store.pendingCount(),
+                    commandMode,
+                    queue: taskQueue.length(),
+                });
+            }
+            if (method === "POST" && path === "/notify") {
+                if (!client.isOpen())
+                    return sendJson(res, 503, { error: "Telegram not connected" });
+                if (config.chatId === "")
+                    return sendJson(res, 503, { error: "TELEGRAM_CHAT_ID not set" });
+                const guard = rateGuard();
+                if (!guard.ok)
+                    return sendJson(res, 429, { error: "rate_limited", waitMs: guard.waitMs });
+                const body = await readJson(req);
+                const summary = String(body.summary ?? "").trim();
+                const project = cleanProject(body.project);
+                if (!summary)
+                    return sendJson(res, 400, { error: "summary is required" });
+                await send(`[${project}] Task complete\n\n${summary}`);
+                return sendJson(res, 200, { ok: true });
+            }
+            if (method === "POST" && (path === "/ask" || path === "/mirror")) {
+                if (!client.isOpen())
+                    return sendJson(res, 503, { error: "Telegram not connected" });
+                if (config.chatId === "")
+                    return sendJson(res, 503, { error: "TELEGRAM_CHAT_ID not set" });
+                const guard = rateGuard();
+                if (!guard.ok)
+                    return sendJson(res, 429, { error: "rate_limited", waitMs: guard.waitMs });
+                const body = await readJson(req);
+                const question = String(body.question ?? "").trim();
+                const project = cleanProject(body.project);
+                if (!question)
+                    return sendJson(res, 400, { error: "question is required" });
+                const { id, mirrored } = await mirrorQuestion(project, question);
+                return sendJson(res, 200, { id, mirrored: path === "/mirror" ? mirrored : true });
+            }
+            if (method === "GET" && path.startsWith("/response/")) {
+                const id = decodeURIComponent(path.slice("/response/".length));
+                const waitMs = Math.max(0, Number(url.searchParams.get("waitMs") ?? 0));
+                function responsePayload(record) {
+                    const elapsedMin = Math.floor((Date.now() - record.createdAt) / 60000);
+                    if (record.status === "answered") {
+                        const attachments = record.answerAttachments?.map((a) => ({
+                            mimeType: a.mimeType,
+                            localPath: a.localPath,
+                            sizeBytes: a.sizeBytes,
+                        })) ?? [];
+                        return {
+                            status: 200,
+                            body: {
+                                id: record.id,
+                                status: "answered",
+                                answer: record.answer ?? "",
+                                attachments,
+                                elapsedMin,
+                            },
+                        };
+                    }
+                    if (elapsedMin >= config.responseTimeoutMin) {
+                        return { status: 200, body: { id: record.id, status: "timed_out", elapsedMin } };
+                    }
+                    return { status: 200, body: { id: record.id, status: "pending", elapsedMin } };
+                }
+                let record = store.get(id);
+                if (!record)
+                    return sendJson(res, 404, { error: "unknown questionId", id });
+                let payload = responsePayload(record);
+                if (payload.body.status === "pending" && waitMs > 0) {
+                    const { promise, cancel } = waitForAnswer(id, waitMs);
+                    req.on("close", cancel);
+                    await promise;
+                    record = store.get(id);
+                    if (!record)
+                        return sendJson(res, 404, { error: "unknown questionId", id });
+                    payload = responsePayload(record);
+                }
+                return sendJson(res, payload.status, payload.body);
+            }
+            if (method === "POST" &&
+                path === "/_test/answer" &&
+                process.env.TG_ALLOW_TEST_ROUTES === "1") {
+                const body = await readJson(req);
+                const testId = String(body.id ?? "");
+                const testAnswer = String(body.answer ?? "test");
+                const testRecord = store.get(testId);
+                if (!testRecord || testRecord.status !== "pending") {
+                    return sendJson(res, 404, { error: "not pending", id: testId });
+                }
+                testRecord.status = "answered";
+                testRecord.answer = testAnswer;
+                testRecord.answeredAt = Date.now();
+                notifyAnswered(testId);
+                return sendJson(res, 200, { ok: true });
+            }
+            return sendJson(res, 404, { error: "not found" });
+        }
+        catch (err) {
+            return sendJson(res, 500, { error: String(err) });
+        }
+    });
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            log(`worker already running (port ${config.workerPort} in use on ${config.workerHost})`);
+            process.exit(1);
+        }
+        log(`HTTP server error: ${String(err)}`);
+        process.exit(1);
+    });
+    server.listen(config.workerPort, config.workerHost, () => {
+        log(`HTTP API listening on http://${config.workerHost}:${config.workerPort}`);
+    });
+    const sweep = setInterval(() => runner.sweepStale(COMMAND_TTL_MS), 10 * 60_000);
+    sweep.unref?.();
+    await client.connect().catch((err) => log(`Telegram connection error: ${String(err)}`));
+    const shutdown = () => {
+        log("Shutting down...");
+        server.close();
+        client.close().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    // Self-update: if a task edits the worker's own source, relaunch on the new
+    // code once nothing is in flight. Only effective under a KeepAlive supervisor
+    // (launchd `npm run worker:install`), which restarts the process after exit.
+    const startFingerprint = sourceFingerprint();
+    function isIdleForRestart() {
+        return (!isWorkerBusy() &&
+            !draining &&
+            taskQueue.length() === 0 &&
+            runner.listAwaitingApproval().length === 0 &&
+            runner.listActiveAsks().length === 0 &&
+            store.pendingCount() === 0);
+    }
+    const updateCheck = setInterval(() => {
+        if (sourceFingerprint() > startFingerprint && isIdleForRestart()) {
+            log("Source changed and worker idle; restarting to load the latest version...");
+            clearInterval(updateCheck);
+            shutdown();
+        }
+    }, UPDATE_CHECK_MS);
+    updateCheck.unref?.();
+}
+main().catch((err) => {
+    log(`Fatal: ${err?.stack ?? err}`);
+    process.exit(1);
+});

package/mcp.client.template.json

@@ -0,0 +1,12 @@
+{
+  "_comment": "Add this 'telegram' block to a project's .cursor/mcp.json (or Cursor Settings -> MCP). Run `npx cursor-telegram-mcp setup` once first to configure your bot. The MCP auto-starts a shared local worker. Optionally set TG_PROJECT to label this project's messages.",
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "cursor-telegram-mcp"],
+      "env": {
+        "TG_PROJECT": "my-project-label"
+      }
+    }
+  }
+}