@mono-agent/telegram-adapter 0.4.0 → 0.4.1

package/dist/bot.js

@@ -1,13 +1,61 @@
+import { stat, readFile, unlink } from "node:fs/promises";
+import { Agent as HttpAgent } from "node:http";
+import { Agent as HttpsAgent } from "node:https";
+import { isAbsolute } from "node:path";
 import { isAgentResponseCancelledError } from "@mono-agent/agent-contracts";
 import { run } from "@grammyjs/runner";
 import { Bot } from "grammy";
 import { DEFAULT_MESSAGES, buildAgentRequest, downloadTelegramAttachments, finishSafely, mergeTelegramMessageInputs, normalizeTelegramMessageInput, resolveErrorText, } from "./adapter.js";
+import { isTelegramAskCallbackData } from "./ask.js";
 import { createGrammyTelegramApi } from "./grammy-client.js";
 import { TelegramMessageStream, } from "./message-stream.js";
 const DEFAULT_INITIAL_STATUS_TEXT = "Thinking…";
 // Quiet window after the last album message before we flush the group as one
 // request. Telegram sends album parts back-to-back (sub-second), so ~1s is safe.
 const DEFAULT_ALBUM_AGGREGATION_DELAY_MS = 1000;
+// Lifecycle reaction emojis (when `reactions` is enabled): 👀 while the agent
+// works, 👍 on success, 👎 on failure. Constrained to Telegram's allowed reaction
+// set — ✅/❌ are NOT valid bot reactions, so the closest allowed emojis are used.
+const REACTION_WORKING = "👀";
+const REACTION_DONE = "👍";
+const REACTION_ERROR = "👎";
+// Bound on the in-memory set of already-answered callback keys so a long-running
+// bot cannot grow it unbounded. A double-tap on an old question past this many
+// distinct answered questions would simply re-run (acceptable, very rare).
+const CALLBACK_DEDUPE_MAX = 200;
+// grammY's Api client default `timeoutSeconds` is 500 (8m20s overall HTTP
+// timeout). A half-open socket (after a network blip or host sleep) therefore
+// hangs ~8 minutes before getUpdates errors. Cap the overall HTTP timeout at 50s
+// so a dead long-poll is detected quickly and the auto-restart monitor can act.
+const DEFAULT_API_TIMEOUT_SECONDS = 50;
+// Long-poll timeout passed to the runner's getUpdates fetch (seconds). Shorter
+// than the 50s client cap so a normal long-poll completes within the HTTP
+// timeout; a stalled socket then fails fast instead of hanging.
+const DEFAULT_LONG_POLL_TIMEOUT_SECONDS = 30;
+// The runner self-retries transient getUpdates errors with exponential backoff
+// for up to this window before its task rejects and the monitor takes over.
+const DEFAULT_RUNNER_MAX_RETRY_TIME_MS = 15_000;
+// Auto-restart backoff bounds for the polling monitor (mirrors slack-adapter's
+// socket-mode reconnect loop): start at 500ms, double on each consecutive
+// failed restart, cap at 30s, reset to the initial delay after a clean restart.
+const DEFAULT_RESTART_INITIAL_BACKOFF_MS = 500;
+const DEFAULT_RESTART_MAX_BACKOFF_MS = 30_000;
+// A restarted runner that stays up this long is treated as a clean restart, so
+// the backoff resets to the initial delay. A runner that crashes again before
+// this window keeps growing the backoff (avoids hammering a flapping connection).
+const DEFAULT_RESTART_STABILITY_MS = 30_000;
+// Poll-liveness watchdog: if no getUpdates call has RESOLVED within this window
+// the runner is force-restarted, even though its task() never rejected. grammY's
+// runner self-retries getUpdates internally, so a degraded connection can stop
+// delivering updates WITHOUT the task rejecting — the crash-based auto-restart
+// then never fires and the bot goes silently deaf. 120s comfortably clears the
+// 30s long-poll heartbeat (DEFAULT_LONG_POLL_TIMEOUT_SECONDS) so a normal
+// idle poll never trips it. Set pollWatchdogMs <= 0 to disable.
+const DEFAULT_POLL_WATCHDOG_MS = 120_000;
+// Cap the startup deleteWebhook call so a flaky network cannot block boot: the
+// app awaits start() before reporting ready, and an unbounded deleteWebhook can
+// hang ~50s (the Api client timeout), past the launcher's readiness deadline.
+const DEFAULT_DELETE_WEBHOOK_TIMEOUT_MS = 5_000;
 // Mirrors the harness LiveSessionManager's DEFAULT_MAX_PENDING_PER_CONVERSATION:
 // the per-chat admission queue rejects past this depth so a flood of same-chat
 // messages cannot grow the queue unbounded.
@@ -132,6 +180,9 @@ export function createTelegramBot(options) {
     const albumDelayMs = options.albumAggregationDelayMs ?? DEFAULT_ALBUM_AGGREGATION_DELAY_MS;
     const cancelChat = (chatId) => {
         const conversationId = `telegram:${String(chatId)}`;
+        // Fail any pending ask first so a tool blocked on ask_user returns
+        // "cancelled by user" instead of waiting out its timeout.
+        options.pendingAsks?.cancel(conversationId);
         // Clear queued follow-ups (and signal the harness to abort the in-flight
         // turn) first, then abort every controller we are tracking for this chat.
         options.responder.cancel?.(conversationId);
@@ -154,16 +205,63 @@ export function createTelegramBot(options) {
             }
         }
     };
