cursor-telegram-mcp 0.5.0

package/dist/splitMessage.js

@@ -0,0 +1,61 @@
+/**
+ * Split long outbound text into Telegram-sized chunks (~4000 chars).
+ * Prefers paragraph breaks, then single newlines, then hard split.
+ */
+const DEFAULT_MAX = 4000;
+function hardSplit(text, max) {
+    const chunks = [];
+    for (let i = 0; i < text.length; i += max) {
+        chunks.push(text.slice(i, i + max));
+    }
+    return chunks;
+}
+function splitBlock(block, max) {
+    if (block.length <= max)
+        return [block];
+    const paragraphs = block.split(/\n\n+/);
+    if (paragraphs.length > 1) {
+        const out = [];
+        let current = "";
+        for (const para of paragraphs) {
+            const candidate = current === "" ? para : `${current}\n\n${para}`;
+            if (candidate.length <= max) {
+                current = candidate;
+            }
+            else {
+                if (current !== "")
+                    out.push(...splitBlock(current, max));
+                current = para;
+            }
+        }
+        if (current !== "")
+            out.push(...splitBlock(current, max));
+        return out;
+    }
+    const lines = block.split("\n");
+    if (lines.length > 1) {
+        const out = [];
+        let current = "";
+        for (const line of lines) {
+            const candidate = current === "" ? line : `${current}\n${line}`;
+            if (candidate.length <= max) {
+                current = candidate;
+            }
+            else {
+                if (current !== "")
+                    out.push(...splitBlock(current, max));
+                current = line;
+            }
+        }
+        if (current !== "")
+            out.push(...splitBlock(current, max));
+        return out;
+    }
+    return hardSplit(block, max);
+}
+/** Split text into chunks no longer than max (default 4000). */
+export function splitMessage(text, max = DEFAULT_MAX) {
+    if (text.length <= max)
+        return [text];
+    return splitBlock(text, max);
+}

package/dist/store.js

@@ -0,0 +1,81 @@
+/** Keep answered questions this long after they are answered, then prune. */
+const ANSWERED_TTL_MS = 60 * 60_000;
+export class QuestionStore {
+    nextId = 1;
+    questions = new Map();
+    /** Create a new pending question. */
+    addQuestion(projectLabel, question) {
+        this.prune();
+        const record = {
+            id: `Q-${this.nextId++}`,
+            projectLabel,
+            question,
+            status: "pending",
+            createdAt: Date.now(),
+        };
+        this.questions.set(record.id, record);
+        return record;
+    }
+    /** Attach the outgoing Telegram message id to a question. */
+    setSentMessageId(id, messageId) {
+        const record = this.questions.get(id);
+        if (record)
+            record.sentMessageId = messageId;
+    }
+    /** Look up a single question by id. */
+    get(id) {
+        return this.questions.get(id);
+    }
+    /** Number of still-unanswered questions. */
+    pendingCount() {
+        let n = 0;
+        for (const q of this.questions.values())
+            if (q.status === "pending")
+                n++;
+        return n;
+    }
+    /** Pending questions, oldest first. */
+    listPending() {
+        return [...this.questions.values()]
+            .filter((q) => q.status === "pending")
+            .sort((a, b) => a.createdAt - b.createdAt);
+    }
+    /**
+     * 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.
+     */
+    matchAndAnswer(incoming) {
+        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) {
+            target = pendings.find((q) => q.sentMessageId && q.sentMessageId === incoming.quotedMessageId);
+        }
+        if (!target)
+            target = pendings[0];
+        target.status = "answered";
+        target.answer = incoming.text;
+        if (incoming.attachments.length > 0) {
+            target.answerAttachments = incoming.attachments;
+        }
+        target.answeredAt = incoming.timestamp || Date.now();
+        return target;
+    }
+    /** Drop answered questions older than the TTL. */
+    prune() {
+        const cutoff = Date.now() - ANSWERED_TTL_MS;
+        for (const [id, q] of this.questions) {
+            if (q.status === "answered" && (q.answeredAt ?? q.createdAt) < cutoff) {
+                this.questions.delete(id);
+            }
+        }
+    }
+}
+/** Build a fresh in-memory store. */
+export function createStore() {
+    return new QuestionStore();
+}

package/dist/taskQueue.js

@@ -0,0 +1,33 @@
+/**
+ * In-memory FIFO queue for /ask, /plan, and plain-text tasks while the worker
+ * is busy planning, executing, or answering.
+ */
+export class TaskQueue {
+    items = [];
+    enqueue(item) {
+        this.items.push(item);
+        return this.items.length;
+    }
+    dequeue() {
+        return this.items.shift();
+    }
+    length() {
+        return this.items.length;
+    }
+    /** Short summary for STATUS output. */
+    preview(max = 3) {
+        if (this.items.length === 0)
+            return "none";
+        const shown = this.items.slice(0, max).map((item, i) => {
+            const label = item.kind === "ask" ? "ask" : "plan";
+            const snippet = item.text.slice(0, 40).replace(/\s+/g, " ");
+            const suffix = item.text.length > 40 ? "..." : "";
+            return `${i + 1}:${label} "${snippet}${suffix}"`;
+        });
+        const extra = this.items.length > max ? ` (+${this.items.length - max} more)` : "";
+        return `${this.items.length} (${shown.join("; ")}${extra})`;
+    }
+}
+export function createTaskQueue() {
+    return new TaskQueue();
+}

