telegram-notify-mcp 1.0.0 → 2.0.0

package/dist/index.js

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
 /**
  * telegram-notify-mcp — stdio MCP server for Telegram Bot API notifications.
- * Env: TELEGRAM_BOT_TOKEN (required for tool calls), TELEGRAM_CHAT_ID (optional default).
+ * Env: TELEGRAM_BOT_TOKEN (required for tool calls), TELEGRAM_CHAT_ID (optional default),
+ * TELEGRAM_CHAT_ALLOWLIST (optional inbound), TELEGRAM_NOTIFY_DATA_DIR (optional store path).
  * Starts cleanly without a token; tools fail with a clear error when invoked.
  * Public release is env-only — no disk/secret-store token loading.
+ * Phase 2: outbound mapping + inbound pending queue (host must poll + SendToAgent + ack).
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { TelegramApiError, TelegramClient, formatNotifyMessage, getDefaultChatId, } from './telegram.js';
+import { LocalStore } from './store.js';
+import { formatAgentFooter, formatNotifyWithFooter, processUpdates, } from './routing.js';
 const SERVER_NAME = 'telegram-notify-mcp';
-const SERVER_VERSION = '1.0.0';
+const SERVER_VERSION = '2.0.0';
 function textResult(text, isError = false) {
     return {
         content: [{ type: 'text', text }],
@@ -27,6 +31,9 @@ function errorResult(err) {
 function getClient() {
     return new TelegramClient(process.env.TELEGRAM_BOT_TOKEN);
 }
+function getStore() {
+    return new LocalStore();
+}
 function createServer() {
     const server = new McpServer({
         name: SERVER_NAME,
@@ -46,7 +53,7 @@ function createServer() {
             return errorResult(err);
         }
     });
-    server.tool('telegram_send_message', 'Send a text message via the Bot API. chat_id is optional when TELEGRAM_CHAT_ID is set.', {
+    server.tool('telegram_send_message', 'Send a text message via the Bot API. chat_id is optional when TELEGRAM_CHAT_ID is set. Optional source_agent_id appends footer and persists reply mapping.', {
         text: z.string().min(1).describe('Message text to send'),
         chat_id: z
             .union([z.string(), z.number()])
@@ -56,52 +63,94 @@ function createServer() {
             .enum(['Markdown', 'MarkdownV2', 'HTML'])
             .optional()
             .describe('Optional Telegram parse_mode'),
-    }, async ({ text, chat_id, parse_mode }) => {
+        source_agent_id: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Originating agent id — when set, append footer and store mapping for replies'),
+        source_agent_name: z
+            .string()
+            .optional()
+            .describe('Optional display name for footer'),
+    }, async ({ text, chat_id, parse_mode, source_agent_id, source_agent_name }) => {
         try {
             const chatId = getDefaultChatId(chat_id);
+            let outbound = text;
+            if (source_agent_id) {
+                outbound = text + formatAgentFooter(source_agent_id, source_agent_name);
+            }
             const msg = await getClient().sendMessage({
                 chat_id: chatId,
-                text,
+                text: outbound,
                 parse_mode,
             });
+            let mapped = false;
+            if (source_agent_id) {
+                getStore().putMapping({
+                    chat_id: String(msg.chat.id),
+                    telegram_message_id: msg.message_id,
+                    source_agent_id,
+                    source_agent_name: source_agent_name || undefined,
+                });
+                mapped = true;
+            }
             return textResult(JSON.stringify({
                 ok: true,
                 message_id: msg.message_id,
                 chat_id: msg.chat.id,
-                text: msg.text ?? text,
+                text: msg.text ?? outbound,
+                mapped,
+                source_agent_id: source_agent_id ?? null,
             }, null, 2));
         }
         catch (err) {
             return errorResult(err);
         }
     });
-    server.tool('telegram_notify', 'Send a short completion-style notification (title + body) to the default or explicit chat.', {
+    server.tool('telegram_notify', 'Send a short completion-style notification (title + body) with required source_agent_id. Appends agent footer and persists message→agent mapping for reply routing.', {
         body: z.string().min(1).describe('Notification body / details'),
         title: z.string().optional().describe('Optional short title (e.g. "Build finished")'),
         chat_id: z
             .union([z.string(), z.number()])
             .optional()
             .describe('Telegram chat id (falls back to TELEGRAM_CHAT_ID)'),
-    }, async ({ body, title, chat_id }) => {
+        source_agent_id: z
+            .string()
+            .min(1)
+            .describe('Required stable id of the originating agent (for reply routing)'),
+        source_agent_name: z
+            .string()
+            .optional()
+            .describe('Optional short human label for the footer'),
+    }, async ({ body, title, chat_id, source_agent_id, source_agent_name }) => {
         try {
             const chatId = getDefaultChatId(chat_id);
-            const text = formatNotifyMessage(title, body);
+            const text = formatNotifyWithFooter(title, body, source_agent_id, source_agent_name, formatNotifyMessage);
             const msg = await getClient().sendMessage({
                 chat_id: chatId,
                 text,
             });
+            getStore().putMapping({
+                chat_id: String(msg.chat.id),
+                telegram_message_id: msg.message_id,
+                source_agent_id,
+                source_agent_name: source_agent_name || undefined,
+            });
             return textResult(JSON.stringify({
                 ok: true,
                 message_id: msg.message_id,
                 chat_id: msg.chat.id,
                 text,
+                mapped: true,
+                source_agent_id,
+                source_agent_name: source_agent_name ?? null,
             }, null, 2));
         }
         catch (err) {
             return errorResult(err);
         }
     });
-    server.tool('telegram_get_updates', 'Fetch recent bot updates so you can discover chat_id after messaging the bot with /start.', {
+    server.tool('telegram_get_updates', 'Fetch recent bot updates so you can discover chat_id after messaging the bot with /start. Does not enqueue pending commands (use telegram_poll_inbound for that).', {
         limit: z
             .number()
             .int()
@@ -142,6 +191,87 @@ function createServer() {
             return errorResult(err);
         }
     });
+    server.tool('telegram_poll_inbound', 'Poll Telegram getUpdates, allowlist-filter, route replies/mappings and /to commands into the pending queue. Unroutable allowlisted messages are ignored (counted). Host must then list + SendToAgent + ack.', {
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe('Max updates to fetch (default 50)'),
+        timeout: z
+            .number()
+            .int()
+            .min(0)
+            .max(50)
+            .optional()
+            .describe('Long-poll timeout seconds (default 0)'),
+    }, async ({ limit, timeout }) => {
+        try {
+            const store = getStore();
+            const offset = store.getUpdateOffset();
+            const updates = await getClient().getUpdates({
+                limit: limit ?? 50,
+                timeout: timeout ?? 0,
+                offset,
+            });
+            const summary = processUpdates(store, updates);
+            if (summary.next_offset !== undefined) {
+                store.setUpdateOffset(summary.next_offset);
+            }
+            return textResult(JSON.stringify({
+                ok: true,
+                ...summary,
+                note: 'Unroutable messages (no reply-to mapping and no /to <agent_id> …) are ignored. Host should call telegram_list_pending_commands, deliver via SendToAgent, then telegram_ack_command.',
+            }, null, 2));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool('telegram_list_pending_commands', 'List pending inbound commands (status=pending). Optional filter by source_agent_id. Host delivers each then calls telegram_ack_command.', {
+        source_agent_id: z
+            .string()
+            .optional()
+            .describe('If set, only list commands for this agent'),
+    }, async ({ source_agent_id }) => {
+        try {
+            const store = getStore();
+            const commands = store.listPending(source_agent_id ? { source_agent_id } : undefined);
+            return textResult(JSON.stringify({
+                ok: true,
+                count: commands.length,
+                commands,
+            }, null, 2));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool('telegram_ack_command', 'Acknowledge (delete) a pending command by id after the host has delivered it to the target agent. Idempotent: unknown id returns ok=false.', {
+        command_id: z.string().min(1).describe('Pending command id from list/poll'),
+    }, async ({ command_id }) => {
+        try {
+            const store = getStore();
+            const cmd = store.ackCommand(command_id);
+            if (!cmd) {
+                return textResult(JSON.stringify({
+                    ok: false,
+                    error: 'unknown_command_id',
+                    command_id,
+                }), true);
+            }
+            return textResult(JSON.stringify({
+                ok: true,
+                acked: true,
+                command_id: cmd.id,
+                source_agent_id: cmd.source_agent_id,
+            }), false);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
     return server;
 }
 async function main() {
@@ -149,7 +279,9 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio` +
-        (process.env.TELEGRAM_BOT_TOKEN ? '' : ' (TELEGRAM_BOT_TOKEN not set — tools will error until configured)'));
+        (process.env.TELEGRAM_BOT_TOKEN
+            ? ''
+            : ' (TELEGRAM_BOT_TOKEN not set — tools will error until configured)'));
 }
 main().catch((err) => {
     console.error('Fatal:', err);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,GAAG,qBAAqB,CAAC;AAC1C,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,SAAS,UAAU,CAAC,IAAY,EAAE,OAAO,GAAG,KAAK;IAC/C,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;QAC1C,OAAO;KACR,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;QACpC,OAAO,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,IAAI,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,YAAY;IACnB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,qGAAqG,EACrG,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC;YACrC,OAAO,UAAU,CACf,IAAI,CAAC,SAAS,CACZ;gBACE,EAAE,EAAE,EAAE,CAAC,EAAE;gBACT,QAAQ,EAAE,EAAE,CAAC,QAAQ,IAAI,IAAI;gBAC7B,UAAU,EAAE,EAAE,CAAC,UAAU;gBACzB,MAAM,EAAE,EAAE,CAAC,MAAM;aAClB,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,uBAAuB,EACvB,wFAAwF,EACxF;QACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC;QACxD,OAAO,EAAE,CAAC;aACP,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;aAC/B,QAAQ,EAAE;aACV,QAAQ,CAAC,mDAAmD,CAAC;QAChE,UAAU,EAAE,CAAC;aACV,IAAI,CAAC,CAAC,UAAU,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;aACxC,QAAQ,EAAE;aACV,QAAQ,CAAC,8BAA8B,CAAC;KAC5C,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE;QACtC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC,WAAW,CAAC;gBACxC,OAAO,EAAE,MAAM;gBACf,IAAI;gBACJ,UAAU;aACX,CAAC,CAAC;YACH,OAAO,UAAU,CACf,IAAI,CAAC,SAAS,CACZ;gBACE,EAAE,EAAE,IAAI;gBACR,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE;gBACpB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI;aACvB,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,4FAA4F,EAC5F;QACE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QAC/D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;QACrF,OAAO,EAAE,CAAC;aACP,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;aAC/B,QAAQ,EAAE;aACV,QAAQ,CAAC,mDAAmD,CAAC;KACjE,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE;QACjC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,IAAI,GAAG,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC9C,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC,WAAW,CAAC;gBACxC,OAAO,EAAE,MAAM;gBACf,IAAI;aACL,CAAC,CAAC;YACH,OAAO,UAAU,CACf,IAAI,CAAC,SAAS,CACZ;gBACE,EAAE,EAAE,IAAI;gBACR,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE;gBACpB,IAAI;aACL,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,sBAAsB,EACtB,2FAA2F,EAC3F;QACE,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,oCAAoC,CAAC;KAClD,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAClB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,SAAS,EAAE,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC;YACrE,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4D,CAAC;YAClF,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC,YAAY,CAAC;gBAC1D,IAAI,CAAC,CAAC,EAAE,IAAI;oBAAE,SAAS;gBACvB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACjB,MAAM,KAAK,GACT,CAAC,CAAC,KAAK;oBACP,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;oBACrD,CAAC,CAAC,QAAQ;oBACV,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACf,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAClE,CAAC;YACD,OAAO,UAAU,CACf,IAAI,CAAC,SAAS,CACZ;gBACE,YAAY,EAAE,OAAO,CAAC,MAAM;gBAC5B,gBAAgB,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;gBACrC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBACzB,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC,YAAY,CAAC;oBAC1D,OAAO;wBACL,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,IAAI;wBAC5B,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,IAAI,IAAI;wBACtD,IAAI,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI;qBACtB,CAAC;gBACJ,CAAC,CAAC;aACH,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CACX,GAAG,WAAW,KAAK,cAAc,mBAAmB;QAClD,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mEAAmE,CAAC,CAC9G,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/routing.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Inbound routing: allowlist, reply→mapping, /to <agent_id> fallback.
+ * Unroutable allowlisted messages are ignored (counted); never executed as shell.
+ */
+import type { PendingCommand, LocalStore } from './store.js';
+import type { TelegramMessage, TelegramUpdate } from './telegram.js';
+export interface AllowlistResult {
+    allowed: boolean;
+    chatId: string;
+}
+/**
+ * Allowed chats from TELEGRAM_CHAT_ALLOWLIST (comma-separated) or TELEGRAM_CHAT_ID.
+ * If neither is set, no chat is allowed for inbound commands.
+ */
+export declare function getAllowedChatIds(env?: NodeJS.ProcessEnv): Set<string>;
+export declare function isChatAllowed(chatId: string | number, env?: NodeJS.ProcessEnv): boolean;
+/** Parse `/to <agent_id> <rest…>` — agent_id is the first whitespace-delimited token after /to. */
+export declare function parseToAgentCommand(text: string): {
+    agentId: string;
+    body: string;
+} | undefined;
+export declare function truncateAgentLabel(idOrName: string, maxLen?: number): string;
+/**
+ * Footer appended to outbound notify text (UX only; routing uses reply_to mapping).
+ */
+export declare function formatAgentFooter(sourceAgentId: string, sourceAgentName?: string): string;
+export declare function formatNotifyWithFooter(title: string | undefined, body: string, sourceAgentId: string, sourceAgentName?: string, formatBase?: (title: string | undefined, body: string) => string): string;
+export type InboundDisposition = {
+    kind: 'enqueued';
+    command: PendingCommand;
+    via: 'reply' | 'to_command';
+} | {
+    kind: 'ignored_not_allowlisted';
+} | {
+    kind: 'ignored_unroutable';
+} | {
+    kind: 'ignored_no_text';
+};
+export declare function routeInboundMessage(store: LocalStore, message: TelegramMessage, env?: NodeJS.ProcessEnv): InboundDisposition;
+export interface PollSummary {
+    updates_seen: number;
+    enqueued: number;
+    ignored_not_allowlisted: number;
+    ignored_unroutable: number;
+    ignored_no_text: number;
+    commands: PendingCommand[];
+    next_offset?: number;
+}
+export declare function processUpdates(store: LocalStore, updates: TelegramUpdate[], env?: NodeJS.ProcessEnv): PollSummary;

