@gguf/pigbot 0.0.1 → 0.0.3

package/dist/telegram/bot-native-commands.js

@@ -7,14 +7,132 @@ import { dispatchReplyWithBufferedBlockDispatcher } from "../auto-reply/reply/pr
 import { finalizeInboundContext } from "../auto-reply/reply/inbound-context.js";
 import { danger, logVerbose } from "../globals.js";
 import { resolveMarkdownTableMode } from "../config/markdown-tables.js";
+import { withTelegramApiErrorLogging } from "./api-logging.js";
+import { normalizeTelegramCommandName, TELEGRAM_COMMAND_NAME_PATTERN, } from "../config/telegram-custom-commands.js";
 import { resolveAgentRoute } from "../routing/resolve-route.js";
 import { resolveThreadSessionKeys } from "../routing/session-key.js";
 import { resolveCommandAuthorizedFromAuthorizers } from "../channels/command-gating.js";
+import { executePluginCommand, getPluginCommandSpecs, matchPluginCommand, } from "../plugins/commands.js";
 import { deliverReplies } from "./bot/delivery.js";
 import { buildInlineKeyboard } from "./send.js";
 import { buildSenderName, buildTelegramGroupFrom, buildTelegramGroupPeerId, resolveTelegramForumThreadId, } from "./bot/helpers.js";
 import { firstDefined, isSenderAllowed, normalizeAllowFromWithStore } from "./bot-access.js";
 import { readTelegramAllowFromStore } from "./pairing-store.js";
+async function resolveTelegramCommandAuth(params) {
+    const { msg, bot, cfg, telegramCfg, allowFrom, groupAllowFrom, useAccessGroups, resolveGroupPolicy, resolveTelegramGroupConfig, requireAuth, } = params;
+    const chatId = msg.chat.id;
+    const isGroup = msg.chat.type === "group" || msg.chat.type === "supergroup";
+    const messageThreadId = msg.message_thread_id;
+    const isForum = msg.chat.is_forum === true;
+    const resolvedThreadId = resolveTelegramForumThreadId({
+        isForum,
+        messageThreadId,
+    });
+    const storeAllowFrom = await readTelegramAllowFromStore().catch(() => []);
+    const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
+    const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
+    const effectiveGroupAllow = normalizeAllowFromWithStore({
+        allowFrom: groupAllowOverride ?? groupAllowFrom,
+        storeAllowFrom,
+    });
+    const hasGroupAllowOverride = typeof groupAllowOverride !== "undefined";
+    const senderIdRaw = msg.from?.id;
+    const senderId = senderIdRaw ? String(senderIdRaw) : "";
+    const senderUsername = msg.from?.username ?? "";
+    if (isGroup && groupConfig?.enabled === false) {
+        await withTelegramApiErrorLogging({
+            operation: "sendMessage",
+            fn: () => bot.api.sendMessage(chatId, "This group is disabled."),
+        });
+        return null;
+    }
+    if (isGroup && topicConfig?.enabled === false) {
+        await withTelegramApiErrorLogging({
+            operation: "sendMessage",
+            fn: () => bot.api.sendMessage(chatId, "This topic is disabled."),
+        });
+        return null;
+    }
+    if (requireAuth && isGroup && hasGroupAllowOverride) {
+        if (senderIdRaw == null ||
+            !isSenderAllowed({
+                allow: effectiveGroupAllow,
+                senderId: String(senderIdRaw),
+                senderUsername,
+            })) {
+            await withTelegramApiErrorLogging({
+                operation: "sendMessage",
+                fn: () => bot.api.sendMessage(chatId, "You are not authorized to use this command."),
+            });
+            return null;
+        }
+    }
+    if (isGroup && useAccessGroups) {
+        const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+        const groupPolicy = telegramCfg.groupPolicy ?? defaultGroupPolicy ?? "open";
+        if (groupPolicy === "disabled") {
+            await withTelegramApiErrorLogging({
+                operation: "sendMessage",
+                fn: () => bot.api.sendMessage(chatId, "Telegram group commands are disabled."),
+            });
+            return null;
+        }
+        if (groupPolicy === "allowlist" && requireAuth) {
+            if (senderIdRaw == null ||
+                !isSenderAllowed({
+                    allow: effectiveGroupAllow,
+                    senderId: String(senderIdRaw),
+                    senderUsername,
+                })) {
+                await withTelegramApiErrorLogging({
+                    operation: "sendMessage",
+                    fn: () => bot.api.sendMessage(chatId, "You are not authorized to use this command."),
+                });
+                return null;
+            }
+        }
+        const groupAllowlist = resolveGroupPolicy(chatId);
+        if (groupAllowlist.allowlistEnabled && !groupAllowlist.allowed) {
+            await withTelegramApiErrorLogging({
+                operation: "sendMessage",
+                fn: () => bot.api.sendMessage(chatId, "This group is not allowed."),
+            });
+            return null;
+        }
+    }
+    const dmAllow = normalizeAllowFromWithStore({
+        allowFrom: allowFrom,
+        storeAllowFrom,
+    });
+    const senderAllowed = isSenderAllowed({
+        allow: dmAllow,
+        senderId,
+        senderUsername,
+    });
+    const commandAuthorized = resolveCommandAuthorizedFromAuthorizers({
+        useAccessGroups,
+        authorizers: [{ configured: dmAllow.hasEntries, allowed: senderAllowed }],
+        modeWhenAccessGroupsOff: "configured",
+    });
+    if (requireAuth && !commandAuthorized) {
+        await withTelegramApiErrorLogging({
+            operation: "sendMessage",
+            fn: () => bot.api.sendMessage(chatId, "You are not authorized to use this command."),
+        });
+        return null;
+    }
+    return {
+        chatId,
+        isGroup,
+        isForum,
+        resolvedThreadId,
+        senderId,
+        senderUsername,
+        groupConfig,
+        topicConfig,
+        commandAuthorized,
+    };
+}
 export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, telegramCfg, allowFrom, groupAllowFrom, replyToMode, textLimit, useAccessGroups, nativeEnabled, nativeSkillsEnabled, nativeDisabledExplicit, resolveGroupPolicy, resolveTelegramGroupConfig, shouldSkipUpdate, opts, }) => {
     const skillCommands = nativeEnabled && nativeSkillsEnabled ? listSkillCommandsForAgents({ cfg }) : [];
     const nativeCommands = nativeEnabled
@@ -32,17 +150,50 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
         runtime.error?.(danger(issue.message));
     }
     const customCommands = customResolution.commands;
