ping-a-human 0.1.1 → 0.1.3

package/dist/channels/telegram.js

@@ -1,3 +1,12 @@
+/**
+ * Telegram bot commands (text beginning with "/", e.g. "/start", "/help") are
+ * client/protocol messages, never a human's answer to a free-text question.
+ * The most common offender is the "/start" Telegram auto-sends when a user
+ * first opens the bot, which would otherwise be returned as the reply.
+ */
+function isBotCommand(text) {
+    return /^\/[A-Za-z0-9_]+(@\w+)?(\s|$)/.test(text.trim());
+}
 /**
  * Telegram implementation of the Channel interface using the Bot API over
  * plain HTTPS (Node's built-in fetch). No third-party Telegram SDK.
@@ -58,6 +67,15 @@ export class TelegramChannel {
     }
     async awaitReply(options) {
         const deadline = Date.now() + options.timeoutMs;
+        // Anchor: only accept replies that arrive AFTER the question was sent.
+        // Telegram message ids are monotonically increasing per chat, so any
+        // update whose message predates the question (e.g. a queued `/start` from
+        // first opening the bot) must be ignored — otherwise it would be wrongly
+        // returned as the human's answer. Honors AwaitReplyOptions.sinceRef.
+        const sinceMessageId = options.sinceRef != null ? Number(options.sinceRef.id) : undefined;
+        const isStale = (messageId) => sinceMessageId != null &&
+            messageId != null &&
+            messageId <= sinceMessageId;
         while (Date.now() < deadline) {
             const remainingMs = deadline - Date.now();
             // Don't long-poll longer than the time we have left.
@@ -73,6 +91,13 @@ export class TelegramChannel {
                 // Free-text reply.
                 const msg = update.message;
                 if (msg?.text && this.fromConfiguredChat(msg.chat)) {
+                    // Skip backlog that predates the question (e.g. a stale `/start`).
+                    if (isStale(msg.message_id))
+                        continue;
+                    // Bot commands ("/start", "/help", ...) are never valid answers to a
+                    // free-text question; treat them as noise and keep waiting.
+                    if (isBotCommand(msg.text))
+                        continue;
                     return {
                         status: "answered",
                         answer: msg.text,
@@ -81,7 +106,7 @@ export class TelegramChannel {
                 }
                 // Inline-button tap.
                 const cb = update.callback_query;
-                if (cb) {
+                if (cb && !isStale(cb.message?.message_id)) {
                     // Best-effort: clear the client's loading spinner.
                     try {
                         await this.api("answerCallbackQuery", { callback_query_id: cb.id });

package/dist/index.js

@@ -21,12 +21,12 @@ export function createServer(channelOptions = {}) {
     // 1.x registerTool: inputSchema is a ZodRawShape (plain object), NOT z.object(...).
     server.registerTool("notify_human", {
         title: "Notify human",
-        description: "Send a fire-and-forget message to the configured human (via Telegram) and return immediately without waiting for a reply.",
+        description: "Send a one-way, fire-and-forget message to the configured human (via Telegram) and return IMMEDIATELY. Use this ONLY to inform the human (status updates, 'task finished', 'deploy succeeded', FYIs) when you do NOT need anything back. The human's reply, if any, is NOT captured or returned. If you need a decision, approval, or any answer before continuing, DO NOT use this — use ask_human instead.",
         inputSchema: { message: z.string() },
     }, async ({ message }) => notifyHuman(resolveChannel(), { message }));
     server.registerTool("ask_human", {
         title: "Ask human",
-        description: "Send a question to the configured human and block until they reply (or a timeout elapses). Optionally provide choices to render tappable buttons. Returns the human's answer, or a clear timed-out result.",
+        description: "Ask the configured human a question and BLOCK until they reply on their messaging app (Telegram) or a timeout elapses. Use this whenever you need a human decision, approval, confirmation, clarification, or any answer before you can continue — the human's reply is captured and returned to you. Optionally provide `choices` to render tappable buttons (the tapped value is returned). Returns the human's answer, or a clear timed-out result if they don't respond in time. If you only need to inform the human and do NOT need a response, use notify_human instead.",
         inputSchema: {
             question: z.string(),
             choices: z.array(z.string()).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ping-a-human",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "An MCP server that adds a human-in-the-loop step to any AI pipeline by reaching a human on their own messaging app (Telegram first).",
   "type": "module",
   "bin": {