@poolzin/pool-bot 2026.3.25 → 2026.3.27

package/dist/telegram/outbound-adapter.js

@@ -0,0 +1,100 @@
+import { resolvePayloadMediaUrls, sendPayloadMediaSequence, } from "../../../src/channels/plugins/outbound/direct-text-media.js";
+import { resolveOutboundSendDep, } from "../../../src/infra/outbound/send-deps.js";
+import { markdownToTelegramHtmlChunks } from "./format.js";
+import { parseTelegramReplyToMessageId, parseTelegramThreadId } from "./outbound-params.js";
+import { sendMessageTelegram } from "./send.js";
+function resolveTelegramSendContext(params) {
+    const send = resolveOutboundSendDep(params.deps, "telegram") ?? sendMessageTelegram;
+    return {
+        send,
+        baseOpts: {
+            verbose: false,
+            textMode: "html",
+            cfg: params.cfg,
+            messageThreadId: parseTelegramThreadId(params.threadId),
+            replyToMessageId: parseTelegramReplyToMessageId(params.replyToId),
+            accountId: params.accountId ?? undefined,
+        },
+    };
+}
+export async function sendTelegramPayloadMessages(params) {
+    const telegramData = params.payload.channelData?.telegram;
+    const quoteText = typeof telegramData?.quoteText === "string" ? telegramData.quoteText : undefined;
+    const text = params.payload.text ?? "";
+    const mediaUrls = resolvePayloadMediaUrls(params.payload);
+    const payloadOpts = {
+        ...params.baseOpts,
+        quoteText,
+    };
+    if (mediaUrls.length === 0) {
+        return await params.send(params.to, text, {
+            ...payloadOpts,
+            buttons: telegramData?.buttons,
+        });
+    }
+    // Telegram allows reply_markup on media; attach buttons only to the first send.
+    const finalResult = await sendPayloadMediaSequence({
+        text,
+        mediaUrls,
+        send: async ({ text, mediaUrl, isFirst }) => await params.send(params.to, text, {
+            ...payloadOpts,
+            mediaUrl,
+            ...(isFirst ? { buttons: telegramData?.buttons } : {}),
+        }),
+    });
+    return finalResult ?? { messageId: "unknown", chatId: params.to };
+}
+export const telegramOutbound = {
+    deliveryMode: "direct",
+    chunker: markdownToTelegramHtmlChunks,
+    chunkerMode: "markdown",
+    textChunkLimit: 4000,
+    sendText: async ({ cfg, to, text, accountId, deps, replyToId, threadId }) => {
+        const { send, baseOpts } = resolveTelegramSendContext({
+            cfg,
+            deps,
+            accountId,
+            replyToId,
+            threadId,
+        });
+        const result = await send(to, text, {
+            ...baseOpts,
+        });
+        return { channel: "telegram", ...result };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots, accountId, deps, replyToId, threadId, forceDocument, }) => {
+        const { send, baseOpts } = resolveTelegramSendContext({
+            cfg,
+            deps,
+            accountId,
+            replyToId,
+            threadId,
+        });
+        const result = await send(to, text, {
+            ...baseOpts,
+            mediaUrl,
+            mediaLocalRoots,
+            forceDocument: forceDocument ?? false,
+        });
+        return { channel: "telegram", ...result };
+    },
+    sendPayload: async ({ cfg, to, payload, mediaLocalRoots, accountId, deps, replyToId, threadId, }) => {
+        const { send, baseOpts } = resolveTelegramSendContext({
+            cfg,
+            deps,
+            accountId,
+            replyToId,
+            threadId,
+        });
+        const result = await sendTelegramPayloadMessages({
+            send,
+            to,
+            payload,
+            baseOpts: {
+                ...baseOpts,
+                mediaLocalRoots,
+            },
+        });
+        return { channel: "telegram", ...result };
+    },
+};

package/dist/telegram/polling-session.js

