sensorium-mcp 2.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andriy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# sensorium-mcp
+
+An MCP (Model Context Protocol) server for remote control of AI assistants via Telegram.
+
+## Overview
+
+This server exposes four tools that allow an AI assistant (e.g. GitHub Copilot) to be operated remotely through a Telegram bot:
+
+| Tool | Description |
+|------|-------------|
+| `start_session` | Begin or resume a sensorium session. Creates a dedicated Telegram topic thread (or resumes an existing one by name or thread ID). |
+| `remote_copilot_wait_for_instructions` | Blocks until a new message (text, photo, document, or voice) arrives in the active topic or the timeout elapses. |
+| `report_progress` | Sends a progress update back to the operator using standard Markdown (auto-converted to Telegram MarkdownV2). |
+| `send_file` | Sends a file or image to the operator via Telegram (base64-encoded). Images are sent as photos; everything else as documents. |
+| `send_voice` | Sends a voice message to the operator via Telegram. Text is converted to speech using OpenAI TTS (max 4096 chars). |
+
+## Features
+
+- **Concurrent sessions** — Multiple VS Code windows can run independent sessions simultaneously. A shared file-based dispatcher ensures only one process polls Telegram (`getUpdates`), while each session reads from its own per-thread message file. No 409 conflicts, no lost updates.
+- **Named session persistence** — Sessions are mapped by name to Telegram thread IDs in `~/.remote-copilot-mcp-sessions.json`. Calling `start_session({ name: "Fix auth bug" })` always resumes the same thread, even across VS Code restarts.
+- **Image & document support** — Send photos or documents to the agent from Telegram; the agent receives them as native MCP image content blocks or base64 text. The agent can also send files back via the `send_file` tool.
+- **Voice message support** — Send voice messages from Telegram; they are automatically transcribed using OpenAI Whisper and delivered as text to the agent. The agent can also send voice responses back via OpenAI TTS. Requires `OPENAI_API_KEY`.
+- **Automatic Markdown conversion** — Standard Markdown in `report_progress` is automatically converted to Telegram MarkdownV2, including code blocks, tables, blockquotes, and special characters.
+- **Keep-alive pings** — Periodic heartbeat messages to Telegram so the operator knows the agent is still alive during long idle periods.
+
+## Prerequisites
+
+- Node.js 18 or later (uses native `fetch`)
+- A [Telegram bot token](https://core.telegram.org/bots#botfather) (`TELEGRAM_TOKEN`)
+- A Telegram **forum supergroup** where the bot is an admin with the **Manage Topics** right
+  - In Telegram: create a group → *Edit → Topics → Enable*
+  - Add your bot as admin and grant it *Manage Topics*
+  - Copy the group's chat ID (e.g. `-1001234567890`) as `TELEGRAM_CHAT_ID`
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Set the following environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TELEGRAM_TOKEN` | ✅ | — | Telegram Bot API token from @BotFather |
+| `TELEGRAM_CHAT_ID` | ✅ | — | Chat ID of the forum supergroup (e.g. `-1001234567890`). The bot must be admin with Manage Topics right. |
+| `WAIT_TIMEOUT_MINUTES` | ❌ | `120` | Minutes to wait for a message before timing out |
+| `OPENAI_API_KEY` | ❌ | — | OpenAI API key for voice message transcription (Whisper) and TTS (`send_voice`). Without it, voice messages show a placeholder instead of a transcript. |
+| `VOICE_ANALYSIS_URL` | ❌ | — | URL of the voice emotion analysis microservice (e.g. `https://voice-analysis.example.com`). When set, voice messages are analyzed for emotion and the result is included with the transcript. See `voice-analysis/` for the deployable service. |
+
+## Usage
+
+### Simply use this prompt
+
+```bash
+Start remote copilot session
+```
+
+### Configure in MCP client (e.g. VS Code Copilot)
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "sensorium-mcp": {
+      "command": "npx",
+      "args": [
+        "sensorium-mcp@latest"
+      ],
+      "env": {
+        "TELEGRAM_TOKEN": "${input:TELEGRAM_TOKEN}",
+        "TELEGRAM_CHAT_ID": "${input:TELEGRAM_CHAT_ID}",
+        "WAIT_TIMEOUT_MINUTES": "30"
+      },
+      "type": "stdio"
+    }
+  }
+}
+```
+
+## How it works
+
+1. The AI calls `start_session`, which creates a new Telegram topic (e.g. *Copilot — 07 Mar 2026, 14:30*) or resumes an existing one by name/thread ID.
+2. A shared **dispatcher** runs a single `getUpdates` poller (elected via a lock file at `~/.remote-copilot-mcp/poller.lock`). It writes incoming messages to per-thread JSONL files under `~/.remote-copilot-mcp/threads/`. Each MCP instance reads from its own thread file — no 409 conflicts between concurrent sessions.
+3. When a message arrives (text, photo, or document), the tool downloads any media, converts it to MCP content blocks (image or text with base64), and instructs the AI to act on it.
+4. The AI calls `report_progress` to post status updates and `send_file` to send files/images back to the operator.
+5. If the timeout elapses with no message, the tool tells the AI to call `remote_copilot_wait_for_instructions` again immediately.
+
+### Architecture
+
+```
+~/.remote-copilot-mcp/
+  poller.lock                 ← PID + timestamp; first instance becomes the poller
+  offset                      ← shared getUpdates offset
+  threads/
+    <threadId>.jsonl           ← messages for each topic thread
+    general.jsonl              ← messages with no thread ID
+~/.remote-copilot-mcp-sessions.json  ← name → threadId mapping
+```

package/dist/dispatcher.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared Telegram update dispatcher.
+ *
+ * Problem: Telegram's getUpdates API is exclusive — only one poller per bot
+ * token. When multiple MCP server instances run concurrently (multiple VS Code
+ * windows), they fight for the poll lock with 409 Conflict errors and silently
+ * lose updates meant for other sessions.
+ *
+ * Solution: A file-system–based message broker.
+ *
+ *   1. One MCP instance becomes the **poller** (elected via a lock file).
+ *      It calls getUpdates and writes incoming messages to per-thread JSON
+ *      files under ~/.remote-copilot-mcp/threads/<threadId>.jsonl.
+ *   2. All MCP instances (including the poller) **read** from their own
+ *      thread file to retrieve messages. This is contention-free because
+ *      each instance is scoped to its own thread ID.
+ *   3. The lock file is automatically released if the poller process dies
+ *      (stale-lock detection via PID check). Another instance then takes over.
+ *
+ * The dispatcher exports two public functions:
+ *   - startDispatcher(telegram, chatId)  — call once on MCP server startup.
+ *   - readThreadMessages(threadId)       — non-blocking; returns and clears
+ *                                           pending messages for a thread.
+ */
+import type { TelegramClient } from "./telegram.js";
+export interface StoredMessage {
+    update_id: number;
+    message: {
+        message_id: number;
+        chat_id: number;
+        text?: string;
+        caption?: string;
+        message_thread_id?: number;
+        photo?: Array<{
+            file_id: string;
+            width: number;
+            height: number;
+        }>;
+        document?: {
+            file_id: string;
+            file_name?: string;
+            mime_type?: string;
+        };
+        voice?: {
+            file_id: string;
+            duration: number;
+            mime_type?: string;
+        };
+        video_note?: {
+            file_id: string;
+            length: number;
+            duration: number;
+        };
+        date: number;
+    };
+}
+/**
+ * Read and clear all pending messages for a thread.
+ * Uses rename for atomic read-and-clear to prevent message loss.
+ */
+export declare function readThreadMessages(threadId: number | undefined): StoredMessage[];
+/**
+ * Non-destructive peek at pending messages for a thread.
+ * Unlike readThreadMessages, this does NOT consume the messages — they remain
+ * in the thread file for the next readThreadMessages call.
+ */
+export declare function peekThreadMessages(threadId: number | undefined): StoredMessage[];
+/**
+ * Start the shared dispatcher.
+ * - Ensures directories exist.
+ * - Attempts to acquire the poller lock.
+ * - If acquired, starts a polling loop that writes to per-thread files.
+ * - If not acquired, this instance is a consumer only (reads from thread files).
+ *
+ * Returns: whether this instance became the poller.
+ */
+export declare function startDispatcher(telegram: TelegramClient, chatId: string): Promise<boolean>;
+/**
+ * Stop the poller loop (if this instance is the poller).
+ */
+export declare function stopDispatcher(): void;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../src/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAaH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAqKpD,MAAM,WAAW,aAAa;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,KAAK,CAAC,EAAE,KAAK,CAAC;YACV,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,EAAE,MAAM,CAAC;YACd,MAAM,EAAE,MAAM,CAAC;SAClB,CAAC,CAAC;QACH,QAAQ,CAAC,EAAE;YACP,OAAO,EAAE,MAAM,CAAC;YAChB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,SAAS,CAAC,EAAE,MAAM,CAAC;SACtB,CAAC;QACF,KAAK,CAAC,EAAE;YACJ,OAAO,EAAE,MAAM,CAAC;YAChB,QAAQ,EAAE,MAAM,CAAC;YACjB,SAAS,CAAC,EAAE,MAAM,CAAC;SACtB,CAAC;QACF,UAAU,CAAC,EAAE;YACT,OAAO,EAAE,MAAM,CAAC;YAChB,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;SACpB,CAAC;QACF,IAAI,EAAE,MAAM,CAAC;KAChB,CAAC;CACL;AAgCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,EAAE,CAiBhF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,EAAE,CAShF;AAgID;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACjC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAgHlB;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAGrC"}

package/dist/dispatcher.js

@@ -0,0 +1,464 @@
+/**
+ * Shared Telegram update dispatcher.
+ *
+ * Problem: Telegram's getUpdates API is exclusive — only one poller per bot
+ * token. When multiple MCP server instances run concurrently (multiple VS Code
+ * windows), they fight for the poll lock with 409 Conflict errors and silently
+ * lose updates meant for other sessions.
+ *
+ * Solution: A file-system–based message broker.
+ *
+ *   1. One MCP instance becomes the **poller** (elected via a lock file).
+ *      It calls getUpdates and writes incoming messages to per-thread JSON
+ *      files under ~/.remote-copilot-mcp/threads/<threadId>.jsonl.
+ *   2. All MCP instances (including the poller) **read** from their own
+ *      thread file to retrieve messages. This is contention-free because
+ *      each instance is scoped to its own thread ID.
+ *   3. The lock file is automatically released if the poller process dies
+ *      (stale-lock detection via PID check). Another instance then takes over.
+ *
+ * The dispatcher exports two public functions:
+ *   - startDispatcher(telegram, chatId)  — call once on MCP server startup.
+ *   - readThreadMessages(threadId)       — non-blocking; returns and clears
+ *                                           pending messages for a thread.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { errorMessage } from "./utils.js";
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const BASE_DIR = join(homedir(), ".remote-copilot-mcp");
+const THREADS_DIR = join(BASE_DIR, "threads");
+const LOCK_FILE = join(BASE_DIR, "poller.lock");
+const OFFSET_FILE = join(BASE_DIR, "offset");
+function ensureDirs() {
+    mkdirSync(THREADS_DIR, { recursive: true });
+    recoverOrphanedReads();
+}
+/**
+ * On startup, scan for orphaned `.reading.PID` files left by hard-crashed
+ * processes and append their content back to the original thread file
+ * so those messages aren't permanently lost.
+ */
+function recoverOrphanedReads() {
+    try {
+        const files = readdirSync(THREADS_DIR);
+        for (const f of files) {
+            const match = f.match(/^(.+)\.reading\.(\d+)$/);
+            if (match) {
+                const pid = Number.parseInt(match[2], 10);
+                if (!isPidAlive(pid)) {
+                    const orphan = join(THREADS_DIR, f);
+                    const original = join(THREADS_DIR, match[1]);
+                    try {
+                        const content = readFileSync(orphan, "utf8");
+                        writeFileSync(original, content, { flag: "a", encoding: "utf8" });
+                        unlinkSync(orphan);
+                        process.stderr.write(`[dispatcher] Recovered orphaned file: ${f}\n`);
+                    }
+                    catch { /* best effort */ }
+                }
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+}
+// ---------------------------------------------------------------------------
+// Lock helpers
+// ---------------------------------------------------------------------------
+function readLock() {
+    try {
+        const raw = readFileSync(LOCK_FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid === "number" && typeof parsed.ts === "number") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write (refresh) the lock file, but only if we still own it.
+ * Prevents a TOCTOU race where two pollers run simultaneously:
+ * if another process stole the lock between our check and write,
+ * we must not overwrite their lock.
+ *
+ * Returns true if the lock was refreshed, false if we lost ownership.
+ */
+function refreshLock() {
+    const current = readLock();
+    if (current && current.pid !== process.pid) {
+        return false; // Someone else owns the lock now.
+    }
+    writeFileSync(LOCK_FILE, JSON.stringify({ pid: process.pid, ts: Date.now() }), "utf8");
+    return true;
+}
+function removeLock() {
+    try {
+        unlinkSync(LOCK_FILE);
+    }
+    catch {
+        // Already gone.
+    }
+}
+/** Check whether a PID is still alive. */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0); // Signal 0 = existence check, does not kill.
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Try to become the poller using exclusive file creation to prevent TOCTOU races.
+ * - If no lock file exists → atomically create it (flag: "wx").
+ * - If lock file exists but the PID is dead → remove and retry.
+ * - If lock file exists, PID is alive, but lock is stale → remove and retry.
+ * - Otherwise → someone else is the poller.
+ */
+const STALE_LOCK_MS = 90 * 1000; // 90 seconds
+function tryAcquireLock() {
+    const existing = readLock();
+    if (existing) {
+        const alive = isPidAlive(existing.pid);
+        const stale = Date.now() - existing.ts > STALE_LOCK_MS;
+        if (alive && !stale) {
+            return false; // Someone else is actively polling.
+        }
+        // Dead or stale — remove before attempting exclusive create.
+        try {
+            unlinkSync(LOCK_FILE);
+        }
+        catch { /* race-ok */ }
+    }
+    else if (existsSync(LOCK_FILE)) {
+        // Lock file exists but is corrupt/empty (readLock returned null).
+        // Remove it so the exclusive create below can succeed.
+        try {
+            unlinkSync(LOCK_FILE);
+        }
+        catch { /* race-ok */ }
+    }
+    // Atomic exclusive create: fails if another process created first.
+    try {
+        writeFileSync(LOCK_FILE, JSON.stringify({ pid: process.pid, ts: Date.now() }), { encoding: "utf8", flag: "wx" });
+        return true;
+    }
+    catch {
+        return false; // Another process won the race.
+    }
+}
+// ---------------------------------------------------------------------------
+// Offset persistence (shared across all instances)
+// ---------------------------------------------------------------------------
+function readOffset() {
+    try {
+        const raw = readFileSync(OFFSET_FILE, "utf8").trim();
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function writeOffset(offset) {
+    try {
+        writeFileSync(OFFSET_FILE, String(offset), "utf8");
+    }
+    catch {
+        // Non-fatal.
+    }
+}
+function threadFilePath(threadId) {
+    return join(THREADS_DIR, `${threadId}.jsonl`);
+}
+/** Parse JSONL content into StoredMessage[], skipping corrupt lines. */
+function parseJsonlLines(raw, label) {
+    if (!raw)
+        return [];
+    const results = [];
+    for (const line of raw.split("\n")) {
+        try {
+            results.push(JSON.parse(line));
+        }
+        catch {
+            process.stderr.write(`[dispatcher] Skipping corrupt JSONL line in ${label}\n`);
+        }
+    }
+    return results;
+}
+/**
+ * Append a message to a thread's JSONL file.
+ * Throws on write failure so the caller can track which messages were persisted.
+ */
+function appendToThread(threadId, msg) {
+    const file = threadFilePath(threadId);
+    const line = JSON.stringify(msg) + "\n";
+    writeFileSync(file, line, { flag: "a", encoding: "utf8" });
+}
+/**
+ * Read and clear all pending messages for a thread.
+ * Uses rename for atomic read-and-clear to prevent message loss.
+ */
+export function readThreadMessages(threadId) {
+    const key = threadId ?? "general";
+    const file = threadFilePath(key);
+    const tmp = file + ".reading." + process.pid;
+    try {
+        renameSync(file, tmp);
+    }
+    catch {
+        return [];
+    }
+    try {
+        const raw = readFileSync(tmp, "utf8").trim();
+        return parseJsonlLines(raw, `${key}.jsonl`);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* already gone */ }
+    }
+}
+/**
+ * Non-destructive peek at pending messages for a thread.
+ * Unlike readThreadMessages, this does NOT consume the messages — they remain
+ * in the thread file for the next readThreadMessages call.
+ */
+export function peekThreadMessages(threadId) {
+    const key = threadId ?? "general";
+    const file = threadFilePath(key);
+    try {
+        const raw = readFileSync(file, "utf8").trim();
+        return parseJsonlLines(raw, `${key}.jsonl`);
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Poller loop
+// ---------------------------------------------------------------------------
+let pollerRunning = false;
+let pollAbortController;
+async function pollOnce(telegram, chatId) {
+    if (!refreshLock()) {
+        // We lost lock ownership — another process took over. Step down.
+        pollerRunning = false;
+        return;
+    }
+    const POLL_TIMEOUT_SECONDS = 10;
+    let offset = readOffset();
+    // Refresh the lock periodically during long polls / 409 retries
+    // to prevent it from going stale (STALE_LOCK_MS = 90 s).
+    const lockRefresher = setInterval(() => {
+        if (!refreshLock()) {
+            pollerRunning = false;
+            pollAbortController?.abort();
+        }
+    }, 15_000);
+    try {
+        pollAbortController = new AbortController();
+        const updates = await telegram.getUpdates(offset, POLL_TIMEOUT_SECONDS, pollAbortController.signal);
+        // Refresh again after the (potentially 10-second) long poll returns.
+        if (!refreshLock()) {
+            pollerRunning = false;
+            return;
+        }
+        if (updates.length === 0)
+            return;
+        // Track the highest offset for which ALL messages were successfully written.
+        let committedOffset = offset;
+        let allSucceeded = true;
+        for (const u of updates) {
+            if (!u.message) {
+                // Non-message update — skip but still advance past it.
+                committedOffset = u.update_id + 1;
+                continue;
+            }
+            if (String(u.message.chat.id) !== chatId) {
+                committedOffset = u.update_id + 1;
+                continue;
+            }
+            const threadId = u.message.message_thread_id ?? "general";
+            const stored = {
+                update_id: u.update_id,
+                message: {
+                    message_id: u.message.message_id,
+                    chat_id: u.message.chat.id,
+                    text: u.message.text,
+                    caption: u.message.caption,
+                    message_thread_id: u.message.message_thread_id,
+                    photo: u.message.photo?.map((p) => ({
+                        file_id: p.file_id,
+                        width: p.width,
+                        height: p.height,
+                    })),
+                    document: u.message.document ? {
+                        file_id: u.message.document.file_id,
+                        file_name: u.message.document.file_name,
+                        mime_type: u.message.document.mime_type,
+                    } : undefined,
+                    voice: u.message.voice ? {
+                        file_id: u.message.voice.file_id,
+                        duration: u.message.voice.duration,
+                        mime_type: u.message.voice.mime_type,
+                    } : undefined,
+                    video_note: u.message.video_note ? {
+                        file_id: u.message.video_note.file_id,
+                        length: u.message.video_note.length,
+                        duration: u.message.video_note.duration,
+                    } : undefined,
+                    date: u.message.date,
+                },
+            };
+            try {
+                appendToThread(threadId, stored);
+                committedOffset = u.update_id + 1;
+            }
+            catch (writeErr) {
+                process.stderr.write(`[dispatcher] Failed to write message ${u.update_id} to thread ${threadId}: ${errorMessage(writeErr)}\n`);
+                allSucceeded = false;
+                break; // Stop processing — don't skip messages.
+            }
+        }
+        // Only advance offset to the last successfully written message.
+        if (committedOffset > offset) {
+            writeOffset(committedOffset);
+        }
+        if (!allSucceeded) {
+            process.stderr.write("[dispatcher] Partial batch write. Will retry remaining messages on next poll.\n");
+        }
+    }
+    catch (err) {
+        // Ignore abort errors during shutdown.
+        if (err instanceof DOMException && err.name === "AbortError")
+            return;
+        process.stderr.write(`[dispatcher] Poll error: ${errorMessage(err)}\n`);
+    }
+    finally {
+        clearInterval(lockRefresher);
+    }
+}
+/**
+ * Start the shared dispatcher.
+ * - Ensures directories exist.
+ * - Attempts to acquire the poller lock.
+ * - If acquired, starts a polling loop that writes to per-thread files.
+ * - If not acquired, this instance is a consumer only (reads from thread files).
+ *
+ * Returns: whether this instance became the poller.
+ */
+export async function startDispatcher(telegram, chatId) {
+    ensureDirs();
+    const isPoller = tryAcquireLock();
+    const CONSUMER_RETRY_MS = 10_000;
+    // Shared cleanup + loop helpers.
+    let cleanupRegistered = false;
+    const registerCleanup = () => {
+        if (cleanupRegistered)
+            return;
+        cleanupRegistered = true;
+        const cleanup = () => {
+            pollerRunning = false;
+            pollAbortController?.abort();
+            removeLock();
+        };
+        process.on("exit", cleanup);
+        process.on("SIGINT", () => { cleanup(); process.exit(0); });
+        process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+    };
+    const installConsumerRetry = () => {
+        const timer = setInterval(() => {
+            if (tryAcquireLock()) {
+                clearInterval(timer);
+                process.stderr.write("[dispatcher] Promoted to poller (previous poller seems inactive).\n");
+                pollerRunning = true;
+                startLoop();
+                registerCleanup();
+            }
+        }, CONSUMER_RETRY_MS);
+        timer.unref();
+    };
+    const startLoop = () => {
+        const loop = async () => {
+            while (pollerRunning) {
+                const currentLock = readLock();
+                if (currentLock && currentLock.pid !== process.pid) {
+                    process.stderr.write(`[dispatcher] Lock taken by PID ${currentLock.pid}. Stepping down to consumer.\n`);
+                    pollerRunning = false;
+                    installConsumerRetry();
+                    break;
+                }
+                try {
+                    await pollOnce(telegram, chatId);
+                }
+                catch (err) {
+                    process.stderr.write(`[dispatcher] Unexpected poll error: ${errorMessage(err)}\n`);
+                    await new Promise((r) => setTimeout(r, 5000));
+                }
+                await new Promise((r) => setTimeout(r, 500));
+            }
+        };
+        void loop();
+    };
+    if (isPoller) {
+        process.stderr.write("[dispatcher] This instance is the poller.\n");
+        // On first run with no offset file, skip all old updates in one call
+        // by fetching the latest update_id and setting the offset past it.
+        // Awaited so the poll loop never sees offset=0.
+        if (!existsSync(OFFSET_FILE)) {
+            process.stderr.write("[dispatcher] No offset file. Skipping old updates...\n");
+            try {
+                // Use a short timeout to prevent blocking startup if another
+                // poller is active (409 retry loop could stall for 60+ seconds).
+                const drainAbort = new AbortController();
+                const drainTimeout = setTimeout(() => drainAbort.abort(), 10_000);
+                const latest = await telegram.getUpdates(-1, 0, drainAbort.signal);
+                clearTimeout(drainTimeout);
+                if (latest.length > 0) {
+                    const skipTo = latest[latest.length - 1].update_id + 1;
+                    writeOffset(skipTo);
+                    process.stderr.write(`[dispatcher] Skipped to offset ${skipTo}.\n`);
+                }
+                else {
+                    writeOffset(0);
+                }
+            }
+            catch (err) {
+                // Don't write offset=0 — leave it at whatever the current value is.
+                // If the file still doesn't exist, readOffset() returns 0 which is
+                // acceptable because the drain simply failed to optimise.
+                process.stderr.write(`[dispatcher] Warning: drain failed: ${errorMessage(err)}. Poll loop will start from offset 0.\n`);
+            }
+        }
+        pollerRunning = true;
+        startLoop();
+        registerCleanup();
+    }
+    else {
+        process.stderr.write("[dispatcher] Another instance is the poller. This instance is a consumer only.\n");
+        // Periodically try to become the poller in case the current one dies
+        // but its PID remains alive (zombie process, stuck socket, etc.).
+        installConsumerRetry();
+    }
+    return isPoller;
+}
+/**
+ * Stop the poller loop (if this instance is the poller).
+ */
+export function stopDispatcher() {
+    pollerRunning = false;
+    removeLock();
+}
+//# sourceMappingURL=dispatcher.js.map