package/dist/routing.js

@@ -0,0 +1,146 @@
+/**
+ * Inbound routing: allowlist, reply→mapping, /to <agent_id> fallback.
+ * Unroutable allowlisted messages are ignored (counted); never executed as shell.
+ */
+/**
+ * Allowed chats from TELEGRAM_CHAT_ALLOWLIST (comma-separated) or TELEGRAM_CHAT_ID.
+ * If neither is set, no chat is allowed for inbound commands.
+ */
+export function getAllowedChatIds(env = process.env) {
+    const allowlist = (env.TELEGRAM_CHAT_ALLOWLIST ?? '').trim();
+    const ids = new Set();
+    if (allowlist) {
+        for (const part of allowlist.split(',')) {
+            const id = part.trim();
+            if (id)
+                ids.add(id);
+        }
+    }
+    const single = (env.TELEGRAM_CHAT_ID ?? '').trim();
+    if (single)
+        ids.add(single);
+    return ids;
+}
+export function isChatAllowed(chatId, env = process.env) {
+    const allowed = getAllowedChatIds(env);
+    if (allowed.size === 0)
+        return false;
+    return allowed.has(String(chatId));
+}
+/** Parse `/to <agent_id> <rest…>` — agent_id is the first whitespace-delimited token after /to. */
+export function parseToAgentCommand(text) {
+    const trimmed = text.trim();
+    const match = trimmed.match(/^\/to\s+(\S+)\s+([\s\S]+)$/i);
+    if (!match)
+        return undefined;
+    const agentId = match[1];
+    const body = match[2].trim();
+    if (!agentId || !body)
+        return undefined;
+    return { agentId, body };
+}
+export function truncateAgentLabel(idOrName, maxLen = 32) {
+    const s = idOrName.trim();
+    if (s.length <= maxLen)
+        return s;
+    return `${s.slice(0, maxLen - 1)}…`;
+}
+/**
+ * Footer appended to outbound notify text (UX only; routing uses reply_to mapping).
+ */
+export function formatAgentFooter(sourceAgentId, sourceAgentName) {
+    const label = truncateAgentLabel((sourceAgentName ?? '').trim() || sourceAgentId);
+    return `\n\n— from agent ${label}\nReply to this message to continue with this agent.`;
+}
+export function formatNotifyWithFooter(title, body, sourceAgentId, sourceAgentName, formatBase = defaultFormatBase) {
+    return formatBase(title, body) + formatAgentFooter(sourceAgentId, sourceAgentName);
+}
+function defaultFormatBase(title, body) {
+    const t = (title ?? '').trim();
+    const b = body.trim();
+    if (t)
+        return `✅ ${t}\n\n${b}`;
+    return `✅ ${b}`;
+}
+export function routeInboundMessage(store, message, env = process.env) {
+    const chatId = message.chat?.id;
+    if (chatId === undefined || chatId === null) {
+        return { kind: 'ignored_unroutable' };
+    }
+    if (!isChatAllowed(chatId, env)) {
+        return { kind: 'ignored_not_allowlisted' };
+    }
+    const text = (message.text ?? '').trim();
+    if (!text) {
+        return { kind: 'ignored_no_text' };
+    }
+    const replyToId = message.reply_to_message?.message_id;
+    if (replyToId !== undefined) {
+        const mapping = store.getMapping(chatId, replyToId);
+        if (mapping) {
+            const command = store.enqueuePending({
+                source_agent_id: mapping.source_agent_id,
+                source_agent_name: mapping.source_agent_name,
+                conversation_hint: mapping.conversation_hint,
+                chat_id: String(chatId),
+                telegram_message_id: message.message_id,
+                reply_to_telegram_message_id: replyToId,
+                text,
+            });
+            return { kind: 'enqueued', command, via: 'reply' };
+        }
+    }
+    const toCmd = parseToAgentCommand(text);
+    if (toCmd) {
+        const command = store.enqueuePending({
+            source_agent_id: toCmd.agentId,
+            chat_id: String(chatId),
+            telegram_message_id: message.message_id,
+            reply_to_telegram_message_id: replyToId,
+            text: toCmd.body,
+        });
+        return { kind: 'enqueued', command, via: 'to_command' };
+    }
+    // Prefer ignore with count (documented): no mapping and no /to → drop
+    return { kind: 'ignored_unroutable' };
+}
+export function processUpdates(store, updates, env = process.env) {
+    const summary = {
+        updates_seen: updates.length,
+        enqueued: 0,
+        ignored_not_allowlisted: 0,
+        ignored_unroutable: 0,
+        ignored_no_text: 0,
+        commands: [],
+    };
+    let maxUpdateId;
+    for (const u of updates) {
+        if (maxUpdateId === undefined || u.update_id > maxUpdateId) {
+            maxUpdateId = u.update_id;
+        }
+        const message = u.message ?? u.edited_message;
+        if (!message)
+            continue;
+        const result = routeInboundMessage(store, message, env);
+        switch (result.kind) {
+            case 'enqueued':
+                summary.enqueued += 1;
+                summary.commands.push(result.command);
+                break;
+            case 'ignored_not_allowlisted':
+                summary.ignored_not_allowlisted += 1;
+                break;
+            case 'ignored_unroutable':
+                summary.ignored_unroutable += 1;
+                break;
+            case 'ignored_no_text':
+                summary.ignored_no_text += 1;
+                break;
+        }
+    }
+    if (maxUpdateId !== undefined) {
+        summary.next_offset = maxUpdateId + 1;
+    }
+    return summary;
+}
+//# sourceMappingURL=routing.js.map

