cursor-telegram-mcp 0.5.0 → 0.7.0

package/README.md

@@ -15,7 +15,8 @@ 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.
+eSIM, no SIM. Pending questions are persisted to disk, so a worker restart
+restores any still-open questions instead of dropping them.
 
 ## Add to Cursor (one click)
 
@@ -31,21 +32,40 @@ Prefer it under "Plugin MCP Servers" / the Cursor marketplace? See
 
 ## Quick start
 
-### 1. Configure your bot (one time)
+The goal: your bot is online whenever your computer is on — no need to open
+Cursor or start anything by hand.
+
+### 1. Install (one time)
+
+```bash
+npm i -g cursor-telegram-mcp
+```
+
+A global install gives the always-on service a stable location. (You can also
+run everything via `npx cursor-telegram-mcp …`, but the always-on installer
+needs a global install so its launch agent doesn't point at a temporary cache.)
+
+### 2. Configure + go always-on
 
 ```bash
-npx cursor-telegram-mcp setup
+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
+The wizard creates a bot with [@BotFather](https://t.me/BotFather), validates
+the token, captures your chat id (you message the bot once), optionally enables
+command mode with a Cursor API key, and then offers to install the **always-on
+service** (macOS launchd: starts at login, restarts itself, plus a watchdog).
+Config is saved to `~/.config/cursor-telegram/config.json` (or
 `%APPDATA%\cursor-telegram\config.json` on Windows).
 
-### 2. Add it to Cursor
+That's it — text your bot to test it. Run `cursor-telegram-mcp doctor` anytime
+to check status, and `cursor-telegram-mcp install` / `uninstall` to toggle the
+always-on service.
 
-Add this to your project's `.cursor/mcp.json` (or Cursor Settings -> Tools & MCP):
+### 3. (optional) Let Cursor agents message you
+
+Add this to a project's `.cursor/mcp.json` (or Cursor Settings -> Tools & MCP),
+then reload MCP:
 
 ```json
 {
@@ -58,8 +78,8 @@ Add this to your project's `.cursor/mcp.json` (or Cursor Settings -> Tools & 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.
+The bot itself runs from the always-on service regardless of Cursor; this step
+just lets in-IDE agents send you notifications and questions.
 
 ## Architecture
 
@@ -71,7 +91,7 @@ flowchart TD
   check -->|yes| reuse["reuse running worker"]
   spawn --> worker["worker dist/worker.js"]
   reuse --> worker
-  worker --> store["in-memory question store"]
+  worker --> store["persisted question store (questions.json)"]
   worker -->|"command mode (optional)"| agent["headless Cursor agent (cursor-agent CLI)"]
   worker -->|"Bot API: sendMessage / getUpdates"| tg["Telegram"]
   tg -->|"your reply / texted task"| worker
@@ -120,15 +140,37 @@ worker treats any message that is not answering an open question as a task:
    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:
+send `status` to see what's running, and `/reset` (or `/new`) to start a fresh
+conversation. 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.
+approve the plan.
+
+## Rolling chat (knowledge carries across messages)
+
+By default (`TG_ROLLING=true`) command mode keeps ONE long-lived Cursor agent
+and sends every turn — plan, execute, and `/ask` — to it. That means:
+
+- The executor remembers the plan it just made, and the next prompt remembers
+  the whole conversation, so you can keep building from your phone without
+  re-explaining context.
+- The agent id is persisted to `TG_SESSION_PATH` (default
+  `<configDir>/rolling-session.json`), so the thread survives worker restarts
+  (including the self-update restart) and resumes where you left off.
+- Send `/reset` (or `/new`) to drop the memory and start a fresh thread.
+
+Set `TG_ROLLING=false` to go back to a stateless agent per message.
+
+### See the same chat on your computer
+
+Every turn is also appended to a Markdown transcript at `TG_TRANSCRIPT_PATH`
+(default `<TG_AGENT_CWD>/remote-chat.md`). Open it in Cursor (or any editor) to
+read the same conversation you are driving from your phone. Because it lives in
+the repo, git tracks its history — commit it whenever you want a snapshot.
 
 ## Keeping the worker alive
 
@@ -136,11 +178,39 @@ 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.)
+If you want it to survive reboots without opening Cursor, install it as an
+always-on background service. On macOS this is one command:
+
+```bash
+cursor-telegram-mcp install     # start now + at every login (launchd)
+cursor-telegram-mcp uninstall   # stop and remove it
+```
+
+`install` writes a per-user launch agent
+(`~/Library/LaunchAgents/com.cursor-telegram.worker.plist`) that points at your
+current Node and the installed CLI — no hardcoded paths — runs the worker under
+`caffeinate` so idle sleep never blocks delivery, and restarts it if it crashes
+(`KeepAlive`). Logs go to `~/Library/Logs/cursor-telegram-worker.log`. Keep the
+Mac on AC power so a closed lid does not fully sleep.
+
+`install` also sets up a **watchdog** (`com.cursor-telegram.watchdog`, every
+120s) that checks the worker's `/health` and restarts it if it is unreachable
+or its poll loop has wedged. Combined with the worker's own retry/backoff (every
+Bot API call has a hard abort timeout, so a stale socket after sleep/wake can't
+silently hang it), the bot stays online as long as the Mac is on.
+
+To stay online the Mac must not fully sleep. The worker runs under `caffeinate`
+so idle sleep is prevented while it's up, but a closed lid on battery still
+sleeps. For a machine you want always-on:
+
+- Keep it on **AC power**.
+- Optionally allow it to run with the lid closed on AC:
+  `sudo pmset -c sleep 0 disablesleep 1` (revert with `sudo pmset -c disablesleep 0`).
+
+On Linux/Windows, run `cursor-telegram-mcp worker` under your own service
+manager (systemd / Task Scheduler). (Note: on macOS, launchd agents cannot read
+files under `~/Desktop`/`~/Documents`/`~/Downloads`; install the package or
+project outside those folders.)
 
 ## Configuration
 