+    const pluginCommandSpecs = getPluginCommandSpecs();
+    const pluginCommands = [];
+    const existingCommands = new Set([
+        ...nativeCommands.map((command) => command.name),
+        ...customCommands.map((command) => command.command),
+    ].map((command) => command.toLowerCase()));
+    const pluginCommandNames = new Set();
+    for (const spec of pluginCommandSpecs) {
+        const normalized = normalizeTelegramCommandName(spec.name);
+        if (!normalized || !TELEGRAM_COMMAND_NAME_PATTERN.test(normalized)) {
+            runtime.error?.(danger(`Plugin command "/${spec.name}" is invalid for Telegram (use a-z, 0-9, underscore; max 32 chars).`));
+            continue;
+        }
+        const description = spec.description.trim();
+        if (!description) {
+            runtime.error?.(danger(`Plugin command "/${normalized}" is missing a description.`));
+            continue;
+        }
+        if (existingCommands.has(normalized)) {
+            runtime.error?.(danger(`Plugin command "/${normalized}" conflicts with an existing Telegram command.`));
+            continue;
+        }
+        if (pluginCommandNames.has(normalized)) {
+            runtime.error?.(danger(`Plugin command "/${normalized}" is duplicated.`));
+            continue;
+        }
+        pluginCommandNames.add(normalized);
+        existingCommands.add(normalized);
+        pluginCommands.push({ command: normalized, description });
+    }
     const allCommands = [
         ...nativeCommands.map((command) => ({
             command: command.name,
             description: command.description,
         })),
+        ...pluginCommands,
         ...customCommands,
     ];
     if (allCommands.length > 0) {
-        bot.api.setMyCommands(allCommands).catch((err) => {
-            runtime.error?.(danger(`telegram setMyCommands failed: ${String(err)}`));
-        });
+        void withTelegramApiErrorLogging({
+            operation: "setMyCommands",
+            runtime,
+            fn: () => bot.api.setMyCommands(allCommands),
+        }).catch(() => { });
         if (typeof bot.command !== "function") {
             logVerbose("telegram: bot.command unavailable; skipping native handlers");
         }
@@ -54,92 +205,21 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                         return;
                     if (shouldSkipUpdate(ctx))
                         return;
-                    const chatId = msg.chat.id;
-                    const isGroup = msg.chat.type === "group" || msg.chat.type === "supergroup";
-                    const messageThreadId = msg.message_thread_id;
-                    const isForum = msg.chat.is_forum === true;
-                    const resolvedThreadId = resolveTelegramForumThreadId({
-                        isForum,
-                        messageThreadId,
-                    });
-                    const storeAllowFrom = await readTelegramAllowFromStore().catch(() => []);
-                    const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
-                    const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
-                    const effectiveGroupAllow = normalizeAllowFromWithStore({
-                        allowFrom: groupAllowOverride ?? groupAllowFrom,
-                        storeAllowFrom,
-                    });
-                    const hasGroupAllowOverride = typeof groupAllowOverride !== "undefined";
-                    if (isGroup && groupConfig?.enabled === false) {
-                        await bot.api.sendMessage(chatId, "This group is disabled.");
-                        return;
-                    }
-                    if (isGroup && topicConfig?.enabled === false) {
-                        await bot.api.sendMessage(chatId, "This topic is disabled.");
-                        return;
-                    }
-                    if (isGroup && hasGroupAllowOverride) {
-                        const senderId = msg.from?.id;
-                        const senderUsername = msg.from?.username ?? "";
-                        if (senderId == null ||
-                            !isSenderAllowed({
-                                allow: effectiveGroupAllow,
-                                senderId: String(senderId),
-                                senderUsername,
-                            })) {
-                            await bot.api.sendMessage(chatId, "You are not authorized to use this command.");
-                            return;
-                        }
-                    }
-                    if (isGroup && useAccessGroups) {
-                        const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
-                        const groupPolicy = telegramCfg.groupPolicy ?? defaultGroupPolicy ?? "open";
-                        if (groupPolicy === "disabled") {
-                            await bot.api.sendMessage(chatId, "Telegram group commands are disabled.");
-                            return;
-                        }
-                        if (groupPolicy === "allowlist") {
-                            const senderId = msg.from?.id;
-                            if (senderId == null) {
-                                await bot.api.sendMessage(chatId, "You are not authorized to use this command.");
-                                return;
-                            }
-                            const senderUsername = msg.from?.username ?? "";
-                            if (!isSenderAllowed({
-                                allow: effectiveGroupAllow,
-                                senderId: String(senderId),
-                                senderUsername,
-                            })) {
-                                await bot.api.sendMessage(chatId, "You are not authorized to use this command.");
-                                return;
-                            }
-                        }
-                        const groupAllowlist = resolveGroupPolicy(chatId);
-                        if (groupAllowlist.allowlistEnabled && !groupAllowlist.allowed) {
-                            await bot.api.sendMessage(chatId, "This group is not allowed.");
-                            return;
-                        }
-                    }
-                    const senderId = msg.from?.id ? String(msg.from.id) : "";
-                    const senderUsername = msg.from?.username ?? "";
-                    const dmAllow = normalizeAllowFromWithStore({
-                        allowFrom: allowFrom,
-                        storeAllowFrom,
-                    });
-                    const senderAllowed = isSenderAllowed({
-                        allow: dmAllow,
-                        senderId,
-                        senderUsername,
-                    });
-                    const commandAuthorized = resolveCommandAuthorizedFromAuthorizers({
+                    const auth = await resolveTelegramCommandAuth({
+                        msg,
+                        bot,
+                        cfg,
+                        telegramCfg,
+                        allowFrom,
+                        groupAllowFrom,
                         useAccessGroups,
-                        authorizers: [{ configured: dmAllow.hasEntries, allowed: senderAllowed }],
-                        modeWhenAccessGroupsOff: "configured",
+                        resolveGroupPolicy,
+                        resolveTelegramGroupConfig,
+                        requireAuth: true,
                     });
-                    if (!commandAuthorized) {
-                        await bot.api.sendMessage(chatId, "You are not authorized to use this command.");
+                    if (!auth)
                         return;
-                    }
+                    const { chatId, isGroup, isForum, resolvedThreadId, senderId, senderUsername, groupConfig, topicConfig, commandAuthorized, } = auth;
                     const commandDefinition = findCommandByNativeName(command.name, "telegram");
                     const rawText = ctx.match?.trim() ?? "";
                     const commandArgs = commandDefinition
@@ -167,18 +247,22 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                             const slice = menu.choices.slice(i, i + 2);
                             rows.push(slice.map((choice) => {
                                 const args = {
-                                    values: { [menu.arg.name]: choice },
+                                    values: { [menu.arg.name]: choice.value },
                                 };
                                 return {
-                                    text: choice,
+                                    text: choice.label,
                                     callback_data: buildCommandTextFromArgs(commandDefinition, args),
                                 };
                             }));
                         }
                         const replyMarkup = buildInlineKeyboard(rows);
-                        await bot.api.sendMessage(chatId, title, {
-                            ...(replyMarkup ? { reply_markup: replyMarkup } : {}),
-                            ...(resolvedThreadId != null ? { message_thread_id: resolvedThreadId } : {}),
+                        await withTelegramApiErrorLogging({
+                            operation: "sendMessage",
+                            runtime,
+                            fn: () => bot.api.sendMessage(chatId, title, {
+                                ...(replyMarkup ? { reply_markup: replyMarkup } : {}),
+                                ...(resolvedThreadId != null ? { message_thread_id: resolvedThreadId } : {}),
+                            }),
                         });
                         return;
                     }
@@ -262,6 +346,7 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                                     messageThreadId: resolvedThreadId,
                                     tableMode,
                                     chunkMode,
+                                    linkPreview: telegramCfg.linkPreview,
                                 });
                             },
                             onError: (err, info) => {
@@ -275,11 +360,77 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                     });
                 });
             }
