@spinabot/brigade 1.0.2 → 1.2.0

package/dist/agents/channels/telegram/connection.js

@@ -0,0 +1,865 @@
+/**
+ * Telegram Bot API connection (grammY long-polling).
+ *
+ * The Brigade analogue of `whatsapp/connection.ts`, distilled from the
+ * reference Telegram polling session. grammY + its runner + the throttler transformer are
+ * HEAVY and only needed when a Telegram channel actually starts, so they are
+ * lazy-imported here (`await import("grammy")` inside `connectTelegram`) — a
+ * non-Telegram boot never pays for them. Types are `type`-only so the static
+ * import never pulls the runtime in.
+ *
+ * Lifecycle:
+ *   - `deleteWebhook({ drop_pending_updates: false })` is called BEFORE polling.
+ *     If a webhook was ever set on this bot, `getUpdates` returns 409 forever
+ *     and the bot silently "receives nothing" — clearing it first is the #1 fix.
+ *   - `getMe` caches the bot's numeric id + @username (the group ACL needs the
+ *     username to detect @-mentions; without it group messages never reach the
+ *     agent).
+ *   - `bot.on("message")` normalizes each update into a `TgInboundMessage` and
+ *     hands it to `onMessage` with a DEFERRED `resolveMedia` thunk — bytes are
+ *     downloaded only after the central access gate admits the sender (mirrors
+ *     WhatsApp).
+ *   - The grammY runner drives `getUpdates`; `apiThrottler()` rate-limits the
+ *     outbound API.
+ *   - Reconnect backoff COPIES WhatsApp's constants (2s → 30s, ×1.8, ±25%).
+ *   - 401 Unauthorized → sticky `tokenInvalid` (terminal; the only fix is a new
+ *     token — stop polling).
+ *   - 409 Conflict (getUpdates) → another poller/webhook is live: clear the
+ *     webhook and restart ONCE, then fall back to normal backoff.
+ *   - Updates are de-duplicated by `update_id` (a redelivered update after a
+ *     restart must not double-run the agent).
+ *
+ * Scope cut (v1): `callback_query` (inline-button taps) is intentionally NOT
+ * subscribed — Brigade's approvals are central TEXT replies handled in
+ * `inbound-pipeline.ts`, so `allowed_updates` only needs message updates.
+ */
+import { createDedupeCache, nextBackoffDelay, } from "../sdk.js";
+import { resolveTelegramAllowedUpdates } from "./allowed-updates.js";
+import { buildTelegramSenderName, extractTelegramMentions, extractTelegramReplyContext, extractTelegramText, hasInboundMedia, resolveInboundMediaFileId, resolveInboundMediaKind, telegramChatType, telegramThreadId, } from "./inbound-extras.js";
+import { downloadTelegramMedia } from "./media.js";
+// All contract types — `OutboundMedia`, `InboundMediaAttachment`,
+// `InboundReplyContext` — now come from the channel SDK barrel (imported above),
+// so this channel is built entirely on `../sdk.js`.
+/* ───────────────────────── reconnect backoff ───────────────────────── */
+// Shares the neutral `nextBackoffDelay` curve with every other channel (see
+// `channels/backoff.ts`), tuned to the same schedule WhatsApp uses (2s → 30s,
+// ×1.8, ±25%). The constants live here so Telegram owns its own knobs; the
+// arithmetic is the shared helper's.
+const RECONNECT_INITIAL_MS = 2_000;
+const RECONNECT_MAX_MS = 30_000;
+const RECONNECT_FACTOR = 1.8;
+const RECONNECT_JITTER = 0.25;
+const RECONNECT_MAX_ATTEMPTS = 12;
+/**
+ * Jittered exponential backoff for reconnect attempt `attempt` (0-based).
+ * Thin wrapper over the neutral `nextBackoffDelay` helper — kept as a named
+ * export so `index.ts` and the connection tests have a stable entry point.
+ */
+export function telegramBackoffDelay(attempt) {
+    return nextBackoffDelay({
+        attempt,
+        initialMs: RECONNECT_INITIAL_MS,
+        maxMs: RECONNECT_MAX_MS,
+        factor: RECONNECT_FACTOR,
+        jitter: RECONNECT_JITTER,
+    });
+}
+/* ───────────────────────── error classification ───────────────────────── */
+/** Pull a Telegram `error_code` off any thrown shape (grammY GrammyError or raw). */
+function errorCode(err) {
+    if (!err || typeof err !== "object")
+        return undefined;
+    const e = err;
+    return e.error_code ?? e.errorCode;
+}
+/** Description / message text off any thrown shape. */
+function errorText(err) {
+    if (!err)
+        return "";
+    if (typeof err === "string")
+        return err;
+    const e = err;
+    return e.description ?? e.message ?? String(err);
+}
+/** 401 Unauthorized → the bot token is wrong / revoked (terminal). */
+export function isTelegramUnauthorized(err) {
+    if (errorCode(err) === 401)
+        return true;
+    return /unauthorized/i.test(errorText(err));
+}
+/** 409 Conflict on getUpdates → another poller or a webhook is active. */
+export function isTelegramGetUpdatesConflict(err) {
+    if (errorCode(err) !== 409)
+        return false;
+    return /conflict|getupdates|webhook|terminated by other/i.test(errorText(err));
+}
+/** Strip a bot token out of any string before it reaches a log. */
+export function redactTelegramToken(text, token) {
+    if (!text)
+        return text;
+    let out = text;
+    if (token)
+        out = out.split(token).join("<redacted>");
+    // Catch `bot<digits>:<base64ish>` URL fragments even if the exact token differs.
+    out = out.replace(/bot\d{6,}:[A-Za-z0-9_-]{20,}/g, "bot<redacted>");
+    return out;
+}
+/* ───────────────────────── the connection ───────────────────────── */
+export async function connectTelegram(args) {
+    const accountId = args.accountId ?? "default";
+    const mode = args.mode === "webhook" ? "webhook" : "polling";
+    const sleep = args.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms).unref?.()));
+    const safeLog = (msg, meta) => {
+        // Defensively redact the token from any message + string meta values.
+        const redactedMsg = redactTelegramToken(msg, args.token);
+        if (!meta)
+            return args.log(redactedMsg);
+        const redactedMeta = {};
+        for (const [k, v] of Object.entries(meta)) {
+            redactedMeta[k] = typeof v === "string" ? redactTelegramToken(v, args.token) : v;
+        }
+        args.log(redactedMsg, redactedMeta);
+    };
+    // ── lazy-load grammY + runner + throttler (production path only) ──
+    let buildBot;
+    let buildRunner;
+    if (args.botFactory && args.runnerFactory) {
+        buildBot = args.botFactory;
+        buildRunner = args.runnerFactory;
+    }
+    else {
+        const grammy = await import("grammy");
+        const { run } = await import("@grammyjs/runner");
+        const { apiThrottler } = await import("@grammyjs/transformer-throttler");
+        buildBot = (token) => {
+            const bot = new grammy.Bot(token);
+            // Rate-limit the outbound API so a chatty agent never trips Telegram's
+            // flood limits — installed on the api config as a transformer.
+            bot.api.config?.use(apiThrottler());
+            return bot;
+        };
+        buildRunner = (bot) => run(bot, {
+            // Subscribe `message` (text/media) + `callback_query` (inline-button
+            // approval presses) — the minimal set Brigade's central pipeline
+            // consumes. Widen via `args.allowedUpdates` (e.g. inbound reactions).
+            // Cast: the resolver returns a strict subset of grammY's update union,
+            // but `args.allowedUpdates` is a plain `string[]`.
+            runner: { fetch: { allowed_updates: allowedUpdates } },
+        });
+    }
+    // The `allowed_updates` list to request — defaults to message + callback_query.
+    const allowedUpdates = args.allowedUpdates && args.allowedUpdates.length > 0
+        ? args.allowedUpdates
+        : resolveTelegramAllowedUpdates();
+    // ── connection state ──
+    let selfId = null;
+    let selfUsername = null;
+    let selfIdentity = null;
+    let connectedAtMs = null;
+    let connected = false;
+    let tokenInvalid = false;
+    let closed = false;
+    let webhookCleared = false;
+    let conflictRestartUsed = false;
+    let reconnectAttempts = 0;
+    let bot = null;
+    let runner = null;
+    let loopPromise = null;
+    // Dedupe inbound updates by `update_id` — a redelivered update after a
+    // restart must not double-run the agent. Per-connection lifetime.
+    const updateDedupe = createDedupeCache({ maxEntries: 10_000, ttlMs: 60 * 60 * 1_000 });
+    /** Normalize one grammY message into the deferred-media inbound shape. */
+    const normalize = (message) => {
+        const chatId = String(message.chat.id);
+        const text = extractTelegramText(message);
+        const chatType = telegramChatType(message);
+        const threadId = telegramThreadId(message);
+        const mentions = extractTelegramMentions(message, selfUsername ?? undefined, selfId ?? undefined);
+        const replyTo = extractTelegramReplyContext(message);
+        const fromName = buildTelegramSenderName(message);
+        const fromId = typeof message.from?.id === "number" ? String(message.from.id) : chatId;
+        const tsSec = typeof message.date === "number" ? message.date : 0;
+        // DEFERRED media — captured by reference, not downloaded. The thunk is only
+        // invoked by the pipeline after the access gate admits the sender.
+        const carriesMedia = hasInboundMedia(message);
+        const resolveMedia = carriesMedia
+            ? async () => {
+                const fileId = resolveInboundMediaFileId(message);
+                const kind = resolveInboundMediaKind(message);
+                if (!fileId || !kind || !bot)
+                    return [];
+                const caption = typeof message.caption === "string" ? message.caption : undefined;
+                const fileName = message.document?.file_name ?? message.audio?.file_name ?? message.video?.file_name;
+                const att = await downloadTelegramMedia({
+                    bot: bot.api,
+                    fileId,
+                    kind,
+                    token: args.token,
+                    caption,
+                    fileName,
+                    log: safeLog,
+                });
+                return att ? [att] : [];
+            }
+            : undefined;
+        return {
+            conversationId: chatId,
+            messageId: typeof message.message_id === "number" ? String(message.message_id) : undefined,
+            messageTimestampMs: tsSec > 0 ? tsSec * 1000 : undefined,
+            from: fromId,
+            fromName,
+            text,
+            chatType,
+            threadId,
+            mentions: mentions.length > 0 ? mentions : undefined,
+            replyTo,
+            resolveMedia,
+            raw: message,
+        };
+    };
+    const onUpdate = (ctx) => {
+        try {
+            const updateId = ctx.update?.update_id;
+            if (typeof updateId === "number" && !updateDedupe.claim(String(updateId)))
+                return; // already seen
+            const message = ctx.message ?? ctx.update?.message;
+            if (!message)
+                return;
+            // Ignore the bot's own outbound echoes (a bot never sees its own sends
+            // via getUpdates, but a linked-account self-message would carry our id).
+            if (typeof message.from?.id === "number" && selfId && String(message.from.id) === selfId)
+                return;
+            args.onMessage(normalize(message));
+        }
+        catch (err) {
+            safeLog("telegram inbound handler error", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    /**
+     * Normalize a `callback_query` (inline-button press) into the inbound shape
+     * the central pipeline routes to the approval-callback path. The button's
+     * `data` rides on `callbackQuery`; `conversationId` / `from` / `threadId`
+     * come from the message the button was attached to so the pending-approval
+     * lookup keys on the SAME peer the prompt was sent to.
+     */
+    const normalizeCallback = (cb) => {
+        const data = typeof cb.data === "string" ? cb.data : "";
+        if (!data)
+            return null; // a button with no payload is not an approval press
+        const msg = cb.message;
+        const chatId = msg?.chat?.id !== undefined ? String(msg.chat.id) : cb.from?.id !== undefined ? String(cb.from.id) : "";
+        if (!chatId)
+            return null;
+        const fromId = typeof cb.from?.id === "number" ? String(cb.from.id) : chatId;
+        const fromName = cb.from
+            ? [cb.from.first_name, cb.from.last_name].filter(Boolean).join(" ").trim() ||
+                (cb.from.username ? `@${cb.from.username}` : undefined)
+            : undefined;
+        const threadId = msg ? telegramThreadId(msg) : undefined;
+        const chatType = msg ? telegramChatType(msg) : "direct";
+        return {
+            conversationId: chatId,
+            from: fromId,
+            ...(fromName ? { fromName } : {}),
+            text: "",
+            chatType,
+            ...(threadId ? { threadId } : {}),
+            callbackQuery: { data, callbackId: cb.id },
+            raw: (msg ?? cb),
+        };
+    };
+    const onCallbackQuery = async (ctx) => {
+        try {
+            const updateId = ctx.update?.update_id;
+            if (typeof updateId === "number" && !updateDedupe.claim(String(updateId)))
+                return; // already seen
+            const cb = ctx.callbackQuery ?? ctx.update.callback_query;
+            if (!cb)
+                return;
+            // ACK first — clears the client-side loading spinner immediately (no text,
+            // matching the reference). Best-effort: a failed ack must not block routing.
+            try {
+                await ctx.answerCallbackQuery();
+            }
+            catch {
+                /* ack is cosmetic */
+            }
+            const normalized = normalizeCallback(cb);
+            if (!normalized)
+                return;
+            args.onCallbackQuery?.(normalized);
+        }
+        catch (err) {
+            safeLog("telegram callback handler error", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    /** Build a bot, wire handlers, getMe, clear webhook, sync commands, start runner. */
+    const startOnce = async () => {
+        const b = buildBot(args.token);
+        b.on("message", onUpdate);
+        // Subscribe inline-button presses (interactive approvals). grammY hands a
+        // per-update `answerCallbackQuery` helper on the ctx; the handler acks via
+        // it then routes the normalized callback inbound.
+        b.on("callback_query", (ctx) => void onCallbackQuery(ctx));
+        bot = b;
+        // getMe first — both proves the token (401 surfaces here) and caches the
+        // bot id + username the group ACL needs (+ the full identity for the probe).
+        const me = await b.api.getMe();
+        selfId = String(me.id);
+        selfUsername = me.username ?? null;
+        selfIdentity = me;
+        // Clear any webhook BEFORE polling — the #1 "receives nothing" cause. Do
+        // not drop pending updates (the operator may want queued messages). Once
+        // cleared we don't re-clear on every reconnect.
+        if (!webhookCleared) {
+            await b.api.deleteWebhook({ drop_pending_updates: false });
+            webhookCleared = true;
+        }
+        // Register the bot's `/` command menu (best-effort — a failed sync must not
+        // block polling). Re-applied on each (re)connect so an edited command set
+        // lands after a gateway restart.
+        if (args.commandMenu && args.commandMenu.length > 0 && b.api.setMyCommands) {
+            try {
+                await b.api.setMyCommands(args.commandMenu);
+            }
+            catch (err) {
+                safeLog("telegram setMyCommands failed (cosmetic)", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        const r = buildRunner(b);
+        runner = r;
+        return r;
+    };
+    /**
+     * Feed a raw update into the inbound path. In webhook mode the gateway HTTP
+     * route calls this with each POSTed `Update`; it dispatches to the same
+     * message / callback_query handlers polling uses (so dedupe + normalize +
+     * ack are identical). grammY's polling ctx supplies a per-update
+     * `answerCallbackQuery`; in webhook mode we synthesise one off `bot.api`.
+     */
+    const feedUpdate = (update) => {
+        const message = update.message;
+        if (message) {
+            onUpdate({ update, message });
+            return;
+        }
+        const callbackQuery = update.callback_query;
+        if (callbackQuery) {
+            void onCallbackQuery({
+                update,
+                callbackQuery,
+                answerCallbackQuery: async (opts) => {
+                    const b = bot;
+                    if (!b?.api.answerCallbackQuery)
+                        return;
+                    await b.api.answerCallbackQuery(callbackQuery.id, opts);
+                },
+            });
+        }
+    };
+    /**
+     * Webhook transport start: build the bot, getMe, sync commands, then register
+     * the webhook (when a url was supplied) so Telegram POSTs updates to the
+     * gateway route. Does NOT poll — inbound arrives via {@link feedUpdate}.
+     */
+    const startWebhook = async () => {
+        const b = buildBot(args.token);
+        // We don't subscribe via b.on(...) in webhook mode — feedUpdate dispatches
+        // directly — but wiring the handlers is harmless and keeps parity if a
+        // future grammy webhookCallback is adopted.
+        bot = b;
+        const me = await b.api.getMe();
+        selfId = String(me.id);
+        selfUsername = me.username ?? null;
+        selfIdentity = me;
+        if (args.commandMenu && args.commandMenu.length > 0 && b.api.setMyCommands) {
+            try {
+                await b.api.setMyCommands(args.commandMenu);
+            }
+            catch (err) {
+                safeLog("telegram setMyCommands failed (cosmetic)", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        const url = args.webhook?.url?.trim();
+        if (url && b.api.setWebhook) {
+            const opts = { allowed_updates: allowedUpdates };
+            if (args.webhook?.secretToken)
+                opts.secret_token = args.webhook.secretToken;
+            await b.api.setWebhook(url, opts);
+            safeLog("telegram webhook registered", { account: accountId });
+        }
+        else {
+            safeLog("telegram webhook mode — no url configured; inbound only via gateway route", {
+                account: accountId,
+            });
+        }
+        connected = true;
+        connectedAtMs = Date.now();
+        reconnectAttempts = 0;
+        args.onConnected?.();
+    };
+    /** The supervise loop — start, run until the runner stops, reconnect with backoff. */
+    const superviseLoop = async () => {
+        while (!closed && !tokenInvalid) {
+            let r;
+            try {
+                r = await startOnce();
+            }
+            catch (err) {
+                if (isTelegramUnauthorized(err)) {
+                    tokenInvalid = true;
+                    connected = false;
+                    safeLog("telegram token rejected (401) — re-token required; polling stopped");
+                    args.onTokenInvalid?.();
+                    return;
+                }
+                if (closed)
+                    return;
+                // Setup failed (transient network on getMe/deleteWebhook) — back off + retry.
+                const delay = telegramBackoffDelay(reconnectAttempts);
+                reconnectAttempts += 1;
+                if (reconnectAttempts > RECONNECT_MAX_ATTEMPTS) {
+                    safeLog("telegram setup attempts exhausted — giving up until restart", { attempts: reconnectAttempts });
+                    return;
+                }
+                safeLog("telegram setup failed — retrying", {
+                    attempt: reconnectAttempts,
+                    delayMs: delay,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                await sleep(delay);
+                continue;
+            }
+            // close() may have fired during the async startOnce() — bail before we
+            // commit to driving a runner we'd otherwise have to wait out.
+            if (closed) {
+                await teardownRunner();
+                return;
+            }
+            // Connected. Reset backoff, announce.
+            connected = true;
+            connectedAtMs = Date.now();
+            reconnectAttempts = 0;
+            conflictRestartUsed = false;
+            safeLog("telegram connected", { account: accountId, self: selfUsername ? `@${selfUsername}` : selfId });
+            args.onConnected?.();
+            // Drive the runner until it stops (graceful or error).
+            try {
+                await r.task();
+                // Runner stopped without throwing — graceful stop (close) or maxRetry.
+                if (closed)
+                    return;
+                connected = false;
+                const delay = telegramBackoffDelay(reconnectAttempts);
+                reconnectAttempts += 1;
+                if (reconnectAttempts > RECONNECT_MAX_ATTEMPTS) {
+                    safeLog("telegram polling attempts exhausted — giving up until restart", { attempts: reconnectAttempts });
+                    return;
+                }
+                safeLog("telegram polling stopped — reconnecting", { attempt: reconnectAttempts, delayMs: delay });
+                await sleep(delay);
+            }
+            catch (err) {
+                connected = false;
+                if (closed)
+                    return;
+                if (isTelegramUnauthorized(err)) {
+                    tokenInvalid = true;
+                    safeLog("telegram token rejected (401) — re-token required; polling stopped");
+                    args.onTokenInvalid?.();
+                    return;
+                }
+                if (isTelegramGetUpdatesConflict(err)) {
+                    // Another poller / a leftover webhook is live. Clear the webhook
+                    // and restart ONCE immediately; if it recurs, fall through to backoff.
+                    if (!conflictRestartUsed) {
+                        conflictRestartUsed = true;
+                        webhookCleared = false; // force a re-clear on the next startOnce
+                        safeLog("telegram getUpdates conflict (409) — clearing webhook + restarting once");
+                        await teardownRunner();
+                        continue;
+                    }
+                    safeLog("telegram getUpdates conflict (409) persists — backing off");
+                }
+                const delay = telegramBackoffDelay(reconnectAttempts);
+                reconnectAttempts += 1;
+                if (reconnectAttempts > RECONNECT_MAX_ATTEMPTS) {
+                    safeLog("telegram polling attempts exhausted — giving up until restart", { attempts: reconnectAttempts });
+                    return;
+                }
+                safeLog("telegram polling error — reconnecting", {
+                    attempt: reconnectAttempts,
+                    delayMs: delay,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                await sleep(delay);
+            }
+            finally {
+                await teardownRunner();
+            }
+        }
+    };
+    const teardownRunner = async () => {
+        const r = runner;
+        runner = null;
+        if (r) {
+            try {
+                if (r.isRunning())
+                    await r.stop();
+            }
+            catch {
+                /* already stopped */
+            }
+        }
+        const b = bot;
+        if (b) {
+            try {
+                await b.stop();
+            }
+            catch {
+                /* already stopped */
+            }
+        }
+    };
+    // Kick the supervise loop. It resolves the initial connect via onConnected;
+    // connectTelegram itself resolves as soon as the FIRST connect (or terminal
+    // failure) settles so the adapter's start() doesn't hang forever.
+    let resolveInitial;
+    const initial = new Promise((resolve) => {
+        resolveInitial = resolve;
+    });
+    const origOnConnected = args.onConnected;
+    const origOnTokenInvalid = args.onTokenInvalid;
+    args.onConnected = () => {
+        origOnConnected?.();
+        resolveInitial();
+    };
+    args.onTokenInvalid = () => {
+        origOnTokenInvalid?.();
+        resolveInitial();
+    };
+    if (mode === "webhook") {
+        // Webhook transport: one-shot setup (no poll loop). A 401 surfaces as a
+        // terminal token-invalid; any other setup error is logged and the channel
+        // stays "starting" until the operator fixes config + restarts.
+        loopPromise = startWebhook().catch((err) => {
+            if (isTelegramUnauthorized(err)) {
+                tokenInvalid = true;
+                connected = false;
+                safeLog("telegram token rejected (401) — re-token required; webhook not registered");
+                args.onTokenInvalid?.();
+                return;
+            }
+            safeLog("telegram webhook setup failed", { error: err instanceof Error ? err.message : String(err) });
+        });
+    }
+    else {
+        loopPromise = superviseLoop().catch((err) => {
+            safeLog("telegram supervise loop crashed", { error: err instanceof Error ? err.message : String(err) });
+        });
+    }
+    // Don't block start() indefinitely — resolve once connected OR after the loop
+    // settles (terminal failure), whichever comes first.
+    await Promise.race([initial, loopPromise.then(() => undefined)]);
+    /* ── outbound + control surface ── */
+    const requireLive = () => {
+        if (tokenInvalid)
+            throw new Error("Telegram token is invalid — set a new bot token and restart.");
+        if (!bot)
+            throw new Error("Telegram channel is not started");
+        return bot;
+    };
+    const sendText = async (chatId, text, opts) => {
+        const b = requireLive();
+        const params = {};
+        if (opts?.html)
+            params.parse_mode = "HTML";
+        if (opts?.threadId)
+            params.message_thread_id = Number(opts.threadId);
+        try {
+            const res = await b.api.sendMessage(chatId, text, params);
+            return { messageId: res.message_id };
+        }
+        catch (err) {
+            // Thread vanished — retry without the thread param (topic deleted/closed).
+            if (opts?.threadId && /message thread not found/i.test(errorText(err))) {
+                const { message_thread_id: _omit, ...rest } = params;
+                const res = await b.api.sendMessage(chatId, text, rest);
+                return { messageId: res.message_id };
+            }
+            throw err;
+        }
+    };
+    const sendInteractive = async (chatId, text, replyMarkup, opts) => {
+        const b = requireLive();
+        const params = { reply_markup: replyMarkup };
+        if (opts?.html)
+            params.parse_mode = "HTML";
+        if (opts?.threadId)
+            params.message_thread_id = Number(opts.threadId);
+        try {
+            const res = await b.api.sendMessage(chatId, text, params);
+            return { messageId: res.message_id };
+        }
+        catch (err) {
+            if (opts?.threadId && /message thread not found/i.test(errorText(err))) {
+                const { message_thread_id: _omit, ...rest } = params;
+                const res = await b.api.sendMessage(chatId, text, rest);
+                return { messageId: res.message_id };
+            }
+            throw err;
+        }
+    };
+    const sendMedia = async (chatId, media, opts) => {
+        const b = requireLive();
+        const { buildTelegramInputFile } = await import("./media.js");
+        const input = await buildTelegramInputFile(media);
+        const params = {};
+        if (opts?.threadId)
+            params.message_thread_id = Number(opts.threadId);
+        if (media.caption)
+            params.caption = media.caption;
+        const api = b.api;
+        const send = async (p) => {
+            switch (media.kind) {
+                case "image":
+                    await api.sendPhoto?.(chatId, input, p);
+                    return;
+                case "video":
+                    await api.sendVideo?.(chatId, input, p);
+                    return;
+                case "audio":
+                    await api.sendAudio?.(chatId, input, p);
+                    return;
+                case "voice":
+                    await api.sendVoice?.(chatId, input, p);
+                    return;
+                case "sticker":
+                    await api.sendSticker?.(chatId, input, p);
+                    return;
+                default:
+                    await api.sendDocument?.(chatId, input, p);
+            }
+        };
+        try {
+            await send(params);
+        }
+        catch (err) {
+            if (opts?.threadId && /message thread not found/i.test(errorText(err))) {
+                const { message_thread_id: _omit, ...rest } = params;
+                await send(rest);
+                return;
+            }
+            throw err;
+        }
+    };
+    const react = async (chatId, messageId, emoji) => {
+        const b = requireLive();
+        if (!b.api.setMessageReaction)
+            return; // older API surface — reaction is cosmetic
+        const id = Number(messageId);
+        if (!Number.isFinite(id))
+            return;
+        const reaction = emoji ? [{ type: "emoji", emoji }] : [];
+        try {
+            await b.api.setMessageReaction(chatId, id, reaction);
+        }
+        catch (err) {
+            safeLog("telegram react failed (cosmetic)", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    const sendPoll = async (chatId, poll, opts) => {
+        const b = requireLive();
+        if (!b.api.sendPoll)
+            throw new Error("Telegram: this bot build cannot send polls.");
+        const params = {
+            // Telegram defaults `is_anonymous` to true; honour an explicit override.
+            is_anonymous: poll.isAnonymous !== false,
+            allows_multiple_answers: poll.allowsMultipleAnswers === true,
+        };
+        if (opts?.threadId)
+            params.message_thread_id = Number(opts.threadId);
+        try {
+            const res = await b.api.sendPoll(chatId, poll.question, poll.options, params);
+            return { messageId: res.message_id };
+        }
+        catch (err) {
+            if (opts?.threadId && /message thread not found/i.test(errorText(err))) {
+                const { message_thread_id: _omit, ...rest } = params;
+                const res = await b.api.sendPoll(chatId, poll.question, poll.options, rest);
+                return { messageId: res.message_id };
+            }
+            throw err;
+        }
+    };
+    const editMessageText = async (chatId, messageId, text, opts) => {
+        const b = requireLive();
+        if (!b.api.editMessageText)
+            throw new Error("Telegram: this bot build cannot edit messages.");
+        const id = Number(messageId);
+        if (!Number.isFinite(id))
+            throw new Error(`Telegram: invalid message id "${messageId}".`);
+        const params = {};
+        if (opts?.html)
+            params.parse_mode = "HTML";
+        await b.api.editMessageText(chatId, id, text, params);
+    };
+    const deleteMessage = async (chatId, messageId) => {
+        const b = requireLive();
+        if (!b.api.deleteMessage)
+            throw new Error("Telegram: this bot build cannot delete messages.");
+        const id = Number(messageId);
+        if (!Number.isFinite(id))
+            throw new Error(`Telegram: invalid message id "${messageId}".`);
+        await b.api.deleteMessage(chatId, id);
+    };
+    const pinMessage = async (chatId, messageId) => {
+        const b = requireLive();
+        if (!b.api.pinChatMessage)
+            throw new Error("Telegram: this bot build cannot pin messages.");
+        const id = Number(messageId);
+        if (!Number.isFinite(id))
+            throw new Error(`Telegram: invalid message id "${messageId}".`);
+        // Silent pin (no member notification) — matches the reference behavior.
+        await b.api.pinChatMessage(chatId, id, { disable_notification: true });
+    };
+    const unpinMessage = async (chatId, messageId) => {
+        const b = requireLive();
+        if (!b.api.unpinChatMessage)
+            throw new Error("Telegram: this bot build cannot unpin messages.");
+        const params = {};
+        if (messageId !== undefined) {
+            const id = Number(messageId);
+            if (Number.isFinite(id))
+                params.message_id = id;
+        }
+        await b.api.unpinChatMessage(chatId, params);
+    };
+    const editForumTopic = async (chatId, threadId, name) => {
+        const b = bot;
+        if (!b || tokenInvalid || !b.api.editForumTopic)
+            return; // best-effort — labeling is cosmetic
+        const id = Number(threadId);
+        if (!Number.isFinite(id))
+            return;
+        // Telegram caps a forum topic name at 128 chars — clamp defensively.
+        const clamped = name.length > 128 ? name.slice(0, 128) : name;
+        if (!clamped.trim())
+            return;
+        try {
+            await b.api.editForumTopic(chatId, id, { name: clamped });
+        }
+        catch (err) {
+            safeLog("telegram editForumTopic failed (cosmetic)", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    };
+    const answerCallback = async (callbackId, text) => {
+        const b = bot;
+        if (!b || tokenInvalid || !b.api.answerCallbackQuery)
+            return; // best-effort
+        try {
+            await b.api.answerCallbackQuery(callbackId, text ? { text } : undefined);
+        }
+        catch {
+            /* ack is cosmetic */
+        }
+    };
+    const getIdentity = async (force) => {
+        if (selfIdentity && !force)
+            return selfIdentity;
+        const b = bot;
+        if (!b || tokenInvalid)
+            return selfIdentity;
+        try {
+            const me = await b.api.getMe();
+            selfIdentity = me;
+            selfId = String(me.id);
+            selfUsername = me.username ?? selfUsername;
+            return me;
+        }
+        catch (err) {
+            safeLog("telegram getMe (probe) failed", { error: err instanceof Error ? err.message : String(err) });
+            return selfIdentity;
+        }
+    };
+    const setCommandMenu = async (commands) => {
+        const b = bot;
+        if (!b || tokenInvalid || !b.api.setMyCommands)
+            return; // best-effort
+        if (commands.length === 0)
+            return;
+        try {
+            await b.api.setMyCommands(commands);
+        }
+        catch (err) {
+            safeLog("telegram setMyCommands failed (cosmetic)", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    };
+    const setComposing = async (chatId, state, threadId) => {
+        if (state !== "composing")
+            return; // Telegram auto-clears typing after ~5s; nothing to send on "paused"
+        const b = bot;
+        if (!b || tokenInvalid)
+            return;
+        const params = {};
+        if (threadId)
+            params.message_thread_id = Number(threadId);
+        try {
+            await b.api.sendChatAction(chatId, "typing", params);
+        }
+        catch {
+            /* presence is best-effort */
+        }
+    };
+    const close = async () => {
+        closed = true;
+        connected = false;
+        await teardownRunner();
+        // Wait for the supervise loop to unwind, but never hang on it — teardown
+        // resolves the active runner's task() so the loop sees `closed` and
+        // returns promptly; the timeout is pure defense-in-depth.
+        try {
+            await Promise.race([
+                loopPromise ?? Promise.resolve(),
+                new Promise((resolve) => setTimeout(resolve, 5_000).unref?.()),
+            ]);
+        }
+        catch {
+            /* loop already settled */
+        }
+    };
+    return {
+        selfId: () => selfId,
+        selfUsername: () => selfUsername,
+        connectedAt: () => connectedAtMs,
+        isConnected: () => connected,
+        isTokenInvalid: () => tokenInvalid,
+        sendText,
+        sendInteractive,
+        sendMedia,
+        sendPoll,
+        react,
+        editMessageText,
+        deleteMessage,
+        pinMessage,
+        unpinMessage,
+        editForumTopic,
+        answerCallback,
+        getIdentity,
+        setCommandMenu,
+        feedUpdate,
+        mode: () => mode,
+        setComposing,
+        markRead: async () => { },
+        close,
+    };
+}
+//# sourceMappingURL=connection.js.map