package/dist/telegram.js

@@ -0,0 +1,241 @@
+/**
+ * Telegram Bot API transport (long polling).
+ *
+ * The Bot API is plain HTTPS - no QR, eSIM, or on-disk session state. Inbound
+ * messages arrive via `getUpdates` long polling, so no public URL/webhook is
+ * needed: this runs entirely on your machine.
+ */
+import { createWriteStream } from "node:fs";
+import { mkdir, readdir, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { finished } from "node:stream/promises";
+export function createStderrLogger(level = "info") {
+    const order = { error: 0, warn: 1, info: 2 };
+    const threshold = order[level];
+    const write = (lvl, msg) => {
+        if (order[lvl] <= threshold)
+            process.stderr.write(`[telegram:${lvl}] ${msg}\n`);
+    };
+    return {
+        info: (m) => write("info", m),
+        warn: (m) => write("warn", m),
+        error: (m) => write("error", m),
+    };
+}
+function silentLogger() {
+    return { info: () => { }, warn: () => { }, error: () => { } };
+}
+const ALLOWED_MIME = new Set(["image/jpeg", "image/png", "image/webp"]);
+const DEFAULT_MEDIA_DIR = ".telegram-media";
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MEDIA_TTL_MS = 24 * 60 * 60_000;
+/**
+ * TIMEOUTS (three different values — do not conflate):
+ * - GETUPDATES_LONG_POLL_SEC (30): Bot API long-poll for inbound messages only
+ *   (worker receive path). NOT how often the agent should poll.
+ * - waitMs / ask_human_and_wait: agent-side long-poll on GET /response/:id;
+ *   wakes immediately when the human replies (see MCP tools in index.ts).
+ * - TG_RESPONSE_TIMEOUT_MIN (default 30 minutes): how long a question stays
+ *   open before status timed_out. Unrelated to getUpdates.
+ */
+export const GETUPDATES_LONG_POLL_SEC = 30;
+function extForMime(mime) {
+    if (mime === "image/png")
+        return ".png";
+    if (mime === "image/webp")
+        return ".webp";
+    return ".jpg";
+}
+/** Thin wrapper around the Telegram Bot API: validate, long-poll, sendText. */
+export class TelegramClient {
+    opts;
+    logger;
+    base;
+    handlers = [];
+    mediaDir;
+    maxAttachmentBytes;
+    mediaTtlMs;
+    open = false;
+    stopping = false;
+    offset = 0;
+    me = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.logger = opts.logger ?? silentLogger();
+        this.base = `https://api.telegram.org/bot${opts.botToken}`;
+        this.mediaDir = opts.mediaDir ?? join(process.cwd(), DEFAULT_MEDIA_DIR);
+        this.maxAttachmentBytes = opts.maxAttachmentBytes ?? DEFAULT_MAX_BYTES;
+        this.mediaTtlMs = opts.mediaTtlMs ?? DEFAULT_MEDIA_TTL_MS;
+    }
+    isOpen() {
+        return this.open;
+    }
+    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}`}`);
+        }
+        return data.result;
+    }
+    async connect() {
+        await mkdir(this.mediaDir, { recursive: true });
+        this.me = await this.call("getMe");
+        await this.call("deleteWebhook", {}).catch(() => undefined);
+        this.open = true;
+        this.opts.onReady?.();
+        void this.pollLoop();
+        void this.cleanupOldMedia();
+        const sweep = setInterval(() => void this.cleanupOldMedia(), 60 * 60_000);
+        sweep.unref?.();
+    }
+    async pollLoop() {
+        while (!this.stopping) {
+            try {
+                const updates = await this.call("getUpdates", {
+                    offset: this.offset,
+                    timeout: GETUPDATES_LONG_POLL_SEC,
+                    allowed_updates: ["message"],
+                });
+                for (const update of updates) {
+                    this.offset = update.update_id + 1;
+                    const msg = await this.toIncoming(update.message);
+                    if (msg)
+                        for (const h of this.handlers)
+                            h(msg);
+                }
+            }
+            catch (err) {
+                if (this.stopping)
+                    break;
+                this.logger.warn(`getUpdates error (retrying): ${String(err)}`);
+                await new Promise((r) => setTimeout(r, 3000));
+            }
+        }
+    }
+    pickImage(message) {
+        if (message.photo && message.photo.length > 0) {
+            const largest = message.photo[message.photo.length - 1];
+            return { fileId: largest.file_id, mimeType: "image/jpeg", size: largest.file_size };
+        }
+        if (message.document?.mime_type && ALLOWED_MIME.has(message.document.mime_type)) {
+            return {
+                fileId: message.document.file_id,
+                mimeType: message.document.mime_type,
+                size: message.document.file_size,
+            };
+        }
+        return null;
+    }
+    async downloadFile(fileId, mimeType) {
+        const file = await this.call("getFile", { file_id: fileId });
+        if (!file.file_path)
+            throw new Error("Telegram getFile returned no file_path");
+        if (file.file_size != null && file.file_size > this.maxAttachmentBytes) {
+            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());
+        if (buf.length > this.maxAttachmentBytes) {
+            throw new Error(`Attachment too large (${buf.length} bytes, max ${this.maxAttachmentBytes})`);
+        }
+        const name = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}${extForMime(mimeType)}`;
+        const localPath = join(this.mediaDir, name);
+        const ws = createWriteStream(localPath);
+        ws.write(buf);
+        ws.end();
+        await finished(ws);
+        return { fileId, mimeType, localPath, sizeBytes: buf.length };
+    }
+    async toIncoming(message) {
+        if (!message)
+            return null;
+        const text = (message.text ?? message.caption ?? "").trim();
+        const image = this.pickImage(message);
+        if (!text && !image)
+            return null;
+        let attachments = [];
+        if (image) {
+            if (image.size != null && image.size > this.maxAttachmentBytes) {
+                this.logger.warn(`Skipping oversized attachment ${image.fileId}`);
+                return {
+                    text: text || "Image too large (max 10 MB). Send a smaller image.",
+                    fromChatId: String(message.chat.id),
+                    quotedMessageId: message.reply_to_message != null
+                        ? String(message.reply_to_message.message_id)
+                        : undefined,
+                    timestamp: message.date ? message.date * 1000 : Date.now(),
+                    attachments: [],
+                };
+            }
+            try {
+                attachments = [await this.downloadFile(image.fileId, image.mimeType)];
+            }
+            catch (err) {
+                this.logger.warn(`Failed to download attachment: ${String(err)}`);
+                return {
+                    text: text || `Could not download image: ${String(err)}`,
+                    fromChatId: String(message.chat.id),
+                    quotedMessageId: message.reply_to_message != null
+                        ? String(message.reply_to_message.message_id)
+                        : undefined,
+                    timestamp: message.date ? message.date * 1000 : Date.now(),
+                    attachments: [],
+                };
+            }
+        }
+        const photoOnly = attachments.length > 0 && text === "";
+        return {
+            text,
+            fromChatId: String(message.chat.id),
+            quotedMessageId: message.reply_to_message != null ? String(message.reply_to_message.message_id) : undefined,
+            timestamp: message.date ? message.date * 1000 : Date.now(),
+            attachments,
+            photoOnly: photoOnly || undefined,
+        };
+    }
+    async sendText(chatId, text) {
+        const sent = await this.call("sendMessage", { chat_id: chatId, text });
+        return sent?.message_id != null ? String(sent.message_id) : undefined;
+    }
+    static sameChat(a, b) {
+        return a.trim() !== "" && a.trim() === b.trim();
+    }
+    async cleanupOldMedia() {
+        try {
+            const entries = await readdir(this.mediaDir);
+            const cutoff = Date.now() - this.mediaTtlMs;
+            for (const name of entries) {
+                const path = join(this.mediaDir, name);
+                try {
+                    const st = await stat(path);
+                    if (st.mtimeMs < cutoff)
+                        await unlink(path);
+                }
+                catch {
+                    // ignore per-file errors
+                }
+            }
+        }
+        catch {
+            // media dir may not exist yet
+        }
+    }
+    async close() {
+        this.stopping = true;
+        this.open = false;
+    }
+}

package/dist/transcript.js

@@ -0,0 +1,56 @@
+/**
+ * Append-only Markdown transcript of the rolling remote chat.
+ *
+ * Every turn of the phone-driven conversation (your prompt, the plan, the
+ * result, an answer) is appended to a single file (default
+ * `<agentCwd>/remote-chat.md`). The file lives in the repo so you can read the
+ * same conversation on your computer that you are driving from your phone, and
+ * git tracks its history.
+ */
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const HEADING = {
+    you: "You (phone)",
+    plan: "Plan",
+    done: "Done",
+    ask: "Ask",
+    answer: "Answer",
+    error: "Error",
+    system: "System",
+};
+const FILE_HEADER = "# Remote chat\n\n" +
+    "Live transcript of the conversation you drive from your phone over Telegram. " +
+    "Each turn is appended below; this file is safe to commit for history.\n";
+function timestamp() {
+    return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+/** A transcript writer bound to a single file path. */
+export class Transcript {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    get filePath() {
+        return this.path;
+    }
+    ensureFile() {
+        if (existsSync(this.path))
+            return;
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, FILE_HEADER, "utf8");
+    }
+    /** Append a single conversation turn. Best-effort; never throws. */
+    append(entry) {
+        try {
+            this.ensureFile();
+            const label = HEADING[entry.role];
+            const suffix = entry.id ? ` (${entry.id})` : "";
+            const body = entry.text.trim() === "" ? "(empty)" : entry.text.trim();
+            const block = `\n## ${timestamp()} - ${label}${suffix}\n\n${body}\n`;
+            appendFileSync(this.path, block, "utf8");
+        }
+        catch {
+            // Best-effort: a failed transcript write must not break the chat.
+        }
+    }
+}