@@ -0,0 +1,275 @@
+import { run } from "@grammyjs/runner";
+import { computeBackoff, sleepWithAbort } from "../../../src/infra/backoff.js";
+import { formatErrorMessage } from "../../../src/infra/errors.js";
+import { formatDurationPrecise } from "../../../src/infra/format-time/format-duration.ts";
+import { withTelegramApiErrorLogging } from "./api-logging.js";
+import { createTelegramBot } from "./bot.js";
+import { isRecoverableTelegramNetworkError } from "./network-errors.js";
+const TELEGRAM_POLL_RESTART_POLICY = {
+    initialMs: 2000,
+    maxMs: 30_000,
+    factor: 1.8,
+    jitter: 0.25,
+};
+const POLL_STALL_THRESHOLD_MS = 90_000;
+const POLL_WATCHDOG_INTERVAL_MS = 30_000;
+const POLL_STOP_GRACE_MS = 15_000;
+const waitForGracefulStop = async (stop) => {
+    let timer;
+    try {
+        await Promise.race([
+            stop(),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, POLL_STOP_GRACE_MS);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+};
+export class TelegramPollingSession {
+    opts;
+    #restartAttempts = 0;
+    #webhookCleared = false;
+    #forceRestarted = false;
+    #activeRunner;
+    #activeFetchAbort;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get activeRunner() {
+        return this.#activeRunner;
+    }
+    markForceRestarted() {
+        this.#forceRestarted = true;
+    }
+    abortActiveFetch() {
+        this.#activeFetchAbort?.abort();
+    }
+    async runUntilAbort() {
+        while (!this.opts.abortSignal?.aborted) {
+            const bot = await this.#createPollingBot();
+            if (!bot) {
+                continue;
+            }
+            const cleanupState = await this.#ensureWebhookCleanup(bot);
+            if (cleanupState === "retry") {
+                continue;
+            }
+            if (cleanupState === "exit") {
+                return;
+            }
+            const state = await this.#runPollingCycle(bot);
+            if (state === "exit") {
+                return;
+            }
+        }
+    }
+    async #waitBeforeRestart(buildLine) {
+        this.#restartAttempts += 1;
+        const delayMs = computeBackoff(TELEGRAM_POLL_RESTART_POLICY, this.#restartAttempts);
+        const delay = formatDurationPrecise(delayMs);
+        this.opts.log(buildLine(delay));
+        try {
+            await sleepWithAbort(delayMs, this.opts.abortSignal);
+        }
+        catch (sleepErr) {
+            if (this.opts.abortSignal?.aborted) {
+                return false;
+            }
+            throw sleepErr;
+        }
+        return true;
+    }
+    async #waitBeforeRetryOnRecoverableSetupError(err, logPrefix) {
+        if (this.opts.abortSignal?.aborted) {
+            return false;
+        }
+        if (!isRecoverableTelegramNetworkError(err, { context: "unknown" })) {
+            throw err;
+        }
+        return this.#waitBeforeRestart((delay) => `${logPrefix}: ${formatErrorMessage(err)}; retrying in ${delay}.`);
+    }
+    async #createPollingBot() {
+        const fetchAbortController = new AbortController();
+        this.#activeFetchAbort = fetchAbortController;
+        try {
+            return createTelegramBot({
+                token: this.opts.token,
+                runtime: this.opts.runtime,
+                proxyFetch: this.opts.proxyFetch,
+                config: this.opts.config,
+                accountId: this.opts.accountId,
+                fetchAbortSignal: fetchAbortController.signal,
+                updateOffset: {
+                    lastUpdateId: this.opts.getLastUpdateId(),
+                    onUpdateId: this.opts.persistUpdateId,
+                },
+            });
+        }
+        catch (err) {
+            await this.#waitBeforeRetryOnRecoverableSetupError(err, "Telegram setup network error");
+            if (this.#activeFetchAbort === fetchAbortController) {
+                this.#activeFetchAbort = undefined;
+            }
+            return undefined;
+        }
+    }
+    async #ensureWebhookCleanup(bot) {
+        if (this.#webhookCleared) {
+            return "ready";
+        }
+        try {
+            await withTelegramApiErrorLogging({
+                operation: "deleteWebhook",
+                runtime: this.opts.runtime,
+                fn: () => bot.api.deleteWebhook({ drop_pending_updates: false }),
+            });
+            this.#webhookCleared = true;
+            return "ready";
+        }
+        catch (err) {
+            const shouldRetry = await this.#waitBeforeRetryOnRecoverableSetupError(err, "Telegram webhook cleanup failed");
+            return shouldRetry ? "retry" : "exit";
+        }
+    }
+    async #confirmPersistedOffset(bot) {
+        const lastUpdateId = this.opts.getLastUpdateId();
+        if (lastUpdateId === null || lastUpdateId >= Number.MAX_SAFE_INTEGER) {
+            return;
+        }
+        try {
+            await bot.api.getUpdates({ offset: lastUpdateId + 1, limit: 1, timeout: 0 });
+        }
+        catch {
+            // Non-fatal: runner middleware still skips duplicates via shouldSkipUpdate.
+        }
+    }
+    async #runPollingCycle(bot) {
+        await this.#confirmPersistedOffset(bot);
+        let lastGetUpdatesAt = Date.now();
+        bot.api.config.use((prev, method, payload, signal) => {
+            if (method === "getUpdates") {
+                lastGetUpdatesAt = Date.now();
+            }
+            return prev(method, payload, signal);
+        });
+        const runner = run(bot, this.opts.runnerOptions);
+        this.#activeRunner = runner;
+        const fetchAbortController = this.#activeFetchAbort;
+        let stopPromise;
+        let stalledRestart = false;
+        let forceCycleTimer;
+        let forceCycleResolve;
+        const forceCyclePromise = new Promise((resolve) => {
+            forceCycleResolve = resolve;
+        });
+        const stopRunner = () => {
+            fetchAbortController?.abort();
+            stopPromise ??= Promise.resolve(runner.stop())
+                .then(() => undefined)
+                .catch(() => {
+                // Runner may already be stopped by abort/retry paths.
+            });
+            return stopPromise;
+        };
+        const stopBot = () => {
+            return Promise.resolve(bot.stop())
+                .then(() => undefined)
+                .catch(() => {
+                // Bot may already be stopped by runner stop/abort paths.
+            });
+        };
+        const stopOnAbort = () => {
+            if (this.opts.abortSignal?.aborted) {
+                void stopRunner();
+            }
+        };
+        const watchdog = setInterval(() => {
+            if (this.opts.abortSignal?.aborted) {
+                return;
+            }
+            const elapsed = Date.now() - lastGetUpdatesAt;
+            if (elapsed > POLL_STALL_THRESHOLD_MS && runner.isRunning()) {
+                stalledRestart = true;
+                this.opts.log(`[telegram] Polling stall detected (no getUpdates for ${formatDurationPrecise(elapsed)}); forcing restart.`);
+                void stopRunner();
+                void stopBot();
+                if (!forceCycleTimer) {
+                    forceCycleTimer = setTimeout(() => {
+                        if (this.opts.abortSignal?.aborted) {
+                            return;
+                        }
+                        this.opts.log(`[telegram] Polling runner stop timed out after ${formatDurationPrecise(POLL_STOP_GRACE_MS)}; forcing restart cycle.`);
+                        forceCycleResolve?.();
+                    }, POLL_STOP_GRACE_MS);
+                }
+            }
+        }, POLL_WATCHDOG_INTERVAL_MS);
+        this.opts.abortSignal?.addEventListener("abort", stopOnAbort, { once: true });
+        try {
+            await Promise.race([runner.task(), forceCyclePromise]);
+            if (this.opts.abortSignal?.aborted) {
+                return "exit";
+            }
+            const reason = stalledRestart
+                ? "polling stall detected"
+                : this.#forceRestarted
+                    ? "unhandled network error"
+                    : "runner stopped (maxRetryTime exceeded or graceful stop)";
+            this.#forceRestarted = false;
+            const shouldRestart = await this.#waitBeforeRestart((delay) => `Telegram polling runner stopped (${reason}); restarting in ${delay}.`);
+            return shouldRestart ? "continue" : "exit";
+        }
+        catch (err) {
+            this.#forceRestarted = false;
+            if (this.opts.abortSignal?.aborted) {
+                throw err;
+            }
+            const isConflict = isGetUpdatesConflict(err);
+            if (isConflict) {
+                this.#webhookCleared = false;
+            }
+            const isRecoverable = isRecoverableTelegramNetworkError(err, { context: "polling" });
+            if (!isConflict && !isRecoverable) {
+                throw err;
+            }
+            const reason = isConflict ? "getUpdates conflict" : "network error";
+            const errMsg = formatErrorMessage(err);
+            const shouldRestart = await this.#waitBeforeRestart((delay) => `Telegram ${reason}: ${errMsg}; retrying in ${delay}.`);
+            return shouldRestart ? "continue" : "exit";
+        }
+        finally {
+            clearInterval(watchdog);
+            if (forceCycleTimer) {
+                clearTimeout(forceCycleTimer);
+            }
+            this.opts.abortSignal?.removeEventListener("abort", stopOnAbort);
+            await waitForGracefulStop(stopRunner);
+            await waitForGracefulStop(stopBot);
+            this.#activeRunner = undefined;
+            if (this.#activeFetchAbort === fetchAbortController) {
+                this.#activeFetchAbort = undefined;
+            }
+        }
+    }
+}
+const isGetUpdatesConflict = (err) => {
+    if (!err || typeof err !== "object") {
+        return false;
+    }
+    const typed = err;
+    const errorCode = typed.error_code ?? typed.errorCode;
+    if (errorCode !== 409) {
+        return false;
+    }
+    const haystack = [typed.method, typed.description, typed.message]
+        .filter((value) => typeof value === "string")
+        .join(" ")
+        .toLowerCase();
+    return haystack.includes("getupdates");
+};