@@ -162,6 +232,9 @@ defaults.
 | `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. |
+| `TG_ROLLING` | `true` | Keep one rolling agent thread so knowledge carries across messages. |
+| `TG_TRANSCRIPT_PATH` | `<cwd>/remote-chat.md` | Markdown transcript of the rolling chat. |
+| `TG_SESSION_PATH` | `<configDir>/rolling-session.json` | Where the rolling agent id is persisted. |
 
 ## CLI
 
@@ -170,6 +243,9 @@ 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 install  Install the always-on worker + watchdog (macOS launchd)
+cursor-telegram-mcp uninstall Remove the always-on worker + watchdog
+cursor-telegram-mcp watchdog One-shot health check; restarts the worker if down
 cursor-telegram-mcp doctor   Diagnose configuration and connectivity
 ```
 
@@ -243,8 +319,8 @@ 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).
+  it is back. Open questions are persisted to disk and restored on the next
+  worker start, so a restart no longer drops unanswered questions.
 - 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
@@ -262,8 +338,12 @@ src/
   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
+  agentRunner.ts# command mode: rolling/resumable headless Cursor agent (lazy @cursor/sdk)
+  session.ts    # persist the rolling agent id across worker restarts
+  transcript.ts # append-only remote-chat.md transcript of the rolling chat
+  store.ts      # pending-question store (persisted to disk) + reply matching
+  install.ts    # `install`/`uninstall`: generate per-user launchd worker + watchdog (macOS)
+  watchdog.ts   # `watchdog`: one-shot /health check that restarts a wedged worker
   parseInbound.ts / splitMessage.ts / taskQueue.ts / formatTelegram.ts
   answerWaiters.ts  # wake-on-answer for long-polling GET /response/:id
 .cursor/

package/dist/agentRunner.js