-    const bot = options.botFactory?.(options.botToken) ?? new Bot(options.botToken);
+    // Cap the Api client's overall HTTP timeout so a half-open getUpdates socket
+    // fails in ~50s instead of grammY's 500s default — see DEFAULT_API_TIMEOUT_SECONDS.
+    // The botFactory test seam owns full Bot construction, so the cap (and the
+    // optional IPv4/IPv6 transport pin + apiRoot) is applied only on the default path.
+    const { client: clientOptions, agent: transportAgent } = buildTelegramBotClientOptions({
+        ...(options.apiRoot === undefined ? {} : { apiRoot: options.apiRoot }),
+        ...(options.transport?.ipFamily === undefined ? {} : { ipFamily: options.transport.ipFamily }),
+    });
+    const bot = options.botFactory?.(options.botToken) ??
+        new Bot(options.botToken, { client: clientOptions });
+    // Poll-liveness heartbeat: stamp the time each getUpdates call RESOLVED. The
+    // watchdog uses this to detect a runner that has gone silently deaf (connected
+    // but no longer delivering) and force-restart it. Installed last so it is the
+    // OUTERMOST transformer (grammY runs the most-recently-installed first), so it
+    // observes every getUpdates resolution even beneath a test-injected transformer.
+    let lastPollMs = Date.now();
+    bot.api.config.use(async (prev, method, payload, signal) => {
+        const result = await prev(method, payload, signal);
+        if (method === "getUpdates") {
+            lastPollMs = Date.now();
+        }
+        return result;
+    });
     const sender = createGrammyTelegramApi(bot.api);
     const fileDownloader = options.fileDownloaderFactory?.(bot, options.botToken) ??
         createDefaultFileDownloader(bot, options.botToken, {
             ...(options.attachments?.downloadTimeoutMs !== undefined
                 ? { downloadTimeoutMs: options.attachments.downloadTimeoutMs }
                 : {}),
+            ...(options.apiRoot === undefined ? {} : { apiRoot: options.apiRoot }),
             ...(logger !== undefined ? { logger } : {}),
         });
     const isAuthorized = (chatId) => chatId !== undefined && (allowAllChats || allowedChatIds.has(String(chatId)));