package/dist/telegram/runtime.js

@@ -0,0 +1,3 @@
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
+const { setRuntime: setTelegramRuntime, getRuntime: getTelegramRuntime } = createPluginRuntimeStore("Telegram runtime not initialized");
+export { getTelegramRuntime, setTelegramRuntime };

package/dist/telegram/sendchataction-401-backoff.js

@@ -0,0 +1,71 @@
+import { computeBackoff, sleepWithAbort } from "../../../src/infra/backoff.js";
+const BACKOFF_POLICY = {
+    initialMs: 1000,
+    maxMs: 300_000, // 5 minutes
+    factor: 2,
+    jitter: 0.1,
+};
+function is401Error(error) {
+    if (!error) {
+        return false;
+    }
+    const message = error instanceof Error ? error.message : JSON.stringify(error);
+    return message.includes("401") || message.toLowerCase().includes("unauthorized");
+}
+/**
+ * Creates a GLOBAL (per-account) handler for sendChatAction that tracks 401 errors
+ * across all message contexts. This prevents the infinite loop that caused Telegram
+ * to delete bots (issue #27092).
+ *
+ * When a 401 occurs, exponential backoff is applied (1s → 2s → 4s → ... → 5min).
+ * After maxConsecutive401 failures (default 10), all sendChatAction calls are
+ * suspended until reset() is called.
+ */
+export function createTelegramSendChatActionHandler({ sendChatActionFn, logger, maxConsecutive401 = 10, }) {
+    let consecutive401Failures = 0;
+    let suspended = false;
+    const reset = () => {
+        consecutive401Failures = 0;
+        suspended = false;
+    };
+    const sendChatAction = async (chatId, action, threadParams) => {
+        if (suspended) {
+            return;
+        }
+        if (consecutive401Failures > 0) {
+            const backoffMs = computeBackoff(BACKOFF_POLICY, consecutive401Failures);
+            logger(`sendChatAction backoff: waiting ${backoffMs}ms before retry ` +
+                `(failure ${consecutive401Failures}/${maxConsecutive401})`);
+            await sleepWithAbort(backoffMs);
+        }
+        try {
+            await sendChatActionFn(chatId, action, threadParams);
+            // Success: reset failure counter
+            if (consecutive401Failures > 0) {
+                logger(`sendChatAction recovered after ${consecutive401Failures} consecutive 401 failures`);
+                consecutive401Failures = 0;
+            }
+        }
+        catch (error) {
+            if (is401Error(error)) {
+                consecutive401Failures++;
+                if (consecutive401Failures >= maxConsecutive401) {
+                    suspended = true;
+                    logger(`CRITICAL: sendChatAction suspended after ${consecutive401Failures} consecutive 401 errors. ` +
+                        `Bot token is likely invalid. Telegram may DELETE the bot if requests continue. ` +
+                        `Replace the token and restart: openclaw channels restart telegram`);
+                }
+                else {
+                    logger(`sendChatAction 401 error (${consecutive401Failures}/${maxConsecutive401}). ` +
+                        `Retrying with exponential backoff.`);
+                }
+            }
+            throw error;
+        }
+    };
+    return {
+        sendChatAction,
+        isSuspended: () => suspended,
+        reset,
+    };
+}