@@ -55,15 +55,23 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * 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.
+ *   2. `plan()` 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()` executes the approved plan and reports the
+ *      result. Reply NO -> `reject()` drops it.
+ *
+ * Rolling thread: by default the runner keeps ONE long-lived Cursor agent and
+ * sends every turn (plan, execute, ask) to it, so knowledge carries across
+ * messages — the executor remembers the plan, and the next prompt remembers the
+ * whole conversation. The agent id is persisted (see session.ts) so the thread
+ * survives worker restarts. Set `rolling: false` to fall back to a fresh agent
+ * per call (the old stateless behavior).
  *
  * Everything runs locally on this machine (the laptop on the charger) against
- * `cwd`, using your CURSOR_API_KEY. Sessions live in memory only.
+ * `cwd`, using your CURSOR_API_KEY.
  */
 import { readFileSync } from "node:fs";
+import { clearRollingSession, loadRollingSession, saveRollingSession, } from "./session.js";
 /**
  * Lazily load the optional `@cursor/sdk`. Command mode needs it; if the package
  * is not installed (it is an optionalDependency), surface a clear, actionable
@@ -100,7 +108,8 @@ function buildUserMessage(text, attachments) {
         return text;
     return { text, images };
 }
-async function runAgentPrompt(promptText, opts, attachments) {
+/** Run a single prompt on a fresh, stateless agent (rolling disabled). */
+async function runStatelessPrompt(promptText, opts, attachments) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
         const message = buildUserMessage(promptText, attachments);
@@ -163,13 +172,114 @@ export class CommandRunner {
     nextAskId = 1;
     sessions = new Map();
     askSessions = new Map();
+    /** Live rolling agent instance (kept across turns; created lazily). */
+    agent;
+    /** Persisted rolling agent id (may exist before `agent` is reattached). */
+    rollingAgentId;
+    /** Epoch ms the current rolling thread started. */
+    threadStartedAt;
+    /** Serializes turns so two phone messages never share one agent send. */
+    turnChain = Promise.resolve();
     constructor(opts) {
         this.opts = opts;
+        if (opts.rolling) {
+            const saved = loadRollingSession(opts.sessionPath);
+            // Only reuse a saved thread if it matches the current cwd (a different
+            // project should get its own conversation).
+            if (saved && saved.cwd === opts.cwd) {
+                this.rollingAgentId = saved.agentId;
+                this.threadStartedAt = saved.startedAt;
+            }
+        }
     }
     /** True when a Cursor API key is configured. */
     get enabled() {
         return this.opts.apiKey.trim() !== "";
     }
+    /** Info about the active rolling thread, if rolling is on and started. */
+    rollingInfo() {
+        if (!this.opts.rolling)
+            return undefined;
+        if (!this.rollingAgentId)
+            return undefined;
+        return { agentId: this.rollingAgentId, startedAt: this.threadStartedAt ?? 0 };
+    }
+    /**
+     * Get the rolling agent, creating it (first ever turn) or resuming a saved
+     * thread (after a worker restart). Reuses the live instance otherwise.
+     */
+    async getRollingAgent() {
+        if (this.agent)
+            return this.agent;
+        const { Agent } = await loadSdk();
+        const local = { cwd: this.opts.cwd, settingSources: this.opts.settingSources };
+        if (this.rollingAgentId) {
+            try {
+                this.agent = await Agent.resume(this.rollingAgentId, {
+                    apiKey: this.opts.apiKey,
+                    model: { id: this.opts.model },
+                    local,
+                });
+                return this.agent;
+            }
+            catch {
+                // The saved thread could not be resumed (e.g. pruned); start fresh.
+                this.rollingAgentId = undefined;
+                this.threadStartedAt = undefined;
+                clearRollingSession(this.opts.sessionPath);
+            }
+        }
+        this.agent = await Agent.create({
+            apiKey: this.opts.apiKey,
+            model: { id: this.opts.model },
+            local,
+        });
+        this.rollingAgentId = this.agent.agentId;
+        this.threadStartedAt = Date.now();
+        saveRollingSession(this.opts.sessionPath, {
+            agentId: this.rollingAgentId,
+            model: this.opts.model,
+            cwd: this.opts.cwd,
+            startedAt: this.threadStartedAt,
+        });
+        return this.agent;
+    }
+    /**
+     * Run one prompt. In rolling mode this reuses the persistent agent (so the
+     * turn remembers all prior turns); otherwise it uses a fresh stateless agent.
+     * Turns are serialized to keep the single agent consistent.
+     */
+    async runTurn(promptText, attachments) {
+        if (!this.opts.rolling) {
+            return runStatelessPrompt(promptText, this.opts, attachments);
+        }
+        const run = this.turnChain.then(async () => {
+            const message = buildUserMessage(promptText, attachments);
+            const agent = await this.getRollingAgent();
+            const r = await agent.send(message);
+            await r.wait();
+            return { status: r.status, result: r.result };
+        });
+        // Keep the chain alive even if this turn rejects, without swallowing the
+        // error for the caller.
+        this.turnChain = run.catch(() => undefined);
+        return run;
+    }
+    /** Start a fresh rolling thread (drops memory of the current conversation). */
+    reset() {
+        if (this.agent) {
+            try {
+                this.agent.close();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        this.agent = undefined;
+        this.rollingAgentId = undefined;
+        this.threadStartedAt = undefined;
+        clearRollingSession(this.opts.sessionPath);
+    }
     /** Most recent session waiting for a YES/NO approval, if any. */
     latestAwaitingApproval() {
         let latest;
@@ -223,7 +333,7 @@ export class CommandRunner {
         this.sessions.set(session.id, session);
         onSession?.(session);
         try {
-            const result = await runAgentPrompt(PLAN_PROMPT(task), this.opts, attachments);
+            const result = await this.runTurn(PLAN_PROMPT(task), attachments);
             if (result.status === "error") {
                 session.status = "error";
                 session.error = coerceText(result.result) || "plan run failed";
@@ -254,7 +364,7 @@ export class CommandRunner {
         this.askSessions.set(session.id, session);
         onSession?.(session);
         try {
-            const result = await runAgentPrompt(ASK_PROMPT(question), this.opts, attachments);
+            const result = await this.runTurn(ASK_PROMPT(question), attachments);
             if (result.status === "error") {
                 session.status = "error";
                 session.error = coerceText(result.result) || "ask run failed";
@@ -284,7 +394,7 @@ export class CommandRunner {
         session.updatedAt = Date.now();
         onExecuting?.(session);
         try {
-            const result = await runAgentPrompt(EXECUTE_PROMPT(session.task, session.plan ?? ""), this.opts);
+            const result = await this.runTurn(EXECUTE_PROMPT(session.task, session.plan ?? ""));
             if (result.status === "error") {
                 session.status = "error";
                 session.error = coerceText(result.result) || "execution run failed";

package/dist/cli.js

@@ -7,6 +7,8 @@
  *   cursor-telegram-mcp setup      Interactive first-time setup (bot + chat id).
  *   cursor-telegram-mcp login      Find your chat id (token must be set).
  *   cursor-telegram-mcp worker     Run the background worker in the foreground.
+ *   cursor-telegram-mcp install    Install the always-on worker (macOS launchd).
+ *   cursor-telegram-mcp uninstall  Remove the always-on worker.
  *   cursor-telegram-mcp doctor     Diagnose configuration / connectivity.
  *
  * Each subcommand is a module whose side-effecting `main()` runs on import.
@@ -20,6 +22,8 @@ function printHelp() {
         "  cursor-telegram-mcp setup    First-time setup: create/link your bot",
         "  cursor-telegram-mcp login    Print your Telegram chat id",
         "  cursor-telegram-mcp worker   Run the background worker in the foreground",
+        "  cursor-telegram-mcp install  Install the always-on worker (macOS launchd)",
+        "  cursor-telegram-mcp uninstall Remove the always-on worker",
         "  cursor-telegram-mcp doctor   Diagnose configuration and connectivity",
         "  cursor-telegram-mcp help     Show this help",
         "",
@@ -39,6 +43,13 @@ async function run() {
         case "worker":
             await import("./worker.js");
             break;
+        case "install":
+        case "uninstall":
+            await import("./install.js");
+            break;
+        case "watchdog":
+            await import("./watchdog.js");
+            break;
         case "setup":
             await import("./setup.js");
             break;

package/dist/config.js

@@ -15,11 +15,21 @@
  * MCP client needs:
  *   TG_WORKER_URL - where the worker listens (default http://127.0.0.1:8787).
  *   TG_PROJECT    - label for this project's messages (default "default").
+ *   TG_AGENT      - optional default per-agent/chat label, shown as
+ *                   [project · agent]. Overridden by the `agent` tool param.
  *   TG_DEFAULT_POLL_WAIT_MS - long-poll chunk size check_human_response uses
  *                             when no explicit waitMs is passed (default 120000).
+ *   TG_STARTUP_PING - set to 0/false to silence the "worker online" message the
+ *                     worker sends after it connects (default on).
  *
  * Command mode (optional, worker-side) needs:
  *   CURSOR_API_KEY - enables texting tasks to the bot to run headless agents.
+ *   TG_COMMAND_MODE - set to 0/false to hard-disable command mode even when a
+ *                     CURSOR_API_KEY is present (inbound text won't spawn tasks).
+ *   TG_SELF_UPDATE  - set to 0/false so the worker never auto-restarts itself when
+ *                     its own source changes (prevents wiping in-flight state).
+ *   TG_AGENT_CWD    - point command-mode agents at a SEPARATE repo so their edits
+ *                     never touch the worker's own source (avoids self-restarts).
  *   TG_AGENT_CWD   - directory the headless agent works in (default cwd).
  *   TG_AGENT_MODEL - model id for the headless agent (default composer-2.5).
  *   TG_AGENT_LOAD_SETTINGS - "1"/"true" to load this repo's .cursor settings.
@@ -141,6 +151,7 @@ export function getConfig(requireToken = true) {
     }
     const workerHost = strOr("TG_WORKER_HOST", "127.0.0.1");
     const workerPort = intOr("TG_WORKER_PORT", 8787);
+    const agentCwd = strOr("TG_AGENT_CWD", process.cwd());
     cached = {
         botToken,
         chatId: strOr("TELEGRAM_CHAT_ID", ""),
@@ -150,11 +161,18 @@ export function getConfig(requireToken = true) {
         workerPort,
         workerUrl: strOr("TG_WORKER_URL", `http://${workerHost}:${workerPort}`).replace(/\/+$/, ""),
         project: strOr("TG_PROJECT", "default"),
