@mono-agent/telegram-adapter 0.3.0 → 0.4.0

package/dist/bot.js

@@ -1,10 +1,64 @@
 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 { 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;
+// 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 +66,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,9 +82,87 @@ 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();
+    // 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)}`;
+        // 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);
+            }
+        }
+    };
     const bot = options.botFactory?.(options.botToken) ?? new Bot(options.botToken);
     const sender = createGrammyTelegramApi(bot.api);
+    const fileDownloader = options.fileDownloaderFactory?.(bot, options.botToken) ??
+        createDefaultFileDownloader(bot, options.botToken, {
+            ...(options.attachments?.downloadTimeoutMs !== undefined
+                ? { downloadTimeoutMs: options.attachments.downloadTimeoutMs }
+                : {}),
+            ...(logger !== undefined ? { logger } : {}),
+        });
     const isAuthorized = (chatId) => chatId !== undefined && (allowAllChats || allowedChatIds.has(String(chatId)));
     bot.use(async (ctx, next) => {
         const chatId = ctx.chat?.id;
@@ -50,40 +184,218 @@ 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);
-    });
+    // 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;
+        }
+        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));
         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) {
+                await finishSafely(stream, messages.cancelledText, logger);
+                return;
+            }
             try {
                 await stream.status(initialStatusText);
             }
@@ -133,17 +445,33 @@ export function createTelegramBot(options) {
             }
         }
         finally {
-            if (activeRuns.get(key) === activeRun) {
-                activeRuns.delete(key);
-            }
+            unregisterController(chatId, controller);
         }
     }
+    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) {
         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,
         };
         const tuning = options.stream;
         if (tuning?.initialStatusText !== undefined) {
@@ -167,6 +495,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;
         }
@@ -178,10 +509,23 @@ export function createTelegramBot(options) {
     let runnerHandle;
     return {
         bot,
+        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;
             if ((options.deleteWebhookOnStart ?? true) === true) {
                 await bot.api.deleteWebhook({ drop_pending_updates: options.dropPendingUpdates ?? false });
             }
@@ -197,6 +541,18 @@ export function createTelegramBot(options) {
             });
         },
         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;
+            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();
             }
@@ -211,4 +567,158 @@ export function createTelegramBot(options) {
 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;
+/**
+ * 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) {
+            const url = `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();
+            }
+        },
+    };
+}
+/**
+ * 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;
+}
+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