+    const reactions = options.reactions;
+    /**
+     * Set (or clear, when `emoji` is undefined) the bot's reaction on a message.
+     * Per-state gating is the caller's job; this only no-ops when the sender lacks
+     * the method, and swallows a failure (e.g. missing permission) so it never
+     * affects the turn. Telegram constrains reactions to a fixed emoji set.
+     */
+    async function applyReaction(chatId, messageId, emoji) {
+        if (sender.setMessageReaction === undefined) {
+            return;
+        }
+        try {
+            await sender.setMessageReaction({
+                chat_id: chatId,
+                message_id: messageId,
+                reaction: emoji === undefined ? [] : [{ type: "emoji", emoji }],
+            });
+        }
+        catch (error) {
+            logger?.debug?.("Telegram setMessageReaction failed (best-effort).", {
+                error: errorMessage(error),
+            });
+        }
+    }
     bot.use(async (ctx, next) => {
         const chatId = ctx.chat?.id;
         if (chatId === undefined) {
@@ -188,6 +286,96 @@ export function createTelegramBot(options) {
         }
         await ctx.reply(messages.cancelledText);
     });
+    // Custom config-driven commands. Registered before the catch-all `message`
+    // handler so a `/cmd` is dispatched here (and never falls through to the agent
+    // as raw text). A command with a `prompt` runs it as a turn through the same
+    // per-chat queue as a typed message; a prompt-less command is menu-only and
+    // just echoes its description. Built-in start/help/cancel are reserved (config
+    // validation rejects them), so these never shadow a built-in.
+    const customCommands = options.commands ?? [];
+    for (const command of customCommands) {
+        const prompt = command.prompt;
+        bot.command(command.command, async (ctx) => {
+            const chatId = ctx.chat?.id;
+            if (chatId === undefined) {
+                return;
+            }
+            if (prompt === undefined) {
+                await ctx.reply(command.description);
+                return;
+            }
+            await notify(chatId, prompt);
+        });
+    }
+    // Inline-keyboard callbacks (telegram_ask). Subscribed only when enabled (the
+    // default `allowedUpdates` then also includes `callback_query`). The auth gate
+    // above already blocks unauthorized chats; we re-check defensively. On a tap we
+    // resolve the chosen LABEL from the tapped message's own keyboard (so no
+    // cross-process state is needed), answer the callback promptly, strip the
+    // buttons, and re-run the choice as a turn on the same conversation — exactly
+    // like a typed reply, on the warm session.
+    const callbacksEnabled = options.callbacksEnabled === true;
+    const answeredCallbacks = new Set();
+    const rememberAnswered = (key) => {
+        answeredCallbacks.add(key);
+        if (answeredCallbacks.size > CALLBACK_DEDUPE_MAX) {
+            const oldest = answeredCallbacks.values().next().value;
+            if (oldest !== undefined) {
+                answeredCallbacks.delete(oldest);
+            }
+        }
+    };
+    async function answerCallbackQuietly(ctx, text) {
+        try {
+            await ctx.answerCallbackQuery(text === undefined ? undefined : { text });
+        }
+        catch (error) {
+            logger?.debug?.("Telegram answerCallbackQuery failed (best-effort).", {
+                error: errorMessage(error),
+            });
+        }
+    }
+    if (callbacksEnabled) {
+        bot.on("callback_query:data", async (ctx) => {
+            if (stopped) {
+                return;
+            }
+            const chatId = ctx.chat?.id;
+            const data = ctx.callbackQuery.data;
+            if (chatId === undefined || !isAuthorized(chatId) || !isTelegramAskCallbackData(data)) {
+                await answerCallbackQuietly(ctx);
+                return;
+            }
+            const messageId = ctx.callbackQuery.message?.message_id;
+            const dedupeKey = `${String(chatId)}:${messageId ?? "?"}`;
+            if (answeredCallbacks.has(dedupeKey)) {
+                await answerCallbackQuietly(ctx, "Already recorded.");
+                return;
+            }
+            // Claim synchronously (no await before this) so a near-simultaneous second
+            // tap on the same question de-dupes instead of running a second turn.
+            rememberAnswered(dedupeKey);
+            const label = labelForCallbackData(ctx.callbackQuery.message?.reply_markup, data);
+            await answerCallbackQuietly(ctx, label === undefined ? undefined : `You chose: ${label}`);
+            if (label === undefined) {
+                return;
+            }
+            // Strip the keyboard so the question cannot be answered twice (best-effort).
+            try {
+                await ctx.editMessageReplyMarkup();
+            }
+            catch (error) {
+                logger?.debug?.("Telegram editMessageReplyMarkup failed after callback (best-effort).", {
+                    error: errorMessage(error),
+                });
+            }
+            const question = ctx.callbackQuery.message?.text;
+            const syntheticText = question !== undefined && question.trim().length > 0
+                ? `Re: "${question.trim()}" — I chose: ${label}`
+                : `I chose: ${label}`;
+            await notify(chatId, syntheticText);
+        });
+    }
     // A single handler for every message type so all messages reach the per-chat
     // admission queue at the same middleware depth. Separate per-type handlers sit
     // at different filter positions, and grammY yields a microtask per non-matching
@@ -259,6 +447,21 @@ export function createTelegramBot(options) {
             await handleControlCommand(ctx, captionCommand);
             return;
         }
+        // A plain-text reply while an ask is pending is that ask's ANSWER. It must be
+        // consumed BEFORE admission: the asking turn holds this chat's queue slot, so
+        // queueing the reply as a turn would deadlock it behind the very tool call
+        // waiting for it. Media always passes through, and slash-prefixed text is
+        // left to the (unknown-)command path so an ask can never eat a command.
+        if (options.pendingAsks !== undefined &&
+            typeof telegramMessage.text === "string" &&
+            telegramMessage.text.trim().length > 0 &&
+            !telegramMessage.text.trimStart().startsWith("/")) {
+            const consumed = await options.pendingAsks.tryResolve(`telegram:${String(chatId)}`, telegramMessage.text);
+            if (consumed) {
+                await applyReaction(chatId, telegramMessage.message_id, "👍");
+                return;
+            }
+        }
         const input = normalizeTelegramMessageInput(telegramMessage);
         if (input === undefined) {
             await ctx.reply(messages.unsupportedText);
@@ -388,14 +591,27 @@ export function createTelegramBot(options) {
         }
         const request = buildAgentRequest(ctx.update, message, input, controller.signal, resolvedAttachments);
         const stream = new TelegramMessageStream(buildStreamOptions(chatId, message.message_id, controller.signal));
+        // Tracks the lifecycle reaction to apply on teardown. Defaults to "error" so
+        // an unexpected throw still lands on the 👎 reaction.
+        let reactionOutcome = "error";
+        // Whether we set the working 👀, so a terminal state with its own reaction
+        // disabled can CLEAR it rather than leave it lingering on the message.
+        let workingReacted = false;
         try {
             // Parked-then-cancelled: /cancel aborted this controller while the message
             // waited behind an earlier same-chat run. Bail before any responder call so a
             // queued message is genuinely cancelled (not run on the warm session later).
             if (controller.signal.aborted) {
+                reactionOutcome = "cancelled";
                 await finishSafely(stream, messages.cancelledText, logger);
                 return;
             }
+            // Acknowledge receipt with the working reaction before the (slower) status
+            // post + agent run, so the user sees the bot picked up the message at once.
+            if (reactions?.working === true) {
+                await applyReaction(chatId, message.message_id, REACTION_WORKING);
+                workingReacted = true;
+            }
             try {
                 await stream.status(initialStatusText);
             }
@@ -405,6 +621,7 @@ export function createTelegramBot(options) {
                 });
             }
             if (controller.signal.aborted) {
+                reactionOutcome = "cancelled";
                 await finishSafely(stream, messages.cancelledText, logger);
                 return;
             }
@@ -414,6 +631,7 @@ export function createTelegramBot(options) {
             }
             catch (error) {
                 if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    reactionOutcome = "cancelled";
                     await finishSafely(stream, messages.cancelledText, logger);
                     return;
                 }
@@ -428,14 +646,17 @@ export function createTelegramBot(options) {
                 return;
             }
             if (controller.signal.aborted) {
+                reactionOutcome = "cancelled";
                 await finishSafely(stream, messages.cancelledText, logger);
                 return;
             }
             try {
                 await stream.finish(response.text);
+                reactionOutcome = "done";
             }
             catch (error) {
                 if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    reactionOutcome = "cancelled";
                     return;
                 }
                 // The AI run succeeded; a delivery failure is degraded, never an error.
@@ -444,10 +665,158 @@ export function createTelegramBot(options) {
                 });
             }
         }
