cursor-telegram-mcp 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuval Ikobson
+
+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,272 @@
+# cursor-telegram-mcp
+
+Manage Cursor from your phone over Telegram. A local [MCP](https://modelcontextprotocol.io)
+server plus an auto-started background worker that lets a Cursor agent talk to
+you on Telegram, and lets you drive work from your phone:
+
+- When the agent finishes a task, it messages you (finish notification).
+- When the agent is blocked on a decision, it mirrors the question to Telegram
+  and keeps working / waiting until your reply comes back.
+- Command mode: text a task to the bot and a headless Cursor agent plans it,
+  sends you the plan, and runs it once you reply `YES` - so you can leave the
+  laptop on the charger and drive work entirely from your phone.
+
+Local and bring-your-own-bot: each person installs the package, creates their
+own Telegram bot, and everything runs on their own machine. There is no shared
+server and nothing shared between users. It uses the official
+[Telegram Bot API](https://core.telegram.org/bots/api) over HTTPS - no QR, no
+eSIM, no SIM. Pending questions are kept in memory only.
+
+## Add to Cursor (one click)
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=cursor-telegram-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImN1cnNvci10ZWxlZ3JhbS1tY3AiXX0%3D)
+
+This adds the server to your global `~/.cursor/mcp.json` (the "Installed MCP
+Servers" list in Cursor Settings → Tools & MCP). It runs `npx -y
+cursor-telegram-mcp`, so it requires the package to be published to npm. After
+adding, run `npx cursor-telegram-mcp setup` once to connect your bot.
+
+Prefer it under "Plugin MCP Servers" / the Cursor marketplace? See
+[As a Cursor plugin](#as-a-cursor-plugin) below.
+
+## Quick start
+
+### 1. Configure your bot (one time)
+
+```bash
+npx cursor-telegram-mcp setup
+```
+
+The wizard walks you through creating a bot with [@BotFather](https://t.me/BotFather),
+validates the token, captures your chat id (you message the bot once), and
+optionally enables command mode with a Cursor API key. It saves everything to a
+local config file (`~/.config/cursor-telegram/config.json`, or
+`%APPDATA%\cursor-telegram\config.json` on Windows).
+
+### 2. Add it to Cursor
+
+Add this to your project's `.cursor/mcp.json` (or Cursor Settings -> Tools & MCP):
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "cursor-telegram-mcp"]
+    }
+  }
+}
+```
+
+Reload MCP in Cursor. That's it - the MCP server auto-starts the background
+worker. Run `npx cursor-telegram-mcp doctor` anytime to check status.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  cursor["Cursor agent"] -->|"MCP stdio (npx)"| mcp["MCP server (thin) dist/index.js"]
+  mcp -->|"GET /health"| check{"worker up?"}
+  check -->|no| spawn["spawn detached worker (singleton)"]
+  check -->|yes| reuse["reuse running worker"]
+  spawn --> worker["worker dist/worker.js"]
+  reuse --> worker
+  worker --> store["in-memory question store"]
+  worker -->|"command mode (optional)"| agent["headless Cursor agent (cursor-agent CLI)"]
+  worker -->|"Bot API: sendMessage / getUpdates"| tg["Telegram"]
+  tg -->|"your reply / texted task"| worker
+  phone["Your phone (Telegram app)"] --> tg
+```
+
+The worker owns the Telegram connection and survives Cursor/MCP reloads. The MCP
+server is a thin client Cursor launches per project; it auto-spawns the worker if
+one is not already running (the worker's port guard keeps it a singleton, so
+multiple projects safely share one worker). For non-blocking questions,
+`ask_human_for_guidance` returns a `questionId` immediately and the agent polls
+`check_human_response` (or long-polls with `waitMs`). For blocking decisions,
+`ask_human_and_wait` long-polls the worker and returns as soon as you reply on
+Telegram (no fixed 30-second sleep after your answer).
+
+## Timeouts (three different values)
+
+- getUpdates 30s: worker receive path only (Bot API long poll for inbound messages).
+- waitMs / ask_human_and_wait: agent wait path — long-poll the worker and wake
+  immediately when you reply (do NOT sleep on a fixed timer between checks).
+- TG_RESPONSE_TIMEOUT_MIN (default 30): minutes before a pending question reports
+  timed_out.
+
+## Tools exposed to the agent
+
+| Tool | Purpose |
+| --- | --- |
+| `notify_human_task_complete(summary)` | Fire-and-forget "task done" message. |
+| `ask_human_for_guidance(question)` | Send a question, return a `questionId` right away. |
+| `ask_human_and_wait(question, timeoutMin?)` | Send a question and block until you answer or it times out. |
+| `check_human_response(questionId, waitMs?)` | Poll for your reply: `answered` / `pending` / `timed_out`. Long-polls by default when `waitMs` is omitted; pass `waitMs=0` for an instant check. |
+
+The rule [.cursor/rules/telegram-hitl.mdc](.cursor/rules/telegram-hitl.mdc) tells
+the agent to send a completion message when it finishes and to mirror any
+question it would ask in chat to Telegram.
+
+## Command mode (drive work from your phone)
+
+When a Cursor API key is configured (`setup` step 3, or `CURSOR_API_KEY`), the
+worker treats any message that is not answering an open question as a task:
+
+1. You text the bot, e.g. `add a healthcheck endpoint and a test`.
+2. A read-only headless Cursor agent investigates and replies with a numbered
+   plan (`Plan (C-1) ...`). No files are changed yet.
+3. You reply `YES` to execute (or `NO` to cancel). On `YES`, a second agent
+   carries out the plan and texts back a summary.
+
+You can also use `/ask <question>` (read-only Q&A) and `/plan <task>` explicitly,
+and send `status` to see what's running. Command mode needs the Cursor CLI
+(`cursor-agent`) installed:
+
+- macOS / Linux: `curl https://cursor.com/install -fsS | bash`
+- Windows (PowerShell): `irm 'https://cursor.com/install?win32=true' | iex`
+
+The headless agent runs locally against `TG_AGENT_CWD` (default: the directory
+the worker started in). Every task is gated: nothing changes code until you
+approve the plan. Sessions are in memory only.
+
+## Keeping the worker alive
+
+The worker runs only while your laptop is awake. It auto-starts with the MCP
+server and stays up across Cursor reloads, so for "laptop on the charger, manage
+from my phone" you usually need nothing else.
+
+If you want it to survive reboots without opening Cursor, run it under your OS
+service manager (launchd / systemd / Task Scheduler) calling
+`cursor-telegram-mcp worker`. (Note: on macOS, launchd agents cannot read files
+under `~/Desktop`/`~/Documents`/`~/Downloads`; install the package or project
+outside those folders.)
+
+## Configuration
+
+Values resolve in this order: real environment variables (e.g. set in
+`mcp.json`) > the config file written by `setup` > a local `.env` (dev) >
+defaults.
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `TELEGRAM_BOT_TOKEN` | (required) | Bot token from @BotFather. |
+| `TELEGRAM_CHAT_ID` | (required) | Chat to message; replies are matched to it. |
+| `TG_PROJECT` | `default` | Project label prefixed to this client's messages. |
+| `TG_WORKER_URL` | `http://127.0.0.1:8787` | Worker base URL the MCP calls. |
+| `TG_WORKER_HOST` | `127.0.0.1` | Host the worker binds to. |
+| `TG_WORKER_PORT` | `8787` | Port the worker listens on. |
+| `TG_MIN_SEND_GAP_MS` | `3000` | Minimum gap between outgoing messages. |
+| `TG_RESPONSE_TIMEOUT_MIN` | `30` | Minutes before a pending question reports `timed_out`. |
+| `CURSOR_API_KEY` | (unset) | Enables command mode. [Cursor -> Integrations](https://cursor.com/dashboard/integrations). |
+| `TG_AGENT_CWD` | worker cwd | Directory the headless command-mode agent works in. |
+| `TG_AGENT_MODEL` | `composer-2.5` | Model id for the headless agent. |
+| `TG_AGENT_LOAD_SETTINGS` | `false` | `true` to load `TG_AGENT_CWD`'s `.cursor` rules/MCP during runs. |
+
+## CLI
+
+```
+cursor-telegram-mcp [mcp]    Start the MCP server (default; Cursor runs this)
+cursor-telegram-mcp setup    First-time setup: create/link your bot
+cursor-telegram-mcp login    Print and save your Telegram chat id
+cursor-telegram-mcp worker   Run the background worker in the foreground
+cursor-telegram-mcp doctor   Diagnose configuration and connectivity
+```
+
+## As a Cursor plugin
+
+This repo is also packaged as a Cursor plugin (manifest in
+[.cursor-plugin/plugin.json](.cursor-plugin/plugin.json), server config in
+[mcp.json](mcp.json), behavior rule in
+[.cursor/rules/telegram-hitl.mdc](.cursor/rules/telegram-hitl.mdc)). Installing
+it as a plugin makes the server show up under "Plugin MCP Servers" and bundles
+the human-in-the-loop rule automatically.
+
+Try it locally (no publishing required):
+
+```bash
+# make the `npx -y cursor-telegram-mcp` command resolve locally
+npm run build && npm pack && npm i -g ./cursor-telegram-mcp-*.tgz
+
+# load the plugin from this checkout, then reload Cursor
+ln -s "$(pwd)" ~/.cursor/plugins/local/cursor-telegram-mcp
+```
+
+Then "Developer: Reload Window" in Cursor — the `telegram` server appears under
+Settings → Tools & MCP → "Plugin MCP Servers". To list it in the in-app
+marketplace for one-click discovery, publish the repo (public, open source) at
+[cursor.com/marketplace/publish](https://cursor.com/marketplace/publish).
+
+## Multiple projects
+
+All your projects can share one worker (one bot, one chat). Each project's
+`mcp.json` sets a different `TG_PROJECT`; messages are prefixed and numbered:
+`[billing-api] Q-7`. Answer by using Telegram Reply on the specific question
+message so the worker matches it to the right `Q-<n>`; otherwise the oldest open
+question is answered first.
+
+## Replying
+
+Reply with a normal Telegram message. With several questions open, reply to the
+specific question message to answer it precisely; otherwise the oldest open
+question is answered first.
+
+## Answering from your phone
+
+When the agent needs a decision while you are away from the laptop:
+
+1. Reply on Telegram. Prefer Telegram Reply on the specific Q-n message so the
+   worker matches your answer to the right question.
+2. Ignore the IDE Questions panel (A/B/C, Skip, Continue) when the agent says
+   the question was also sent to Telegram as Q-n. That panel is separate; Skip
+   there does not read your Telegram reply.
+3. The agent should resume as soon as it sees your answer (`ask_human_and_wait`
+   wakes immediately on reply; `check_human_response` long-polls by default when
+   you omit `waitMs`, or pass `waitMs=0` for an instant status check). If it
+   picks a default instead, send a follow-up message in the IDE chat with your
+   choice.
+
+Use Telegram for remote decisions; use the IDE panel only when you are at the
+desk and not relying on Telegram for that question.
+
+## Develop from source
+
+```bash
+npm install
+npm run setup       # or: npm run login (after a token is set)
+npm run worker      # foreground worker (tsx)
+npm run start       # MCP server (tsx)
+npm run typecheck
+npm run build       # emit dist/ for publishing
+```
+
+## Notes & limitations
+
+- Local-only: if the laptop sleeps or the worker stops, messaging pauses until
+  it is back. Questions are in memory, so a worker restart forgets any
+  unanswered question (by design).
+- Per user: each person creates their own bot and runs their own worker (one bot
+  token can only be polled by one process).
+- Command mode requires the `cursor-agent` CLI and a Cursor API key; without
+  them, notifications and questions still work.
+
+## Project layout
+
+```
+src/
+  cli.ts        # CLI dispatcher (bin) -> mcp / setup / login / worker / doctor
+  index.ts      # thin MCP stdio server; auto-spawns the worker
+  worker.ts     # long-running Telegram worker + localhost HTTP API
+  config.ts     # config resolution (env > config file > .env > defaults)
+  setup.ts      # interactive first-time setup wizard
+  login.ts      # chat-id discovery helper
+  doctor.ts     # diagnostics
+  telegram.ts   # Bot API client: long-poll getUpdates, sendText, media
+  agentRunner.ts# command mode: headless Cursor agent (lazy @cursor/sdk)
+  store.ts      # in-memory pending-question store + reply matching
+  parseInbound.ts / splitMessage.ts / taskQueue.ts / formatTelegram.ts
+  answerWaiters.ts  # wake-on-answer for long-polling GET /response/:id
+.cursor/
+  rules/telegram-hitl.mdc  # agent behavior rule
+mcp.client.template.json   # per-project MCP client block to copy
+```

package/dist/agentRunner.js

@@ -0,0 +1,332 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+ * Command mode: run headless Cursor agents from a phone message.
+ *
+ * Flow (plan-then-approve, always gated):
+ *   1. You text the bot a task.
+ *   2. `plan()` runs a read-only Cursor agent that produces a step-by-step PLAN
+ *      only (no file changes) and returns it for you to review on your phone.
+ *   3. You reply YES -> `approve()` runs a second agent that executes the
+ *      approved plan and reports the result. Reply NO -> `reject()` drops it.
+ *
+ * Everything runs locally on this machine (the laptop on the charger) against
+ * `cwd`, using your CURSOR_API_KEY. Sessions live in memory only.
+ */
+import { readFileSync } from "node:fs";
+/**
+ * Lazily load the optional `@cursor/sdk`. Command mode needs it; if the package
+ * is not installed (it is an optionalDependency), surface a clear, actionable
+ * error instead of crashing the worker at import time.
+ */
+async function loadSdk() {
+    try {
+        return await import("@cursor/sdk");
+    }
+    catch {
+        throw new Error("command mode requires the optional '@cursor/sdk' package, which is not installed. " +
+            "Install it in the worker's environment (npm i @cursor/sdk) and restart.");
+    }
+}
+/** True if the error is a Cursor SDK startup failure (auth/config/network). */
+function isStartupError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "CursorAgentError");
+}
+function attachmentsToSdkImages(attachments) {
+    if (!attachments || attachments.length === 0)
+        return undefined;
+    const images = [];
+    for (const att of attachments) {
+        const data = readFileSync(att.localPath).toString("base64");
+        images.push({ data, mimeType: att.mimeType });
+    }
+    return images.length > 0 ? images : undefined;
+}
+function buildUserMessage(text, attachments) {
+    const images = attachmentsToSdkImages(attachments);
+    if (!images)
+        return text;
+    return { text, images };
+}
+async function runAgentPrompt(promptText, opts, attachments) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const message = buildUserMessage(promptText, attachments);
+        const { Agent } = await loadSdk();
+        const agent = __addDisposableResource(env_1, await Agent.create({
+            apiKey: opts.apiKey,
+            model: { id: opts.model },
+            local: { cwd: opts.cwd, settingSources: opts.settingSources },
+        }), true);
+        const run = await agent.send(message);
+        await run.wait();
+        return { status: run.status, result: run.result };
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
+    }
+}
+function coerceText(value) {
+    if (value == null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+const PLAIN_TEXT_RULE = `Write in plain text only — no Markdown (no **bold**, \`code\`, # headers, or ` +
+    `links in [label](url) form). Use numbered lists for steps and CAPS for ` +
+    `emphasis. Keep it short and easy to skim on a phone screen.`;
+const PLAN_PROMPT = (task) => `You are operating in PLAN-ONLY mode for a user reviewing on their phone.\n\n` +
+    `Task:\n${task}\n\n` +
+    `Investigate the repository as needed, then reply with a concise, numbered ` +
+    `step-by-step plan of exactly what you would change. Do NOT edit, create, or ` +
+    `delete any files, and do not run mutating commands.\n\n` +
+    PLAIN_TEXT_RULE;
+const EXECUTE_PROMPT = (task, plan) => `Execute the following approved plan for this task. Make the actual changes.\n\n` +
+    `Task:\n${task}\n\n` +
+    `Approved plan:\n${plan}\n\n` +
+    `Carry out the plan now. When finished, reply with a short summary of what you ` +
+    `changed and anything the user should review.\n\n` +
+    PLAIN_TEXT_RULE;
+const ASK_PROMPT = (question) => `You are answering a quick question from the user on their phone.\n\n` +
+    `Question:\n${question}\n\n` +
+    `Investigate the repository as needed (read-only), then answer directly. Do NOT ` +
+    `edit, create, or delete any files, and do not run mutating commands.\n\n` +
+    PLAIN_TEXT_RULE;
+/** Runs and tracks plan-then-approve command sessions. */
+export class CommandRunner {
+    opts;
+    nextId = 1;
+    nextAskId = 1;
+    sessions = new Map();
+    askSessions = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** True when a Cursor API key is configured. */
+    get enabled() {
+        return this.opts.apiKey.trim() !== "";
+    }
+    /** Most recent session waiting for a YES/NO approval, if any. */
+    latestAwaitingApproval() {
+        let latest;
+        for (const s of this.sessions.values()) {
+            if (s.status === "awaiting_approval" && (!latest || s.updatedAt > latest.updatedAt)) {
+                latest = s;
+            }
+        }
+        return latest;
+    }
+    /** Most recent session that is actively planning, executing, or asking, if any. */
+    latestActiveSession() {
+        let latest;
+        let latestAt = 0;
+        for (const s of this.sessions.values()) {
+            if ((s.status === "planning" || s.status === "executing") &&
+                s.updatedAt > latestAt) {
+                latest = { id: s.id, status: s.status };
+                latestAt = s.updatedAt;
+            }
+        }
+        for (const s of this.askSessions.values()) {
+            if (s.status === "asking" && s.updatedAt > latestAt) {
+                latest = { id: s.id, status: s.status };
+                latestAt = s.updatedAt;
+            }
+        }
+        return latest;
+    }
+    /** Ask sessions that are still running (newest first). */
+    listActiveAsks() {
+        return [...this.askSessions.values()]
+            .filter((s) => s.status === "asking")
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    /** All sessions waiting for YES/NO approval (newest first). */
+    listAwaitingApproval() {
+        return [...this.sessions.values()]
+            .filter((s) => s.status === "awaiting_approval")
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    /** Plan a new task (read-only). Returns the session with plan or error set. */
+    async plan(task, onSession, attachments) {
+        const session = {
+            id: `C-${this.nextId++}`,
+            task,
+            status: "planning",
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+        this.sessions.set(session.id, session);
+        onSession?.(session);
+        try {
+            const result = await runAgentPrompt(PLAN_PROMPT(task), this.opts, attachments);
+            if (result.status === "error") {
+                session.status = "error";
+                session.error = coerceText(result.result) || "plan run failed";
+            }
+            else {
+                session.status = "awaiting_approval";
+                session.plan = coerceText(result.result).trim() || "(no plan text returned)";
+            }
+        }
+        catch (err) {
+            session.status = "error";
+            session.error = isStartupError(err)
+                ? `agent did not start: ${err.message}`
+                : String(err);
+        }
+        session.updatedAt = Date.now();
+        return session;
+    }
+    /** Answer a question directly (read-only, no approval step). */
+    async ask(question, onSession, attachments) {
+        const session = {
+            id: `A-${this.nextAskId++}`,
+            question,
+            status: "asking",
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+        this.askSessions.set(session.id, session);
+        onSession?.(session);
+        try {
+            const result = await runAgentPrompt(ASK_PROMPT(question), this.opts, attachments);
+            if (result.status === "error") {
+                session.status = "error";
+                session.error = coerceText(result.result) || "ask run failed";
+            }
+            else {
+                session.status = "done";
+                session.answer = coerceText(result.result).trim() || "(no answer text returned)";
+            }
+        }
+        catch (err) {
+            session.status = "error";
+            session.error = isStartupError(err)
+                ? `agent did not start: ${err.message}`
+                : String(err);
+        }
+        session.updatedAt = Date.now();
+        return session;
+    }
+    /** Execute a previously planned session. Returns it with result or error. */
+    async approve(id, onExecuting) {
+        const session = this.sessions.get(id);
+        if (!session)
+            throw new Error(`unknown command session ${id}`);
+        if (session.status !== "awaiting_approval")
+            return session;
+        session.status = "executing";
+        session.updatedAt = Date.now();
+        onExecuting?.(session);
+        try {
+            const result = await runAgentPrompt(EXECUTE_PROMPT(session.task, session.plan ?? ""), this.opts);
+            if (result.status === "error") {
+                session.status = "error";
+                session.error = coerceText(result.result) || "execution run failed";
+            }
+            else {
+                session.status = "done";
+                session.result = coerceText(result.result).trim() || "(no result text returned)";
+            }
+        }
+        catch (err) {
+            session.status = "error";
+            session.error = isStartupError(err)
+                ? `agent did not start: ${err.message}`
+                : String(err);
+        }
+        session.updatedAt = Date.now();
+        return session;
+    }
+    /** Cancel a session awaiting approval. */
+    reject(id) {
+        const session = this.sessions.get(id);
+        if (session && session.status === "awaiting_approval") {
+            session.status = "cancelled";
+            session.updatedAt = Date.now();
+        }
+        return session;
+    }
+    /** Drop sessions older than maxAgeMs that aren't actively running. */
+    sweepStale(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        for (const [id, s] of this.sessions) {
+            const idle = s.status !== "planning" && s.status !== "executing";
+            if (idle && s.updatedAt < cutoff)
+                this.sessions.delete(id);
+        }
+        for (const [id, s] of this.askSessions) {
+            if (s.status !== "asking" && s.updatedAt < cutoff)
+                this.askSessions.delete(id);
+        }
+    }
+}
+/** Build a CommandRunner (always returns one; check `.enabled`). */
+export function createCommandRunner(opts) {
+    return new CommandRunner(opts);
+}

package/dist/answerWaiters.js

@@ -0,0 +1,64 @@
+/**
+ * Wake-on-answer registry for long-polling GET /response/:id.
+ *
+ * When a client blocks on a pending question, register a waiter keyed by
+ * question id. notifyAnswered() resolves all waiters immediately when the
+ * human's Telegram reply is recorded.
+ */
+const waiters = new Map();
+/** Resolve every blocked waiter for this question id (called after matchAndAnswer). */
+export function notifyAnswered(id) {
+    const set = waiters.get(id);
+    if (!set)
+        return;
+    for (const w of set) {
+        clearTimeout(w.timer);
+        w.resolve();
+    }
+    waiters.delete(id);
+}
+/**
+ * Block until notifyAnswered(id) or maxMs elapses.
+ * Returns { promise, cancel } — call cancel on client disconnect to avoid leaks.
+ */
+export function waitForAnswer(id, maxMs) {
+    let settled = false;
+    let waiter;
+    let resolvePromise;
+    const remove = () => {
+        if (!waiter)
+            return;
+        const set = waiters.get(id);
+        if (set) {
+            set.delete(waiter);
+            if (set.size === 0)
+                waiters.delete(id);
+        }
+    };
+    const finish = () => {
+        if (settled)
+            return;
+        settled = true;
+        if (waiter)
+            clearTimeout(waiter.timer);
+        remove();
+        resolvePromise?.();
+    };
+    const promise = new Promise((resolve) => {
+        resolvePromise = resolve;
+        const timer = setTimeout(() => finish(), maxMs);
+        timer.unref?.();
+        waiter = {
+            timer,
+            resolve: finish,
+        };
+        let set = waiters.get(id);
+        if (!set) {
+            set = new Set();
+            waiters.set(id, set);
+        }
+        set.add(waiter);
+    });
+    const cancel = () => finish();
+    return { promise, cancel };
+}