+            for (const pluginCommand of pluginCommands) {
+                bot.command(pluginCommand.command, async (ctx) => {
+                    const msg = ctx.message;
+                    if (!msg)
+                        return;
+                    if (shouldSkipUpdate(ctx))
+                        return;
+                    const chatId = msg.chat.id;
+                    const rawText = ctx.match?.trim() ?? "";
+                    const commandBody = `/${pluginCommand.command}${rawText ? ` ${rawText}` : ""}`;
+                    const match = matchPluginCommand(commandBody);
+                    if (!match) {
+                        await withTelegramApiErrorLogging({
+                            operation: "sendMessage",
+                            runtime,
+                            fn: () => bot.api.sendMessage(chatId, "Command not found."),
+                        });
+                        return;
+                    }
+                    const auth = await resolveTelegramCommandAuth({
+                        msg,
+                        bot,
+                        cfg,
+                        telegramCfg,
+                        allowFrom,
+                        groupAllowFrom,
+                        useAccessGroups,
+                        resolveGroupPolicy,
+                        resolveTelegramGroupConfig,
+                        requireAuth: match.command.requireAuth !== false,
+                    });
+                    if (!auth)
+                        return;
+                    const { resolvedThreadId, senderId, commandAuthorized } = auth;
+                    const result = await executePluginCommand({
+                        command: match.command,
+                        args: match.args,
+                        senderId,
+                        channel: "telegram",
+                        isAuthorizedSender: commandAuthorized,
+                        commandBody,
+                        config: cfg,
+                    });
+                    const tableMode = resolveMarkdownTableMode({
+                        cfg,
+                        channel: "telegram",
+                        accountId,
+                    });
+                    const chunkMode = resolveChunkMode(cfg, "telegram", accountId);
+                    await deliverReplies({
+                        replies: [result],
+                        chatId: String(chatId),
+                        token: opts.token,
+                        runtime,
+                        bot,
+                        replyToMode,
+                        textLimit,
+                        messageThreadId: resolvedThreadId,
+                        tableMode,
+                        chunkMode,
+                        linkPreview: telegramCfg.linkPreview,
+                    });
+                });
+            }
         }
     }
     else if (nativeDisabledExplicit) {
-        bot.api.setMyCommands([]).catch((err) => {
-            runtime.error?.(danger(`telegram clear commands failed: ${String(err)}`));
-        });
+        void withTelegramApiErrorLogging({
+            operation: "setMyCommands",
+            runtime,
+            fn: () => bot.api.setMyCommands([]),
+        }).catch(() => { });
     }
 };