+        finally {
+            // Apply the terminal reaction: 👍 on success / 👎 on failure when that state
+            // is enabled; otherwise (or on cancel) clear the working 👀 if we set one, so
+            // a disabled terminal state never leaves the message marked "working".
+            if (reactions !== undefined) {
+                const terminalEnabled = reactionOutcome === "done"
+                    ? reactions.done
+                    : reactionOutcome === "error"
+                        ? reactions.error
+                        : false;
+                if (terminalEnabled) {
+                    await applyReaction(chatId, message.message_id, reactionOutcome === "done" ? REACTION_DONE : REACTION_ERROR);
+                }
+                else if (workingReacted) {
+                    await applyReaction(chatId, message.message_id, undefined);
+                }
+            }
+            unregisterController(chatId, controller);
+        }
+    }
+    /**
+     * Run a proactive (externally triggered) turn on a chat: a cron/webhook nudge
+     * routed here so the message becomes a REAL turn on this chat's own harness
+     * (same session + history + per-chat queue as inbound messages), delivered
+     * through the normal stream. No inbound message, so the request carries
+     * sentinel ids and the stream posts top-level (no reply-to). Best-effort: a
+     * failed or empty turn posts nothing rather than an unprompted error.
+     */
+    async function runProactiveTurn(chatId, text, controller, silent) {
+        try {
+            if (controller.signal.aborted) {
+                return { delivered: false, reason: "cancelled" };
+            }
+            const request = {
+                conversationId: `telegram:${String(chatId)}`,
+                chatId,
+                messageId: 0,
+                updateId: 0,
+                text,
+                abortSignal: controller.signal,
+                metadata: {
+                    telegram: {
+                        updateId: 0,
+                        chat: { id: chatId },
+                        message: { id: 0 },
+                    },
+                },
+            };
+            const stream = new TelegramMessageStream(buildStreamOptions(chatId, undefined, controller.signal, silent));
+            let response;
+            try {
+                response = await options.responder.respond(request, stream);
+            }
+            catch (error) {
+                if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    return { delivered: false, reason: "cancelled" };
+                }
+                logger?.error?.("Telegram proactive notify failed.", { error: errorMessage(error) });
+                return { delivered: false, reason: "responder failed" };
+            }
+            const answer = response.text;
+            if (controller.signal.aborted) {
+                return { delivered: false, reason: "cancelled" };
+            }
+            if (answer === undefined || answer.trim().length === 0) {
+                return { delivered: false, reason: "agent produced no answer" };
+            }
+            try {
+                await stream.finish(answer);
+            }
+            catch (error) {
+                if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    return { delivered: false, reason: "cancelled" };
+                }
+                // The AI run succeeded; a delivery failure is degraded, never an error.
+                logger?.error?.("Telegram proactive delivery failed after a successful AI run.", {
+                    error: errorMessage(error),
+                });
+                return { delivered: false, reason: "delivery failed" };
+            }
+            return { delivered: true };
+        }
+        finally {
+            unregisterController(chatId, controller);
+        }
+    }
+    /**
+     * Deliver `text` VERBATIM to `chatId`: post it unchanged through the normal
+     * stream with NO model call (the producing cron/webhook run already wrote the
+     * message), then record it to the chat's durable history via the responder so a
+     * later reply resumes with it in context. Serialized through the per-chat queue
+     * by {@link notify}. Best-effort: a history-record failure never fails an
+     * already-delivered post.
+     */
+    async function runVerbatimDelivery(chatId, text, controller, silent) {
+        try {
+            if (controller.signal.aborted) {
+                return { delivered: false, reason: "cancelled" };
+            }
+            if (text.trim().length === 0) {
+                return { delivered: false, reason: "empty notification" };
+            }
+            const stream = new TelegramMessageStream(buildStreamOptions(chatId, undefined, controller.signal, silent));
+            try {
+                await stream.finish(text);
+            }
+            catch (error) {
+                if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    return { delivered: false, reason: "cancelled" };
+                }
+                logger?.error?.("Telegram verbatim notify delivery failed.", { error: errorMessage(error) });
+                return { delivered: false, reason: "delivery failed" };
+            }
+            try {
+                await options.responder.deliverVerbatim?.(`telegram:${String(chatId)}`, text);
+            }
+            catch (error) {
+                logger?.warn?.("Telegram verbatim notify history record failed.", { error: errorMessage(error) });
+            }
+            return { delivered: true };
+        }
         finally {
             unregisterController(chatId, controller);
         }
     }