package/dist/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Local JSON persistence for outbound message→agent mappings and pending inbound commands.
+ * Path: TELEGRAM_NOTIFY_DATA_DIR or ./.telegram-notify-data
+ * Does not log secrets. Never execute Telegram text as shell.
+ */
+export interface OutboundMapping {
+    chat_id: string;
+    telegram_message_id: number;
+    source_agent_id: string;
+    source_agent_name?: string;
+    conversation_hint?: string;
+    created_at: string;
+}
+export type PendingCommandStatus = 'pending' | 'acked';
+export interface PendingCommand {
+    id: string;
+    source_agent_id: string;
+    source_agent_name?: string;
+    conversation_hint?: string;
+    chat_id: string;
+    telegram_message_id: number;
+    reply_to_telegram_message_id?: number;
+    text: string;
+    created_at: string;
+    status: PendingCommandStatus;
+    error?: string;
+}
+export declare function getDataDir(env?: NodeJS.ProcessEnv): string;
+export declare class LocalStore {
+    readonly dataDir: string;
+    private readonly filePath;
+    constructor(dataDir?: string);
+    private ensureDir;
+    private read;
+    private write;
+    putMapping(entry: Omit<OutboundMapping, 'created_at'> & {
+        created_at?: string;
+    }): OutboundMapping;
+    getMapping(chatId: string | number, messageId: number): OutboundMapping | undefined;
+    enqueuePending(input: Omit<PendingCommand, 'id' | 'created_at' | 'status'> & {
+        id?: string;
+        created_at?: string;
+        status?: PendingCommandStatus;
+    }): PendingCommand;
+    listPending(filter?: {
+        source_agent_id?: string;
+        includeAcked?: boolean;
+    }): PendingCommand[];
+    /**
+     * Idempotent ack: marks pending→acked and removes from active list (or keeps as acked).
+     * Returns the command if found; undefined if unknown id.
+     */
+    ackCommand(id: string): PendingCommand | undefined;
+    getUpdateOffset(): number | undefined;
+    setUpdateOffset(offset: number): void;
+}