package/dist/telegram/bot.js

@@ -12,8 +12,10 @@ import { resolveChannelGroupPolicy, resolveChannelGroupRequireMention, } from ".
 import { loadSessionStore, resolveStorePath } from "../config/sessions.js";
 import { danger, logVerbose, shouldLogVerbose } from "../globals.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
+import { formatUncaughtError } from "../infra/errors.js";
 import { enqueueSystemEvent } from "../infra/system-events.js";
 import { getChildLogger } from "../logging.js";
+import { withTelegramApiErrorLogging } from "./api-logging.js";
 import { resolveAgentRoute } from "../routing/resolve-route.js";
 import { resolveThreadSessionKeys } from "../routing/session-key.js";
 import { resolveTelegramAccount } from "./accounts.js";
@@ -67,7 +69,9 @@ export function createTelegramBot(opts) {
         accountId: opts.accountId,
     });
     const telegramCfg = account.config;
-    const fetchImpl = resolveTelegramFetch(opts.proxyFetch);
+    const fetchImpl = resolveTelegramFetch(opts.proxyFetch, {
+        network: telegramCfg.network,
+    });
     const shouldProvideFetch = Boolean(fetchImpl);
     const timeoutSeconds = typeof telegramCfg?.timeoutSeconds === "number" && Number.isFinite(telegramCfg.timeoutSeconds)
         ? Math.max(1, Math.floor(telegramCfg.timeoutSeconds))