+        agentLabel: strOr("TG_AGENT", ""),
         defaultPollWaitMs: intOr("TG_DEFAULT_POLL_WAIT_MS", 120_000),
+        startupPing: boolOr("TG_STARTUP_PING", true),
         cursorApiKey: strOr("CURSOR_API_KEY", ""),
-        agentCwd: strOr("TG_AGENT_CWD", process.cwd()),
+        commandModeEnabled: boolOr("TG_COMMAND_MODE", true),
+        selfUpdateEnabled: boolOr("TG_SELF_UPDATE", true),
+        agentCwd,
         agentModel: strOr("TG_AGENT_MODEL", "composer-2.5"),
         agentLoadSettings: boolOr("TG_AGENT_LOAD_SETTINGS", false),
+        rolling: boolOr("TG_ROLLING", true),
+        transcriptPath: strOr("TG_TRANSCRIPT_PATH", join(agentCwd, "remote-chat.md")),
+        sessionPath: strOr("TG_SESSION_PATH", join(configDir(), "rolling-session.json")),
     };
     return cached;
 }

package/dist/formatTelegram.js

@@ -1,3 +1,11 @@
+/**
+ * Bracketed prefix for outgoing messages: "[project]" or "[project · agent]"
+ * when a per-agent/chat label is present. Lets the human tell which agent a
+ * question/notification came from when several chats are active.
+ */
+export function labelPrefix(project, agent) {
+    return agent && agent !== "" ? `[${project} · ${agent}]` : `[${project}]`;
+}
 /**
  * Convert agent Markdown to plain text suitable for Telegram (no parse_mode).
  */