package/dist/store.js

@@ -0,0 +1,126 @@
+/**
+ * Local JSON persistence for outbound message→agent mappings and pending inbound commands.
+ * Path: TELEGRAM_NOTIFY_DATA_DIR or ./.telegram-notify-data
+ * Does not log secrets. Never execute Telegram text as shell.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+function mappingKey(chatId, messageId) {
+    return `${chatId}:${messageId}`;
+}
+export function getDataDir(env = process.env) {
+    const fromEnv = (env.TELEGRAM_NOTIFY_DATA_DIR ?? '').trim();
+    if (fromEnv)
+        return fromEnv;
+    return join(process.cwd(), '.telegram-notify-data');
+}
+function emptyStore() {
+    return { mappings: {}, pending: [], update_offset: undefined };
+}
+export class LocalStore {
+    dataDir;
+    filePath;
+    constructor(dataDir) {
+        this.dataDir = dataDir ?? getDataDir();
+        this.filePath = join(this.dataDir, 'store.json');
+    }
+    ensureDir() {
+        if (!existsSync(this.dataDir)) {
+            mkdirSync(this.dataDir, { recursive: true });
+        }
+    }
+    read() {
+        this.ensureDir();
+        if (!existsSync(this.filePath)) {
+            return emptyStore();
+        }
+        try {
+            const raw = readFileSync(this.filePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            return {
+                mappings: parsed.mappings ?? {},
+                pending: Array.isArray(parsed.pending) ? parsed.pending : [],
+                update_offset: parsed.update_offset,
+            };
+        }
+        catch {
+            return emptyStore();
+        }
+    }
+    write(data) {
+        this.ensureDir();
+        writeFileSync(this.filePath, JSON.stringify(data, null, 2), 'utf8');
+    }
+    putMapping(entry) {
+        const data = this.read();
+        const full = {
+            chat_id: String(entry.chat_id),
+            telegram_message_id: entry.telegram_message_id,
+            source_agent_id: entry.source_agent_id,
+            source_agent_name: entry.source_agent_name,
+            conversation_hint: entry.conversation_hint,
+            created_at: entry.created_at ?? new Date().toISOString(),
+        };
+        data.mappings[mappingKey(full.chat_id, full.telegram_message_id)] = full;
+        this.write(data);
+        return full;
+    }
+    getMapping(chatId, messageId) {
+        const data = this.read();
+        return data.mappings[mappingKey(chatId, messageId)];
+    }
+    enqueuePending(input) {
+        const data = this.read();
+        const cmd = {
+            id: input.id ?? randomUUID(),
+            source_agent_id: input.source_agent_id,
+            source_agent_name: input.source_agent_name,
+            conversation_hint: input.conversation_hint,
+            chat_id: String(input.chat_id),
+            telegram_message_id: input.telegram_message_id,
+            reply_to_telegram_message_id: input.reply_to_telegram_message_id,
+            text: input.text,
+            created_at: input.created_at ?? new Date().toISOString(),
+            status: input.status ?? 'pending',
+            error: input.error,
+        };
+        data.pending.push(cmd);
+        this.write(data);
+        return cmd;
+    }
+    listPending(filter) {
+        const data = this.read();
+        return data.pending.filter((c) => {
+            if (!filter?.includeAcked && c.status !== 'pending')
+                return false;
+            if (filter?.source_agent_id && c.source_agent_id !== filter.source_agent_id)
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Idempotent ack: marks pending→acked and removes from active list (or keeps as acked).
+     * Returns the command if found; undefined if unknown id.
+     */
+    ackCommand(id) {
+        const data = this.read();
+        const idx = data.pending.findIndex((c) => c.id === id);
+        if (idx < 0)
+            return undefined;
+        const cmd = { ...data.pending[idx], status: 'acked' };
+        // Drop acked rows to keep the file small (at-least-once already delivered)
+        data.pending.splice(idx, 1);
+        this.write(data);
+        return cmd;
+    }
+    getUpdateOffset() {
+        return this.read().update_offset;
+    }
+    setUpdateOffset(offset) {
+        const data = this.read();
+        data.update_offset = offset;
+        this.write(data);
+    }
+}
+//# sourceMappingURL=store.js.map