@@ -83,6 +87,14 @@ export function createTelegramBot(opts) {
     const bot = new Bot(opts.token, client ? { client } : undefined);
     bot.api.config.use(apiThrottler());
     bot.use(sequentialize(getTelegramSequentialKey));
+    bot.catch((err) => {
+        runtime.error?.(danger(`telegram bot error: ${formatUncaughtError(err)}`));
+    });
+    // Catch all errors from bot middleware to prevent unhandled rejections
+    bot.catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        runtime.error?.(danger(`telegram bot error: ${message}`));
+    });
     const recentUpdates = createTelegramUpdateDedupe();
     let lastUpdateId = typeof opts.updateOffset?.lastUpdateId === "number" ? opts.updateOffset.lastUpdateId : null;
     const recordUpdateId = (ctx) => {
@@ -189,7 +201,11 @@ export function createTelegramBot(opts) {
         if (typeof botHasTopicsEnabled === "boolean")
             return botHasTopicsEnabled;
         try {
-            const me = (await bot.api.getMe());
+            const me = (await withTelegramApiErrorLogging({
+                operation: "getMe",
+                runtime,
+                fn: () => bot.api.getMe(),
+            }));
             botHasTopicsEnabled = Boolean(me?.has_topics_enabled);
         }
         catch (err) {

package/dist/telegram/fetch.js

@@ -1,6 +1,30 @@
+import * as net from "node:net";
 import { resolveFetch } from "../infra/fetch.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import { resolveTelegramAutoSelectFamilyDecision } from "./network-config.js";
+let appliedAutoSelectFamily = null;
+const log = createSubsystemLogger("telegram/network");
+// Node 22 workaround: disable autoSelectFamily to avoid Happy Eyeballs timeouts.
+// See: https://github.com/nodejs/node/issues/54359
+function applyTelegramNetworkWorkarounds(network) {
+    const decision = resolveTelegramAutoSelectFamilyDecision({ network });
+    if (decision.value === null || decision.value === appliedAutoSelectFamily)
+        return;
+    appliedAutoSelectFamily = decision.value;
+    if (typeof net.setDefaultAutoSelectFamily === "function") {
+        try {
+            net.setDefaultAutoSelectFamily(decision.value);
+            const label = decision.source ? ` (${decision.source})` : "";
+            log.info(`telegram: autoSelectFamily=${decision.value}${label}`);
+        }
+        catch {
+            // ignore if unsupported by the runtime
+        }
+    }
+}
 // Prefer wrapped fetch when available to normalize AbortSignal across runtimes.
-export function resolveTelegramFetch(proxyFetch) {
+export function resolveTelegramFetch(proxyFetch, options) {
+    applyTelegramNetworkWorkarounds(options?.network);
     if (proxyFetch)
         return resolveFetch(proxyFetch);
     const fetchImpl = resolveFetch();

package/dist/telegram/monitor.js

@@ -2,10 +2,12 @@ import { run } from "@grammyjs/runner";
 import { loadConfig } from "../config/config.js";
 import { resolveAgentMaxConcurrent } from "../config/agent-limits.js";
 import { computeBackoff, sleepWithAbort } from "../infra/backoff.js";
+import { formatErrorMessage } from "../infra/errors.js";
 import { formatDurationMs } from "../infra/format-duration.js";
 import { resolveTelegramAccount } from "./accounts.js";
 import { resolveTelegramAllowedUpdates } from "./allowed-updates.js";
 import { createTelegramBot } from "./bot.js";
+import { isRecoverableTelegramNetworkError } from "./network-errors.js";
 import { makeProxyFetch } from "./proxy.js";
 import { readTelegramUpdateOffset, writeTelegramUpdateOffset } from "./update-offset-store.js";
 import { startTelegramWebhook } from "./webhook.js";
@@ -23,6 +25,9 @@ export function createTelegramRunnerOptions(cfg) {
             },
             // Suppress grammY getUpdates stack traces; we log concise errors ourselves.
             silent: true,
+            // Retry transient failures for a limited window before surfacing errors.
+            maxRetryTime: 5 * 60 * 1000,
+            retryInterval: "exponential",
         },
     };
 }
@@ -101,7 +106,6 @@ export async function monitorTelegramProvider(opts = {}) {
         return;
     }
     // Use grammyjs/runner for concurrent update processing
-    const log = opts.runtime?.log ?? console.log;
     let restartAttempts = 0;
     while (!opts.abortSignal?.aborted) {
         const runner = run(bot, createTelegramRunnerOptions(cfg));
@@ -120,12 +124,16 @@ export async function monitorTelegramProvider(opts = {}) {
             if (opts.abortSignal?.aborted) {
                 throw err;
             }
-            if (!isGetUpdatesConflict(err)) {
+            const isConflict = isGetUpdatesConflict(err);
+            const isRecoverable = isRecoverableTelegramNetworkError(err, { context: "polling" });
+            if (!isConflict && !isRecoverable) {
                 throw err;
             }
             restartAttempts += 1;
             const delayMs = computeBackoff(TELEGRAM_POLL_RESTART_POLICY, restartAttempts);
-            log(`Telegram getUpdates conflict; retrying in ${formatDurationMs(delayMs)}.`);
+            const reason = isConflict ? "getUpdates conflict" : "network error";
+            const errMsg = formatErrorMessage(err);
+            (opts.runtime?.error ?? console.error)(`Telegram ${reason}: ${errMsg}; retrying in ${formatDurationMs(delayMs)}.`);
             try {
                 await sleepWithAbort(delayMs, opts.abortSignal);
             }

package/dist/telegram/network-config.js

@@ -0,0 +1,23 @@
+import process from "node:process";
+import { isTruthyEnvValue } from "../infra/env.js";
+export const TELEGRAM_DISABLE_AUTO_SELECT_FAMILY_ENV = "CLAWDBOT_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY";
+export const TELEGRAM_ENABLE_AUTO_SELECT_FAMILY_ENV = "CLAWDBOT_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY";
+export function resolveTelegramAutoSelectFamilyDecision(params) {
+    const env = params?.env ?? process.env;
+    const nodeMajor = typeof params?.nodeMajor === "number"
+        ? params.nodeMajor
+        : Number(process.versions.node.split(".")[0]);
+    if (isTruthyEnvValue(env[TELEGRAM_ENABLE_AUTO_SELECT_FAMILY_ENV])) {
+        return { value: true, source: `env:${TELEGRAM_ENABLE_AUTO_SELECT_FAMILY_ENV}` };
+    }
+    if (isTruthyEnvValue(env[TELEGRAM_DISABLE_AUTO_SELECT_FAMILY_ENV])) {
+        return { value: false, source: `env:${TELEGRAM_DISABLE_AUTO_SELECT_FAMILY_ENV}` };
+    }
+    if (typeof params?.network?.autoSelectFamily === "boolean") {
+        return { value: params.network.autoSelectFamily, source: "config" };
+    }
+    if (Number.isFinite(nodeMajor) && nodeMajor >= 22) {
+        return { value: false, source: "default-node22" };
+    }
+    return { value: null };
+}

package/dist/telegram/network-errors.js

@@ -0,0 +1,103 @@
+import { extractErrorCode, formatErrorMessage } from "../infra/errors.js";
+const RECOVERABLE_ERROR_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EPIPE",
+    "ETIMEDOUT",
+    "ESOCKETTIMEDOUT",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+    "UND_ERR_ABORTED",
+]);
+const RECOVERABLE_ERROR_NAMES = new Set([
+    "AbortError",
+    "TimeoutError",
+    "ConnectTimeoutError",
+    "HeadersTimeoutError",
+    "BodyTimeoutError",
+]);
+const RECOVERABLE_MESSAGE_SNIPPETS = [
+    "fetch failed",
+    "network error",
+    "network request",
+    "client network socket disconnected",
+    "socket hang up",
+    "getaddrinfo",
+];
+function normalizeCode(code) {
+    return code?.trim().toUpperCase() ?? "";
+}
+function getErrorName(err) {
+    if (!err || typeof err !== "object")
+        return "";
+    return "name" in err ? String(err.name) : "";
+}
+function getErrorCode(err) {
+    const direct = extractErrorCode(err);
+    if (direct)
+        return direct;
+    if (!err || typeof err !== "object")
+        return undefined;
+    const errno = err.errno;
+    if (typeof errno === "string")
+        return errno;
+    if (typeof errno === "number")
+        return String(errno);
+    return undefined;
+}
+function collectErrorCandidates(err) {
+    const queue = [err];
+    const seen = new Set();
+    const candidates = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current == null || seen.has(current))
+            continue;
+        seen.add(current);
+        candidates.push(current);
+        if (typeof current === "object") {
+            const cause = current.cause;
+            if (cause && !seen.has(cause))
+                queue.push(cause);
+            const reason = current.reason;
+            if (reason && !seen.has(reason))
+                queue.push(reason);
+            const errors = current.errors;
+            if (Array.isArray(errors)) {
+                for (const nested of errors) {
+                    if (nested && !seen.has(nested))
+                        queue.push(nested);
+                }
+            }
+        }
+    }
+    return candidates;
+}
+export function isRecoverableTelegramNetworkError(err, options = {}) {
+    if (!err)
+        return false;
+    const allowMessageMatch = typeof options.allowMessageMatch === "boolean"
+        ? options.allowMessageMatch
+        : options.context !== "send";
+    for (const candidate of collectErrorCandidates(err)) {
+        const code = normalizeCode(getErrorCode(candidate));
+        if (code && RECOVERABLE_ERROR_CODES.has(code))
+            return true;
+        const name = getErrorName(candidate);
+        if (name && RECOVERABLE_ERROR_NAMES.has(name))
+            return true;
+        if (allowMessageMatch) {
+            const message = formatErrorMessage(candidate).toLowerCase();
+            if (message && RECOVERABLE_MESSAGE_SNIPPETS.some((snippet) => message.includes(snippet))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}