+    /**
+     * Deliver a proactive notification to `chatId` by running it as a turn on this
+     * chat through the same per-chat admission queue as inbound messages, so it
+     * serializes with live traffic on the same conversation.
+     */
+    async function notify(chatId, text, notifyOptions) {
+        if (stopped) {
+            return { delivered: false, reason: "adapter stopped" };
+        }
+        const controller = registerController(chatId);
+        const silent = notifyOptions?.silent === true;
+        // `admit` returns void, so capture the run's outcome in a closure variable.
+        // It defaults to the queue-full reason and is only overwritten when the task
+        // actually runs (an over-cap rejection settles via onReject, leaving it).
+        let outcome = { delivered: false, reason: "chat at concurrency cap" };
+        await admit(chatId, async () => {
+            outcome = notifyOptions?.verbatim === true
+                ? await runVerbatimDelivery(chatId, text, controller, silent)
+                : await runProactiveTurn(chatId, text, controller, silent);
+        }, () => {
+            unregisterController(chatId, controller);
+            logger?.warn?.("Telegram proactive notify dropped: chat is at its concurrency cap.", {
+                chatId: String(chatId),
+            });
+        });
+        return outcome;
+    }
     async function handleControlCommand(ctx, command) {
         if (command === "start") {
             await ctx.reply(messages.welcomeText);
@@ -463,16 +832,23 @@ export function createTelegramBot(options) {
         }
         await ctx.reply(messages.cancelledText);
     }
-    function buildStreamOptions(chatId, replyToMessageId, signal) {
+    function buildStreamOptions(chatId, replyToMessageId, signal, silent = false) {
         const streamOptions = {
             api: sender,
             chatId,
-            replyToMessageId,
             abortSignal: signal,
             // Default to "typing…" + final-answer-only delivery (no streamed interim
             // edits); a tuning override can restore interim streaming.
             finalOnly: options.stream?.finalOnly ?? true,
         };
+        if (silent) {
+            streamOptions.silent = true;
+        }
+        // Proactive notifications have no inbound message to reply to, so the caller
+        // may omit replyToMessageId (a top-level send rather than a threaded reply).
+        if (replyToMessageId !== undefined) {
+            streamOptions.replyToMessageId = replyToMessageId;
+        }
         const tuning = options.stream;
         if (tuning?.initialStatusText !== undefined) {
             streamOptions.initialStatusText = tuning.initialStatusText;
@@ -507,8 +883,218 @@ export function createTelegramBot(options) {
         return streamOptions;
     }
     let runnerHandle;
+    // Pending auto-restart timer (set while backing off after a polling crash).
+    // Cleared by stop() and before each restart so at most one restart is queued.
+    let restartTimer;
+    // Fires once a restarted runner has stayed up for the stability window, at
+    // which point the backoff resets to the initial delay. Cleared on the next
+    // crash/restart and on stop().
+    let stabilityTimer;
+    // Current restart backoff (ms). Doubles on each consecutive crash that recurs
+    // before the stability window; resets to the initial delay on a clean restart.
+    let restartBackoffMs = DEFAULT_RESTART_INITIAL_BACKOFF_MS;
+    // Poll-liveness watchdog. Lifetime-scoped (armed at first spawn, cleared on
+    // stop()) so it spans crash/backoff/restart cycles. `pollWatchdogMs <= 0`
+    // disables it. `watchdogRestarting` prevents a second tick from stacking
+    // another stop()/spawn while a forced restart is still settling.
+    const pollWatchdogMs = options.pollWatchdogMs ?? DEFAULT_POLL_WATCHDOG_MS;
+    let pollWatchdogTimer;
+    let watchdogRestarting = false;
+    // True once polling has crashed and not yet recovered. Gates onPollingRecovered
+    // so it fires only after a real crash→recovery cycle, never on the initial start.
+    let pollingDegraded = false;
+    /** Arm the lifetime-scoped poll-liveness watchdog (idempotent, no-op if disabled). */
+    function startPollWatchdog() {
+        if (pollWatchdogMs <= 0 || pollWatchdogTimer !== undefined) {
+            return;
+        }
+        // Check a few times per window so a stall is caught within ~1/3 of it.
+        const checkMs = Math.max(1_000, Math.floor(pollWatchdogMs / 3));
+        pollWatchdogTimer = setInterval(() => {
+            checkPollLiveness();
+        }, checkMs);
+        pollWatchdogTimer.unref?.();
+    }
+    function clearPollWatchdog() {
+        if (pollWatchdogTimer !== undefined) {
+            clearInterval(pollWatchdogTimer);
+            pollWatchdogTimer = undefined;
+        }
+    }
+    /**
+     * Force-restart the current runner if no getUpdates has resolved within the
+     * watchdog window. This covers the case the crash monitor cannot: grammY's
+     * runner self-retries getUpdates internally, so a degraded connection can stop
+     * delivering updates WITHOUT the task rejecting. We only act on a runner that
+     * reports running (a crashed/stopped one is handled by the crash monitor), and
+     * we go through a clean stop() + respawn so the crash monitor is not tripped.
+     */
+    function checkPollLiveness() {
+        if (stopped || watchdogRestarting) {
+            return;
+        }
+        const current = runnerHandle;
+        if (current?.isRunning() !== true) {
+            return;
+        }
+        const stalledMs = Date.now() - lastPollMs;
+        if (stalledMs <= pollWatchdogMs) {
+            return;
+        }
+        watchdogRestarting = true;
+        // Reset the window up front so the replacement runner gets a full grace
+        // period and a slow stop() cannot let a later tick re-trigger.
+        lastPollMs = Date.now();
+        logger?.warn?.("Telegram poll liveness stalled; force-restarting the runner.", {
+            stalledMs,
+            thresholdMs: pollWatchdogMs,
+        });
+        void Promise.resolve(current.stop())
+            .catch(() => undefined)
+            .finally(() => {
+            watchdogRestarting = false;
+            // Only respawn if nothing else swapped/stopped the runner meanwhile. A
+            // watchdog restart is a clean recovery, so reset the backoff (mirrors a
+            // stable restart) rather than inheriting the crash backoff.
+            if (!stopped && runnerHandle === current) {
+                restartBackoffMs = DEFAULT_RESTART_INITIAL_BACKOFF_MS;
+                spawnRunnerWithMonitor();
+            }
+        });
+    }
+    /**
+     * Spawn a runner and attach the crash monitor. The runner's task rejects when
+     * long polling dies (e.g. getUpdates ETIMEDOUT/EADDRNOTAVAIL after a network
+     * blip or host sleep). Without auto-restart the runner just stops and the bot
+     * goes silent until a full process restart — so on a crash (while not stopped)
+     * we recreate the runner via the factory and re-attach the monitor, with
+     * exponential backoff. Mirrors slack-adapter's socket-mode reconnect loop.
+     */
+    function spawnRunnerWithMonitor() {
+        if (stabilityTimer !== undefined) {
+            clearTimeout(stabilityTimer);
+            stabilityTimer = undefined;
+        }
+        // Give the (re)spawned runner a full watchdog window before it can be judged
+        // stalled, and ensure the lifetime-scoped watchdog is armed.
+        lastPollMs = Date.now();
+        startPollWatchdog();
+        runnerHandle = (options.runnerFactory ?? defaultRunnerFactory)(bot);
+        const spawned = runnerHandle;
+        // A runner that stays up for the stability window counts as a clean restart:
+        // reset the backoff so a LATER, unrelated crash starts from the initial delay
+        // again. A runner that crashes before this window keeps the grown backoff so
+        // a flapping connection is not hammered.
+        stabilityTimer = setTimeout(() => {
+            stabilityTimer = undefined;
+            if (!stopped && runnerHandle === spawned) {
+                restartBackoffMs = DEFAULT_RESTART_INITIAL_BACKOFF_MS;
+                // This runner stayed up past the stability window. If it followed a crash,
+                // polling has recovered — tell the host so it can clear a "degraded" state.
+                if (pollingDegraded) {
+                    pollingDegraded = false;
+                    options.onPollingRecovered?.();
+                }
+            }
+        }, DEFAULT_RESTART_STABILITY_MS);
+        stabilityTimer.unref?.();
+        // Only a REJECTION is a crash: grammY's runner task rejects when long polling
+        // dies (getUpdates ETIMEDOUT/EADDRNOTAVAIL). A clean resolution means the
+        // runner was stopped deliberately (stop() / a host-driven stop), so it is NOT
+        // auto-restarted — matching the original .catch-only handling.
+        runnerHandle.task?.()?.catch((error) => { onPollingCrashed(error); });
+    }
+    /**
+     * Handle a runner task REJECTION: long polling crashed. If the adapter is
+     * stopped this is the expected teardown path (no-op). Otherwise surface it
+     * (logger + onPollingError) and schedule a backoff restart so the bot recovers
+     * instead of going silent until a full process restart.
+     */
+    function onPollingCrashed(error) {
+        // The runner is no longer up, so cancel the pending stability reset: the
+        // backoff must keep growing if this crash recurs before a runner stays up.
+        if (stabilityTimer !== undefined) {
+            clearTimeout(stabilityTimer);
+            stabilityTimer = undefined;
+        }
+        if (stopped) {
+            return;
+        }
+        if (!pollingDegraded) {
+            logger?.error?.("Telegram polling stopped with an error; scheduling restart.", {
+                error: errorMessage(error),
+                restartInMs: restartBackoffMs,
+            });
+            // Mark degraded so the stability-window callback fires onPollingRecovered once a
+            // restarted runner stays up. The adapter always restarts (capped backoff), so a
+            // crash is "degraded, recovering" to the host — never terminal.
+            pollingDegraded = true;
+        }
+        options.onPollingError?.(error);
+        scheduleRestart();
+    }
+    /** Schedule a single backoff restart, growing the backoff for the next attempt. */
+    function scheduleRestart() {
+        if (restartTimer !== undefined) {
+            return;
+        }
+        const delay = restartBackoffMs;
+        // Grow the backoff now so a restart that itself crashes before resetting (via
+        // a healthy spawn) backs off further next time.
+        restartBackoffMs = Math.min(DEFAULT_RESTART_MAX_BACKOFF_MS, restartBackoffMs * 2);
+        restartTimer = setTimeout(() => {
+            restartTimer = undefined;
+            if (stopped) {
+                return;
+            }
+            try {
+                spawnRunnerWithMonitor();
+            }
+            catch (error) {
+                // The factory threw synchronously (e.g. transient construction failure):
+                // back off and try again rather than giving up.
+                logger?.error?.("Telegram polling restart failed; backing off.", {
+                    error: errorMessage(error),
+                });
+                scheduleRestart();
+            }
+        }, delay);
+        // Never let the restart timer keep the process alive on its own.
+        restartTimer.unref?.();
+    }
+    // Tool-progress status messages, keyed `chat:key` → message_id for edit-in-place.
+    const statusMessages = new Map();
     return {
         bot,
+        notify,
+        async post(chatId, text) {
+            await sender.sendMessage({ chat_id: chatId, text });
+        },
+        async postStatus(chatId, text, statusOptions) {
+            const key = `${String(chatId)}:${statusOptions.key}`;
+            try {
+                const existing = statusMessages.get(key);
+                if (existing === undefined) {
+                    const sent = await sender.sendMessage({ chat_id: chatId, text });
+                    statusMessages.set(key, sent.message_id);
+                }
+                else {
+                    await sender.editMessageText({ chat_id: chatId, message_id: existing, text });
+                }
+            }
+            catch (error) {
+                // Best-effort by contract: a lost progress edit must never fail the
+                // reporting tool (e.g. "message is not modified" on identical text).
+                logger?.debug?.("Telegram postStatus failed (best-effort).", {
+                    error: errorMessage(error),
+                });
+            }
+            finally {
+                if (statusOptions.state !== "working") {
+                    statusMessages.delete(key);
+                }
+            }
+        },
         activeControllerCount() {
             let total = 0;
             for (const set of activeControllers.values()) {
@@ -526,25 +1112,81 @@ export function createTelegramBot(options) {
             // update can be dispatched by the new runner) means a restart actually
             // handles messages again instead of silently dropping every one.
             stopped = false;
+            restartBackoffMs = DEFAULT_RESTART_INITIAL_BACKOFF_MS;
+            // Clear any crash flag left over from a previous session: onPollingRecovered
+            // must only fire for a crash→recovery within THIS run, never for a stale
+            // crash that preceded a stop()/start() cycle.
+            pollingDegraded = false;
             if ((options.deleteWebhookOnStart ?? true) === true) {
-                await bot.api.deleteWebhook({ drop_pending_updates: options.dropPendingUpdates ?? false });
-            }
-            runnerHandle = (options.runnerFactory ?? defaultRunnerFactory)(bot);
-            // Surface a late polling crash to the shared logger and the host's
-            // onPollingError callback without leaving an unhandled rejection; stop()
-            // still settles the runner independently.
-            runnerHandle.task?.()?.catch((error) => {
-                logger?.error?.("Telegram polling stopped with an error.", {
-                    error: errorMessage(error),
-                });
-                options.onPollingError?.(error);
-            });
+                // Bound + best-effort: the host awaits start() before reporting ready, so
+                // an unbounded deleteWebhook over a flaky network could hang ~50s (the Api
+                // client timeout) and blow past the launcher's readiness deadline. Cap it
+                // and never reject so boot proceeds. This is safe for a polling bot with no
+                // webhook configured (the call is a no-op). NOTE: if a webhook genuinely IS
+                // set and this call is skipped/times out, getUpdates returns 409 and the
+                // runner crash-restarts on a backoff — the backoff path does NOT re-issue
+                // deleteWebhook, so polling only resumes once the webhook is cleared (a
+                // later full start(), or its natural expiry). Deployments that use webhooks
+                // should not rely on this fallback.
+                try {
+                    // grammY types `signal` with the abort-controller shim, not the global
+                    // AbortSignal; the runtime value is identical (cf. grammy-client.ts).
+                    const timeoutSignal = AbortSignal.timeout(options.deleteWebhookTimeoutMs ?? DEFAULT_DELETE_WEBHOOK_TIMEOUT_MS);
+                    await bot.api.deleteWebhook({ drop_pending_updates: options.dropPendingUpdates ?? false }, timeoutSignal);
+                }
+                catch (error) {
+                    logger?.warn?.("Telegram deleteWebhook failed or timed out at startup; continuing to poll.", {
+                        error: errorMessage(error),
+                    });
+                }
+            }
+            // Register the command menu (setMyCommands) when custom commands are
+            // configured: the built-in help/cancel plus each custom command, scoped to
+            // private chats. Best-effort + bounded so a flaky network can't stall boot
+            // (the menu is cosmetic); skipped entirely with no custom commands so an
+            // existing deployment sees no menu it never asked for.
+            if (customCommands.length > 0) {
+                const menu = [
+                    { command: "help", description: "How to use this agent" },
+                    { command: "cancel", description: "Stop the current response" },
+                    ...customCommands.map((command) => ({
+                        command: command.command,
+                        description: command.description,
+                    })),
+                ];
+                try {
+                    const timeoutSignal = AbortSignal.timeout(options.deleteWebhookTimeoutMs ?? DEFAULT_DELETE_WEBHOOK_TIMEOUT_MS);
+                    await bot.api.setMyCommands(menu, { scope: { type: "all_private_chats" } }, timeoutSignal);
+                }
+                catch (error) {
+                    logger?.warn?.("Telegram setMyCommands failed or timed out at startup; continuing.", {
+                        error: errorMessage(error),
+                    });
+                }
+            }
+            // Spawn the runner with the auto-restart monitor attached: a late polling
+            // crash is surfaced (logger + onPollingError) AND triggers a backoff
+            // restart instead of leaving the bot silent. stop() settles the runner and
+            // cancels any pending restart independently.
+            spawnRunnerWithMonitor();
         },
         async stop() {
             // Guard the timer/late-update paths first: a pending album timer must not
             // flush a turn after teardown. Clear every outstanding album timer and drop
             // the buffers (mirrors cancelChat's per-chat cleanup, but for all chats).
             stopped = true;
+            // Cancel any pending auto-restart so a backoff timer cannot resurrect the
+            // runner after shutdown. The `stopped` flag also short-circuits the monitor
+            // and the timer callback, so a restart in flight when stop() runs is a no-op.
+            if (restartTimer !== undefined) {
+                clearTimeout(restartTimer);
+                restartTimer = undefined;
+            }
+            if (stabilityTimer !== undefined) {
+                clearTimeout(stabilityTimer);
+                stabilityTimer = undefined;
+            }
+            clearPollWatchdog();
             for (const buffer of albumBuffers.values()) {
                 clearTimeout(buffer.timer);
                 // Settle the reserved admission slot so the parked admit() task does not
@@ -557,11 +1199,28 @@ export function createTelegramBot(options) {
                 await runnerHandle.stop();
             }
             runnerHandle = undefined;
+            // Close any in-flight socket on the family-pinned agent (no-op when the
+            // default dual-stack transport is used and no agent was created).
+            transportAgent?.destroy();
         },
     };
     function defaultRunnerFactory(target) {
-        const allowed = [...(options.allowedUpdates ?? ["message"])];
-        return run(target, { runner: { fetch: { allowed_updates: allowed } } });
+        const defaultAllowed = callbacksEnabled ? ["message", "callback_query"] : ["message"];
+        const allowed = [...(options.allowedUpdates ?? defaultAllowed)];
+        return run(target, {
+            runner: {
+                // Self-retry transient getUpdates errors (network blips) with exponential
+                // backoff before the task rejects and the monitor restarts the runner.
+                retryInterval: "exponential",
+                maxRetryTime: DEFAULT_RUNNER_MAX_RETRY_TIME_MS,
+                fetch: {
+                    allowed_updates: allowed,
+                    // Bound the long-poll below the Api client HTTP timeout so a stalled
+                    // socket fails fast instead of hanging on grammY's 500s default.
+                    timeout: DEFAULT_LONG_POLL_TIMEOUT_SECONDS,
+                },
+            },
+        });
     }
 }
 function errorMessage(error) {
@@ -576,6 +1235,32 @@ function createDeferred() {
     return { promise, resolve };
 }
 const DEFAULT_DOWNLOAD_TIMEOUT_MS = 30_000;
+/**
+ * Build the grammY client options for the default Bot construction. Extracted
+ * (and exported) so the apiRoot/agent interplay is unit-testable — the botFactory
+ * test seam otherwise owns the whole construction.
+ *
+ * grammY's node platform fetches with node-fetch, which rejects an agent whose
+ * protocol mismatches the URL — so the family-locked keep-alive-off agent (see
+ * the ipFamily rationale on {@link CreateTelegramBotOptions.transport}) must be
+ * an `http.Agent` when the apiRoot is plain http (a loopback self-hosted server)
+ * and an `https.Agent` otherwise.
+ */
+export function buildTelegramBotClientOptions(options) {
+    const client = { timeoutSeconds: DEFAULT_API_TIMEOUT_SECONDS };
+    if (options.apiRoot !== undefined) {
+        client.apiRoot = options.apiRoot;
+    }
+    if (options.ipFamily === undefined) {
+        return { client };
+    }
+    const agentOptions = { family: options.ipFamily, keepAlive: false };
+    const agent = options.apiRoot?.startsWith("http://") === true
+        ? new HttpAgent(agentOptions)
+        : new HttpsAgent(agentOptions);
+    client.baseFetchConfig = { ...client.baseFetchConfig, agent };
+    return { client, agent };
+}
 /**
  * Default {@link TelegramFileDownloader}: resolve a `file_id` to a `file_path`
  * via `bot.api.getFile`, then download it from the Telegram file URL
@@ -597,7 +1282,14 @@ function createDefaultFileDownloader(bot, token, options) {
             return file.file_path;
         },
         async download(filePath, signal, maxBytes) {
-            const url = `https://api.telegram.org/file/bot${token}/${filePath}`;
+            // A `--local` self-hosted server downloads the file itself during getFile
+            // and returns an ABSOLUTE path; the /file/ HTTP route is unavailable in
+            // that mode, so the bytes are read straight from disk. Hosted and
+            // non-local self-hosted servers return relative paths served over HTTP.
+            if (isAbsolute(filePath)) {
+                return await readLocalTelegramFile(filePath, signal, maxBytes, options?.logger);
+            }
+            const url = `${options?.apiRoot ?? "https://api.telegram.org"}/file/bot${token}/${filePath}`;
             const { signal: fetchSignal, cleanup } = composeDownloadSignal(signal, timeoutMs);
             try {
                 const response = await fetch(url, fetchSignal === undefined ? {} : { signal: fetchSignal });
@@ -620,6 +1312,37 @@ function createDefaultFileDownloader(bot, token, options) {
         },
     };
 }
+/**
+ * Read a `--local` Bot API server file from disk. The stat-before-read is the
+ * local analog of the Content-Length early-skip (the declared file_size in the
+ * update can be stale). A consumed read deletes the daemon's copy: the daemon
+ * keeps downloads for up to ~25h, the harness persists its own copy into the
+ * attachments dir before the model sees it, and getFile re-downloads on demand —
+ * so the daemon file is a drained cache. Skip paths (over-cap, missing) never
+ * delete.
+ */
+async function readLocalTelegramFile(filePath, signal, maxBytes, logger) {
+    let size;
+    try {
+        size = (await stat(filePath)).size;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error("Telegram local file is missing (expired from the Bot API server cache?).");
+        }
+        throw error;
+    }
+    if (maxBytes !== undefined && size > maxBytes) {
+        throw new Error("Telegram file exceeded the configured byte cap (local file size).");
+    }
+    const bytes = await readFile(filePath, signal === undefined ? {} : { signal });
+    await unlink(filePath).catch((error) => {
+        logger?.debug?.("Telegram local file cleanup failed (best-effort).", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+    return new Uint8Array(bytes);
+}
 /**
  * Compose a `downloadTimeoutMs` timer with the run abort signal into a single
  * signal for `fetch`. The returned `cleanup` clears the timer (and detaches the
@@ -705,6 +1428,25 @@ async function readBodyWithCap(response, maxBytes) {
     }
     return out;
 }
+/**
+ * Resolve the label of the button whose `callback_data` matches `data` by reading
+ * the tapped message's own inline keyboard. Returns undefined when the keyboard or
+ * a matching button is absent. Pure so it can be unit-tested directly.
+ */
+function labelForCallbackData(replyMarkup, data) {
+    const keyboard = replyMarkup?.inline_keyboard;
+    if (!Array.isArray(keyboard)) {
+        return undefined;
+    }
+    for (const row of keyboard) {
+        for (const button of row) {
+            if (button?.callback_data === data && typeof button.text === "string") {
+                return button.text;
+            }
+        }
+    }
+    return undefined;
+}
 function controlCommandFromCaption(message, botUsername) {
     if (message.text !== undefined || message.caption === undefined) {
         return undefined;