@mono-agent/telegram-adapter 0.3.0 → 0.4.1

package/dist/bot.js

@@ -1,10 +1,112 @@
+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, finishSafely, resolveErrorText, } from "./adapter.js";
+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.
+const DEFAULT_ADMISSION_QUEUE_MAX_DEPTH = 100;
+/**
+ * Thrown synchronously by {@link SerialQueue.run} when the queue is already at
+ * its depth cap. The bot catches this sentinel to answer with the busy reply
+ * instead of admitting an unbounded backlog.
+ */
+export class SerialQueueFullError extends Error {
+    code = "serial_queue_full";
+    constructor(maxDepth) {
+        super(`Per-chat admission queue is full (max ${maxDepth} pending).`);
+        this.name = "SerialQueueFullError";
+    }
+}
+function isSerialQueueFullError(error) {
+    return error instanceof SerialQueueFullError;
+}
+/**
+ * Minimal per-conversation serial queue: each submitted task runs only after the
+ * previous one settles, preserving arrival order. A task's failure does not
+ * poison the queue (the chain swallows it; the caller still sees the rejection).
+ *
+ * The queue is bounded by {@link maxDepth}: once `depth` reaches the cap, `run`
+ * rejects synchronously with a {@link SerialQueueFullError} BEFORE incrementing
+ * or chaining, so an over-cap task never enters the chain (mirroring the harness
+ * LiveSessionManager's maxPendingPerConversation rejection).
+ */
+export class SerialQueue {
+    tail = Promise.resolve();
+    depth = 0;
+    maxDepth;
+    constructor(maxDepth = DEFAULT_ADMISSION_QUEUE_MAX_DEPTH) {
+        this.maxDepth = maxDepth;
+    }
+    run(task) {
+        if (this.depth >= this.maxDepth) {
+            return Promise.reject(new SerialQueueFullError(this.maxDepth));
+        }
+        this.depth += 1;
+        const result = this.tail.then(() => task());
+        this.tail = result.then(() => undefined, () => undefined);
+        void result.then(() => { this.depth -= 1; }, () => { this.depth -= 1; });
+        return result;
+    }
+    /** True when no task is queued or running. */
+    get idle() {
+        return this.depth === 0;
+    }
+}
 /**
  * Build a grammY bot that routes authorized text messages to an agent responder.
  *
@@ -12,10 +114,12 @@ const DEFAULT_INITIAL_STATUS_TEXT = "Thinking…";
  * Middleware order is: authorization gate → `/start` `/help` `/cancel` commands →
  * agent run handler (`message:text`) → unsupported fallback (other messages).
  *
- * Per-chat concurrency is guarded by an `activeRuns` map: a run is recorded
- * synchronously at handler entry, so a second message arriving for the same chat
- * mid-run gets a "busy" reply rather than starting a competing run. The long run
- * is intentionally NOT sequentialized, which is what makes "busy" reachable.
+ * Concurrency is NOT rejected per chat. Every message is handed to the responder,
+ * which routes through the runtime harness; the harness serializes per
+ * conversation (queue-after-turn follow-ups answered on the warm session). For
+ * each in-flight message the bot tracks an `AbortController` in a per-chat set so
+ * `/cancel` can abort every live turn for the chat (in addition to clearing
+ * queued follow-ups via `responder.cancel`).
  */
 export function createTelegramBot(options) {
     const allowAllChats = options.allowAllChats === true;
@@ -26,10 +130,138 @@ export function createTelegramBot(options) {
     const messages = { ...DEFAULT_MESSAGES, ...options.messages };
     const logger = options.logger;
     const initialStatusText = options.stream?.initialStatusText ?? DEFAULT_INITIAL_STATUS_TEXT;
-    const activeRuns = new Map();
-    const bot = options.botFactory?.(options.botToken) ?? new Bot(options.botToken);
+    // Per-chat set of AbortControllers for in-flight messages. The runtime harness
+    // serializes turns per conversation, so we never reject concurrent messages —
+    // we only track them so `/cancel` can abort every live turn for the chat.
+    const activeControllers = new Map();
+    /**
+     * Create and register a fresh AbortController for a chat BEFORE the turn is
+     * admitted to the per-chat queue. Registering eagerly means a /cancel can abort
+     * a message that is still parked behind an earlier run (the controller would
+     * otherwise not exist until the queue reached its runAgentTurn).
+     */
+    function registerController(chatId) {
+        const key = String(chatId);
+        const controller = new AbortController();
+        const controllers = activeControllers.get(key);
+        if (controllers === undefined) {
+            activeControllers.set(key, new Set([controller]));
+        }
+        else {
+            controllers.add(controller);
+        }
+        return controller;
+    }
+    /** Remove a controller from a chat's active set (no-op if already gone). */
+    function unregisterController(chatId, controller) {
+        const key = String(chatId);
+        const set = activeControllers.get(key);
+        if (set !== undefined) {
+            set.delete(controller);
+            if (set.size === 0) {
+                activeControllers.delete(key);
+            }
+        }
+    }
+    // Per-conversation admission queue. grammY (via @grammyjs/runner) dispatches
+    // updates concurrently, and the pre-respond work (status + attachment download)
+    // is variable latency, so without this a later text-only message could reach
+    // responder.respond() (and the harness FIFO) before an earlier still-downloading
+    // media message in the same chat — and many same-chat downloads would run
+    // unbounded. We serialize runAgentTurn per chat to preserve arrival order and
+    // bound concurrent same-chat downloads. /cancel stays out-of-band (it never
+    // enters this queue, so a queued turn can never block cancellation).
+    const admissionQueues = new Map();
+    // Set in stop() so a pending album timer (or a late update) cannot fire a turn
+    // after the channel was torn down. Mirrors the slack/whatsapp adapters.
+    let stopped = false;
+    const albumBuffers = new Map();
+    const noopAlbumWork = () => Promise.resolve();
+    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);
+        const controllers = activeControllers.get(String(chatId));
+        if (controllers !== undefined) {
+            for (const controller of controllers) {
+                controller.abort(new Error("Cancelled by Telegram user."));
+            }
+        }
+        // Drop any album still buffering for this chat so /cancel does not leave it
+        // to fire a turn after the user asked to stop. Settle the reserved admission
+        // slot with a no-op so the parked admit() task does not hang the per-chat
+        // queue. (Its eager controller was just aborted in the loop above.)
+        for (const [key, buffer] of albumBuffers) {
+            if (key.startsWith(`${String(chatId)}:`)) {
+                clearTimeout(buffer.timer);
+                albumBuffers.delete(key);
+                buffer.ready.resolve(noopAlbumWork);
+                unregisterController(chatId, buffer.controller);
+            }
+        }
+    };
+    // 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) {
@@ -50,40 +282,336 @@ export function createTelegramBot(options) {
     bot.command("cancel", async (ctx) => {
         const chatId = ctx.chat?.id;
         if (chatId !== undefined) {
-            activeRuns.get(String(chatId))?.controller.abort(new Error("Cancelled by Telegram user."));
+            cancelChat(chatId);
         }
         await ctx.reply(messages.cancelledText);
     });
-    bot.on("message:text", async (ctx) => {
-        await handleAgentMessage(ctx);
-    });
+    // 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
+    // filter — so a later text message (matched by the first `message:text` filter)
+    // could overtake an earlier document/photo (filtered one step further) before
+    // admission, breaking arrival order. handleAgentMessage routes supported types
+    // and replies unsupportedText for the rest (normalizeTelegramMessageInput
+    // returns undefined), so a single `message` handler covers both cases.
     bot.on("message", async (ctx) => {
-        await ctx.reply(messages.unsupportedText);
+        await handleAgentMessage(ctx);
     });
+    /**
+     * Run a turn through the per-chat admission queue so same-chat turns serialize
+     * (preserving harness FIFO arrival order and bounding concurrent same-chat
+     * downloads). Cross-chat concurrency is preserved because queues are keyed per
+     * chat id (the same key /cancel uses for activeControllers).
+     *
+     * The queue is bounded: a same-chat flood past the depth cap is rejected by
+     * SerialQueue.run BEFORE the task enters the chain, so the over-cap message is
+     * never admitted. On that rejected path the task body never runs — its eager
+     * controller (and, for an album, its reserved slot) never reach the cleanup in
+     * runAgentTurn/flushAlbum — so the caller supplies an `onReject` callback to
+     * settle/unregister those eagerly-created resources, after which we reply with
+     * the busy terminal instead of admitting an unbounded backlog.
+     */
+    async function admit(chatId, task, onReject) {
+        const key = String(chatId);
+        let queue = admissionQueues.get(key);
+        if (queue === undefined) {
+            queue = new SerialQueue();
+            admissionQueues.set(key, queue);
+        }
+        try {
+            await queue.run(task);
+        }
+        catch (error) {
+            if (isSerialQueueFullError(error)) {
+                await onReject?.();
+                return;
+            }
+            throw error;
+        }
+        finally {
+            if (queue.idle && admissionQueues.get(key) === queue) {
+                admissionQueues.delete(key);
+            }
+        }
+    }
     async function handleAgentMessage(ctx) {
+        if (stopped) {
+            return;
+        }
         const message = ctx.message;
         const chatId = ctx.chat?.id;
         if (message === undefined || chatId === undefined) {
             return;
         }
-        const text = (message.text ?? "").trim();
-        if (text.length === 0) {
+        const telegramMessage = message;
+        // A multi-photo/video album arrives as several messages sharing a
+        // media_group_id; buffer them and flush once so the agent sees one request
+        // with every attachment instead of N single-attachment turns.
+        const groupId = telegramMessage.media_group_id;
+        if (typeof groupId === "string" && groupId.length > 0) {
+            bufferAlbumMessage(ctx, chatId, groupId, telegramMessage);
+            return;
+        }
+        const captionCommand = controlCommandFromCaption(telegramMessage, ctx.me.username);
+        if (captionCommand !== undefined) {
+            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);
             return;
         }
-        const key = String(chatId);
-        if (activeRuns.has(key)) {
+        // Register the controller before admission so /cancel can abort this message
+        // even while it is still parked behind an earlier same-chat run.
+        const controller = registerController(chatId);
+        await admit(chatId, () => runAgentTurn(ctx, telegramMessage, input, controller), 
+        // Over-cap: the task was rejected before entering the queue, so runAgentTurn
+        // (and its finally) never ran. Unregister the eagerly created controller so
+        // it does not leak in activeControllers, then reply with the busy terminal.
+        async () => {
+            unregisterController(chatId, controller);
             await ctx.reply(messages.busyText);
+        });
+    }
+    function bufferAlbumMessage(ctx, chatId, groupId, message) {
+        const key = `${String(chatId)}:${groupId}`;
+        const schedule = () => {
+            const timer = setTimeout(() => {
+                void flushAlbum(key);
+            }, albumDelayMs);
+            timer.unref?.();
+            return timer;
+        };
+        const existing = albumBuffers.get(key);
+        if (existing === undefined) {
+            // First part of a new album: reserve a per-chat admission slot NOW so a
+            // later same-chat message cannot overtake the album. Register the eager
+            // controller (so /cancel can abort a parked album) and admit a task that
+            // blocks on `ready.promise` — flushAlbum settles it with the real work
+            // after the quiet window. The slot blocks only on the album timer, which
+            // fires independently of queue progress, so there is no deadlock.
+            const controller = registerController(chatId);
+            const ready = createDeferred();
+            const timer = schedule();
+            albumBuffers.set(key, { ctx, messages: [message], timer, controller, ready });
+            void admit(chatId, async () => {
+                const work = await ready.promise;
+                await work();
+            }, 
+            // Over-cap: the reserved album slot was rejected before entering the
+            // queue, so flushAlbum's later run/settle never executes for it. Drop the
+            // buffered album (clear its timer, remove it, settle the deferred), and
+            // unregister the eager controller so it does not leak; then reply busy.
+            async () => {
+                const buffered = albumBuffers.get(key);
+                if (buffered !== undefined) {
+                    clearTimeout(buffered.timer);
+                    albumBuffers.delete(key);
+                    buffered.ready.resolve(noopAlbumWork);
+                }
+                else {
+                    ready.resolve(noopAlbumWork);
+                }
+                unregisterController(chatId, controller);
+                await ctx.reply(messages.busyText);
+            });
             return;
         }
-        // Record the run synchronously, before any await, so a concurrent message for
-        // the same chat observes it and gets the "busy" reply above.
-        const controller = new AbortController();
-        const activeRun = { controller };
-        activeRuns.set(key, activeRun);
-        const request = buildAgentRequest(ctx.update, message, text, controller.signal);
+        existing.messages.push(message);
+        clearTimeout(existing.timer);
+        existing.timer = schedule();
+    }
+    async function flushAlbum(key) {
+        const buffer = albumBuffers.get(key);
+        if (buffer === undefined) {
+            return;
+        }
+        albumBuffers.delete(key);
+        const { ctx, messages: parts, controller, ready } = buffer;
+        const albumChatId = ctx.chat?.id;
+        // The reserved admission slot is parked on `ready.promise`. EVERY exit below
+        // must settle it (with real work or a no-op) or the per-chat queue hangs
+        // forever. On a no-op exit, the eager controller never reaches runAgentTurn's
+        // finally, so unregister it here to avoid leaking it in activeControllers; on
+        // the run path it is reused (do not re-register) and runAgentTurn owns cleanup.
+        const settleAsNoop = () => {
+            ready.resolve(noopAlbumWork);
+            if (albumChatId !== undefined) {
+                unregisterController(albumChatId, controller);
+            }
+        };
+        if (stopped) {
+            settleAsNoop();
+            return;
+        }
+        // A control command in any album caption controls the chat. The album itself
+        // does not run, so settle the reserved slot with a no-op.
+        for (const part of parts) {
+            const command = controlCommandFromCaption(part, ctx.me.username);
+            if (command !== undefined) {
+                settleAsNoop();
+                await handleControlCommand(ctx, command);
+                return;
+            }
+        }
+        const primary = parts[0];
+        const input = mergeTelegramMessageInputs(parts);
+        if (primary === undefined || input === undefined) {
+            settleAsNoop();
+            await ctx.reply(messages.unsupportedText);
+            return;
+        }
+        // Fill the reserved slot with the real run so the album executes in its
+        // arrival-order position (a later same-chat text admitted after this album
+        // started buffering lands behind this slot).
+        ready.resolve(() => runAgentTurn(ctx, primary, input, controller));
+    }
+    async function runAgentTurn(ctx, message, input, controller) {
+        const chatId = message.chat.id;
+        // The AbortController is created and registered in activeControllers by the
+        // caller BEFORE admission, so a /cancel can abort a message still parked in the
+        // per-chat queue (the controller would otherwise not exist until the queue
+        // reached this run). This function owns unregistering it in the finally below.
+        // Download attachment bytes (best-effort) before handing the request to the
+        // responder. Failures skip the attachment; the run proceeds regardless. The
+        // download is tied to this message's abort signal.
+        let resolvedAttachments = [];
+        if (input.attachments.length > 0 && !controller.signal.aborted) {
+            const downloadOptions = {
+                ...options.attachments,
+                ...(logger !== undefined ? { logger } : {}),
+            };
+            resolvedAttachments = await downloadTelegramAttachments(input.attachments, fileDownloader, controller.signal, downloadOptions);
+        }
+        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);
             }
@@ -93,6 +621,7 @@ export function createTelegramBot(options) {
                 });
             }
             if (controller.signal.aborted) {
+                reactionOutcome = "cancelled";
                 await finishSafely(stream, messages.cancelledText, logger);
                 return;
             }