package/dist/telegram/sequential-key.js

@@ -0,0 +1,46 @@
+import { isAbortRequestText } from "../../../src/auto-reply/reply/abort.js";
+import { isBtwRequestText } from "../../../src/auto-reply/reply/btw-command.js";
+import { resolveTelegramForumThreadId } from "./bot/helpers.js";
+export function getTelegramSequentialKey(ctx) {
+    const reaction = ctx.update?.message_reaction;
+    if (reaction?.chat?.id) {
+        return `telegram:${reaction.chat.id}`;
+    }
+    const msg = ctx.message ??
+        ctx.channelPost ??
+        ctx.editedChannelPost ??
+        ctx.update?.message ??
+        ctx.update?.edited_message ??
+        ctx.update?.channel_post ??
+        ctx.update?.edited_channel_post ??
+        ctx.update?.callback_query?.message;
+    const chatId = msg?.chat?.id ?? ctx.chat?.id;
+    const rawText = msg?.text ?? msg?.caption;
+    const botUsername = ctx.me?.username;
+    if (isAbortRequestText(rawText, botUsername ? { botUsername } : undefined)) {
+        if (typeof chatId === "number") {
+            return `telegram:${chatId}:control`;
+        }
+        return "telegram:control";
+    }
+    if (isBtwRequestText(rawText, botUsername ? { botUsername } : undefined)) {
+        const messageId = msg?.message_id;
+        if (typeof chatId === "number" && typeof messageId === "number") {
+            return `telegram:${chatId}:btw:${messageId}`;
+        }
+        if (typeof chatId === "number") {
+            return `telegram:${chatId}:btw`;
+        }
+        return "telegram:btw";
+    }
+    const isGroup = msg?.chat?.type === "group" || msg?.chat?.type === "supergroup";
+    const messageThreadId = msg?.message_thread_id;
+    const isForum = msg?.chat?.is_forum;
+    const threadId = isGroup
+        ? resolveTelegramForumThreadId({ isForum, messageThreadId })
+        : messageThreadId;
+    if (typeof chatId === "number") {
+        return threadId != null ? `telegram:${chatId}:topic:${threadId}` : `telegram:${chatId}`;
+    }
+    return "telegram:unknown";
+}