package/dist/index.js

@@ -173,9 +173,18 @@ async function main() {
                 .string()
                 .min(1)
                 .describe("Short summary of the completed work (what changed / result)."),
+            agent: z
+                .string()
+                .optional()
+                .describe("Optional short label for THIS chat/agent (e.g. \"auth-refactor\"), shown " +
+                "as [project · agent] so multiple agents are distinguishable."),
         },
-    }, async ({ summary }) => {
-        const r = await callWorker("POST", "/notify", { summary, project: config.project });
+    }, async ({ summary, agent }) => {
+        const r = await callWorker("POST", "/notify", {
+            summary,
+            project: config.project,
+            agent: (agent ?? "").trim() || config.agentLabel,
+        });
         if (!r)
             return textResult(WORKER_DOWN, true);
         if (r.status === 200)
@@ -203,9 +212,19 @@ async function main() {
                 .min(1)
                 .describe("The exact question to ask the human. Be specific and include the " +
                 "options/context needed to answer from a phone."),
+            agent: z
+                .string()
+                .optional()
+                .describe("Optional short label for THIS chat/agent (e.g. \"auth-refactor\"), shown " +
+                "as [project · agent] Q-n so the human can tell which agent is asking " +
+                "and route their reply. Keep it stable across the chat."),
         },
-    }, async ({ question }) => {
-        const r = await callWorker("POST", "/ask", { question, project: config.project });
+    }, async ({ question, agent }) => {
+        const r = await callWorker("POST", "/ask", {
+            question,
+            project: config.project,
+            agent: (agent ?? "").trim() || config.agentLabel,
+        });
         if (!r)
             return textResult(WORKER_DOWN, true);
         if (r.status === 200) {
@@ -237,6 +256,12 @@ async function main() {
                 .min(1)
                 .describe("The exact question to ask the human. Be specific and include the " +
                 "options/context needed to answer from a phone."),
+            agent: z
+                .string()
+                .optional()
+                .describe("Optional short label for THIS chat/agent (e.g. \"auth-refactor\"), shown " +
+                "as [project · agent] Q-n so the human can tell which agent is asking " +
+                "and route their reply. Keep it stable across the chat."),
             timeoutMin: z
                 .number()
                 .int()
@@ -245,9 +270,13 @@ async function main() {
                 .describe("Maximum minutes to wait for a reply (default: TG_RESPONSE_TIMEOUT_MIN, " +
                 "usually 30). Returns timed_out if no reply within this window."),
         },
-    }, async ({ question, timeoutMin }) => {
+    }, async ({ question, agent, timeoutMin }) => {
         const maxWaitMin = timeoutMin ?? config.responseTimeoutMin;
-        const askRes = await callWorker("POST", "/ask", { question, project: config.project });
+        const askRes = await callWorker("POST", "/ask", {
+            question,
+            project: config.project,
+            agent: (agent ?? "").trim() || config.agentLabel,
+        });
         if (!askRes)
             return textResult(WORKER_DOWN, true);
         if (askRes.status === 503) {