@@ -102,6 +631,7 @@ export function createTelegramBot(options) {
             }
             catch (error) {
                 if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    reactionOutcome = "cancelled";
                     await finishSafely(stream, messages.cancelledText, logger);
                     return;
                 }
@@ -116,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.
@@ -133,18 +666,189 @@ export function createTelegramBot(options) {
             }
         }
         finally {
-            if (activeRuns.get(key) === activeRun) {
-                activeRuns.delete(key);
+            // 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);
         }
     }
-    function buildStreamOptions(chatId, replyToMessageId, signal) {
+    /**
+     * 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);
+            return;
+        }
+        if (command === "help") {
+            await ctx.reply(messages.helpText);
+            return;
+        }
+        const chatId = ctx.chat?.id;
+        if (chatId !== undefined) {
+            cancelChat(chatId);
+        }
+        await ctx.reply(messages.cancelledText);
+    }
+    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;
@@ -167,6 +871,9 @@ export function createTelegramBot(options) {
         if (tuning?.showThoughts !== undefined) {
             streamOptions.showThoughts = tuning.showThoughts;
         }
+        if (tuning?.showHints !== undefined) {
+            streamOptions.showHints = tuning.showHints;
+        }
         if (tuning?.formatMarkdown !== undefined) {
             streamOptions.formatMarkdown = tuning.formatMarkdown;
         }
@@ -176,39 +883,584 @@ 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()) {
+                total += set.size;
+            }
+            return total;
+        },
         async start() {
             if (runnerHandle?.isRunning() === true) {
                 return;
             }
+            // Re-arm message handling on a genuine (re)start: a prior stop() latches
+            // `stopped = true`, and handleAgentMessage/flushAlbum early-return while it
+            // is set. Resetting here (after the already-running no-op guard, before any
+            // 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
+                // hang the per-chat queue after teardown (no turn fires: stopped guard +
+                // no-op work).
+                buffer.ready.resolve(noopAlbumWork);
+            }
+            albumBuffers.clear();
             if (runnerHandle?.isRunning() === true) {
                 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) {
     return error instanceof Error ? error.message : String(error);
 }
+/** A promise plus its resolver, for an externally-settled deferred value. */
+function createDeferred() {
+    let resolve = () => undefined;
+    const promise = new Promise((innerResolve) => {
+        resolve = innerResolve;
+    });
+    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
+ * (`https://api.telegram.org/file/bot<token>/<file_path>`) with `fetch`. Both
+ * calls honor the request abort signal.
+ *
+ * The download is hardened against oversized/stale-`file_size` bodies: a
+ * `Content-Length` header over the cap is rejected before reading the body, and
+ * the body is streamed with a running byte counter that cancels the reader the
+ * moment the cap is exceeded (so the whole payload is never buffered first). A
+ * `downloadTimeoutMs` timer is composed with the run signal so a stalled
+ * transfer is bounded by a dedicated timeout, not just the overall run.
+ */
+function createDefaultFileDownloader(bot, token, options) {
+    const timeoutMs = options?.downloadTimeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS;
+    return {
+        async resolveFilePath(fileId, signal) {
+            const file = await bot.api.getFile(fileId, signal);
+            return file.file_path;
+        },
+        async download(filePath, signal, maxBytes) {
+            // 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 });
+                if (!response.ok) {
+                    throw new Error(`Telegram file download failed with status ${response.status}.`);
+                }
+                // Early skip: a declared Content-Length over the cap means we never read
+                // the body at all (the adapter turns the throw into a logged skip).
+                if (maxBytes !== undefined) {
+                    const declared = Number.parseInt(response.headers.get("content-length") ?? "", 10);
+                    if (Number.isFinite(declared) && declared > maxBytes) {
+                        throw new Error("Telegram file exceeded the configured byte cap (Content-Length).");
+                    }
+                }
+                return await readBodyWithCap(response, maxBytes);
+            }
+            finally {
+                cleanup();
+            }
+        },
+    };
+}
+/**
+ * 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
+ * forwarding listener) in every path so no timer leaks/keeps the loop alive.
+ */
+function composeDownloadSignal(externalSignal, timeoutMs) {
+    const shouldUseTimeout = Number.isFinite(timeoutMs) && timeoutMs > 0;
+    if (!shouldUseTimeout) {
+        if (externalSignal === undefined) {
+            return { cleanup: () => undefined };
+        }
+        return { signal: externalSignal, cleanup: () => undefined };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort(new Error("Telegram file download timed out."));
+    }, timeoutMs);
+    timer.unref?.();
+    const forwardAbort = () => {
+        controller.abort(externalSignal?.reason);
+    };
+    if (externalSignal !== undefined) {
+        if (externalSignal.aborted) {
+            forwardAbort();
+        }
+        else {
+            externalSignal.addEventListener("abort", forwardAbort, { once: true });
+        }
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timer);
+            externalSignal?.removeEventListener("abort", forwardAbort);
+        },
+    };
+}
+/**
+ * Read a response body into a single `Uint8Array`, rejecting once `maxBytes` is
+ * exceeded. Streams the body where possible so an oversized file is abandoned
+ * without buffering the whole thing; falls back to an `arrayBuffer()` read (still
+ * cap-checked) when the runtime exposes no readable stream.
+ */
+async function readBodyWithCap(response, maxBytes) {
+    const cap = maxBytes !== undefined && Number.isFinite(maxBytes) && maxBytes >= 0 ? maxBytes : undefined;
+    const body = response.body;
+    if (body === null || typeof body.getReader !== "function") {
+        const buffer = await response.arrayBuffer();
+        const bytes = new Uint8Array(buffer);
+        if (cap !== undefined && bytes.byteLength > cap) {
+            throw new Error("Telegram file exceeded the configured byte cap.");
+        }
+        return bytes;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (value === undefined) {
+                continue;
+            }
+            total += value.byteLength;
+            if (cap !== undefined && total > cap) {
+                await reader.cancel();
+                throw new Error("Telegram file exceeded the configured byte cap.");
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    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;
+    }
+    const match = message.caption.trim().match(/^\/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s|$)/u);
+    const command = match?.[1]?.toLowerCase();
+    const target = match?.[2]?.toLowerCase();
+    if (target !== undefined) {
+        if (botUsername === undefined || target !== botUsername.toLowerCase()) {
+            return undefined;
+        }
+    }
+    return command === "start" || command === "help" || command === "cancel"
+        ? command
+        : undefined;
+}
 //# sourceMappingURL=bot.js.map