package/dist/telegram/status-issues.js

@@ -0,0 +1,105 @@
+import { appendMatchMetadata, asString, isRecord, resolveEnabledConfiguredAccountId, } from "../../../src/channels/plugins/status-issues/shared.js";
+function readTelegramAccountStatus(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    return {
+        accountId: value.accountId,
+        enabled: value.enabled,
+        configured: value.configured,
+        allowUnmentionedGroups: value.allowUnmentionedGroups,
+        audit: value.audit,
+    };
+}
+function readTelegramGroupMembershipAuditSummary(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const unresolvedGroups = typeof value.unresolvedGroups === "number" && Number.isFinite(value.unresolvedGroups)
+        ? value.unresolvedGroups
+        : undefined;
+    const hasWildcardUnmentionedGroups = typeof value.hasWildcardUnmentionedGroups === "boolean"
+        ? value.hasWildcardUnmentionedGroups
+        : undefined;
+    const groupsRaw = value.groups;
+    const groups = Array.isArray(groupsRaw)
+        ? groupsRaw
+            .map((entry) => {
+            if (!isRecord(entry)) {
+                return null;
+            }
+            const chatId = asString(entry.chatId);
+            if (!chatId) {
+                return null;
+            }
+            const ok = typeof entry.ok === "boolean" ? entry.ok : undefined;
+            const status = asString(entry.status) ?? null;
+            const error = asString(entry.error) ?? null;
+            const matchKey = asString(entry.matchKey) ?? undefined;
+            const matchSource = asString(entry.matchSource) ?? undefined;
+            return { chatId, ok, status, error, matchKey, matchSource };
+        })
+            .filter(Boolean)
+        : undefined;
+    return { unresolvedGroups, hasWildcardUnmentionedGroups, groups };
+}
+export function collectTelegramStatusIssues(accounts) {
+    const issues = [];
+    for (const entry of accounts) {
+        const account = readTelegramAccountStatus(entry);
+        if (!account) {
+            continue;
+        }
+        const accountId = resolveEnabledConfiguredAccountId(account);
+        if (!accountId) {
+            continue;
+        }
+        if (account.allowUnmentionedGroups === true) {
+            issues.push({
+                channel: "telegram",
+                accountId,
+                kind: "config",
+                message: "Config allows unmentioned group messages (requireMention=false). Telegram Bot API privacy mode will block most group messages unless disabled.",
+                fix: "In BotFather run /setprivacy → Disable for this bot (then restart the gateway).",
+            });
+        }
+        const audit = readTelegramGroupMembershipAuditSummary(account.audit);
+        if (audit.hasWildcardUnmentionedGroups === true) {
+            issues.push({
+                channel: "telegram",
+                accountId,
+                kind: "config",
+                message: 'Telegram groups config uses "*" with requireMention=false; membership probing is not possible without explicit group IDs.',
+                fix: "Add explicit numeric group ids under channels.telegram.groups (or per-account groups) to enable probing.",
+            });
+        }
+        if (audit.unresolvedGroups && audit.unresolvedGroups > 0) {
+            issues.push({
+                channel: "telegram",
+                accountId,
+                kind: "config",
+                message: `Some configured Telegram groups are not numeric IDs (unresolvedGroups=${audit.unresolvedGroups}). Membership probe can only check numeric group IDs.`,
+                fix: "Use numeric chat IDs (e.g. -100...) as keys in channels.telegram.groups for requireMention=false groups.",
+            });
+        }
+        for (const group of audit.groups ?? []) {
+            if (group.ok === true) {
+                continue;
+            }
+            const status = group.status ? ` status=${group.status}` : "";
+            const err = group.error ? `: ${group.error}` : "";
+            const baseMessage = `Group ${group.chatId} not reachable by bot.${status}${err}`;
+            issues.push({
+                channel: "telegram",
+                accountId,
+                kind: "runtime",
+                message: appendMatchMetadata(baseMessage, {
+                    matchKey: group.matchKey,
+                    matchSource: group.matchSource,
+                }),
+                fix: "Invite the bot to the group, then DM the bot once (/start) and restart the gateway.",
+            });
+        }
+    }
+    return issues;
+}