@poolzin/pool-bot 2026.3.25 → 2026.3.27

package/dist/telegram/bot/delivery.resolve-media.js

@@ -0,0 +1,227 @@
+import { GrammyError } from "grammy";
+import { logVerbose, warn } from "../../../../src/globals.js";
+import { formatErrorMessage } from "../../../../src/infra/errors.js";
+import { retryAsync } from "../../../../src/infra/retry.js";
+import { fetchRemoteMedia } from "../../../../src/media/fetch.js";
+import { saveMediaBuffer } from "../../../../src/media/store.js";
+import { shouldRetryTelegramIpv4Fallback } from "../fetch.js";
+import { cacheSticker, getCachedSticker } from "../sticker-cache.js";
+import { resolveTelegramMediaPlaceholder } from "./helpers.js";
+const FILE_TOO_BIG_RE = /file is too big/i;
+const TELEGRAM_MEDIA_SSRF_POLICY = {
+    // Telegram file downloads should trust api.telegram.org even when DNS/proxy
+    // resolution maps to private/internal ranges in restricted networks.
+    allowedHostnames: ["api.telegram.org"],
+    allowRfc2544BenchmarkRange: true,
+};
+/**
+ * Returns true if the error is Telegram's "file is too big" error.
+ * This happens when trying to download files >20MB via the Bot API.
+ * Unlike network errors, this is a permanent error and should not be retried.
+ */
+function isFileTooBigError(err) {
+    if (err instanceof GrammyError) {
+        return FILE_TOO_BIG_RE.test(err.description);
+    }
+    return FILE_TOO_BIG_RE.test(formatErrorMessage(err));
+}
+/**
+ * Returns true if the error is a transient network error that should be retried.
+ * Returns false for permanent errors like "file is too big" (400 Bad Request).
+ */
+function isRetryableGetFileError(err) {
+    // Don't retry "file is too big" - it's a permanent 400 error
+    if (isFileTooBigError(err)) {
+        return false;
+    }
+    // Retry all other errors (network issues, timeouts, etc.)
+    return true;
+}
+function resolveMediaFileRef(msg) {
+    return (msg.photo?.[msg.photo.length - 1] ??
+        msg.video ??
+        msg.video_note ??
+        msg.document ??
+        msg.audio ??
+        msg.voice);
+}
+function resolveTelegramFileName(msg) {
+    return (msg.document?.file_name ??
+        msg.audio?.file_name ??
+        msg.video?.file_name ??
+        msg.animation?.file_name);
+}
+async function resolveTelegramFileWithRetry(ctx) {
+    try {
+        return await retryAsync(() => ctx.getFile(), {
+            attempts: 3,
+            minDelayMs: 1000,
+            maxDelayMs: 4000,
+            jitter: 0.2,
+            label: "telegram:getFile",
+            shouldRetry: isRetryableGetFileError,
+            onRetry: ({ attempt, maxAttempts }) => logVerbose(`telegram: getFile retry ${attempt}/${maxAttempts}`),
+        });
+    }
+    catch (err) {
+        // Handle "file is too big" separately - Telegram Bot API has a 20MB download limit
+        if (isFileTooBigError(err)) {
+            logVerbose(warn("telegram: getFile failed - file exceeds Telegram Bot API 20MB limit; skipping attachment"));
+            return null;
+        }
+        // All retries exhausted — return null so the message still reaches the agent
+        // with a type-based placeholder (e.g. <media:audio>) instead of being dropped.
+        logVerbose(`telegram: getFile failed after retries: ${String(err)}`);
+        return null;
+    }
+}
+function resolveRequiredTelegramTransport(transport) {
+    if (transport) {
+        return transport;
+    }
+    const resolvedFetch = globalThis.fetch;
+    if (!resolvedFetch) {
+        throw new Error("fetch is not available; set channels.telegram.proxy in config");
+    }
+    return {
+        fetch: resolvedFetch,
+        sourceFetch: resolvedFetch,
+    };
+}
+function resolveOptionalTelegramTransport(transport) {
+    try {
+        return resolveRequiredTelegramTransport(transport);
+    }
+    catch {
+        return null;
+    }
+}
+/** Default idle timeout for Telegram media downloads (30 seconds). */
+const TELEGRAM_DOWNLOAD_IDLE_TIMEOUT_MS = 30_000;
+async function downloadAndSaveTelegramFile(params) {
+    const url = `https://api.telegram.org/file/bot${params.token}/${params.filePath}`;
+    const fetched = await fetchRemoteMedia({
+        url,
+        fetchImpl: params.transport.sourceFetch,
+        dispatcherPolicy: params.transport.pinnedDispatcherPolicy,
+        fallbackDispatcherPolicy: params.transport.fallbackPinnedDispatcherPolicy,
+        shouldRetryFetchError: shouldRetryTelegramIpv4Fallback,
+        filePathHint: params.filePath,
+        maxBytes: params.maxBytes,
+        readIdleTimeoutMs: TELEGRAM_DOWNLOAD_IDLE_TIMEOUT_MS,
+        ssrfPolicy: TELEGRAM_MEDIA_SSRF_POLICY,
+    });
+    const originalName = params.telegramFileName ?? fetched.fileName ?? params.filePath;
+    return saveMediaBuffer(fetched.buffer, fetched.contentType, "inbound", params.maxBytes, originalName);
+}
+async function resolveStickerMedia(params) {
+    const { msg, ctx, maxBytes, token, transport } = params;
+    if (!msg.sticker) {
+        return undefined;
+    }
+    const sticker = msg.sticker;
+    // Skip animated (TGS) and video (WEBM) stickers - only static WEBP supported
+    if (sticker.is_animated || sticker.is_video) {
+        logVerbose("telegram: skipping animated/video sticker (only static stickers supported)");
+        return null;
+    }
+    if (!sticker.file_id) {
+        return null;
+    }
+    try {
+        const file = await resolveTelegramFileWithRetry(ctx);
+        if (!file?.file_path) {
+            logVerbose("telegram: getFile returned no file_path for sticker");
+            return null;
+        }
+        const resolvedTransport = resolveOptionalTelegramTransport(transport);
+        if (!resolvedTransport) {
+            logVerbose("telegram: fetch not available for sticker download");
+            return null;
+        }
+        const saved = await downloadAndSaveTelegramFile({
+            filePath: file.file_path,
+            token,
+            transport: resolvedTransport,
+            maxBytes,
+        });
+        // Check sticker cache for existing description
+        const cached = sticker.file_unique_id ? getCachedSticker(sticker.file_unique_id) : null;
+        if (cached) {
+            logVerbose(`telegram: sticker cache hit for ${sticker.file_unique_id}`);
+            const fileId = sticker.file_id ?? cached.fileId;
+            const emoji = sticker.emoji ?? cached.emoji;
+            const setName = sticker.set_name ?? cached.setName;
+            if (fileId !== cached.fileId || emoji !== cached.emoji || setName !== cached.setName) {
+                // Refresh cached sticker metadata on hits so sends/searches use latest file_id.
+                cacheSticker({
+                    ...cached,
+                    fileId,
+                    emoji,
+                    setName,
+                });
+            }
+            return {
+                path: saved.path,
+                contentType: saved.contentType,
+                placeholder: "<media:sticker>",
+                stickerMetadata: {
+                    emoji,
+                    setName,
+                    fileId,
+                    fileUniqueId: sticker.file_unique_id,
+                    cachedDescription: cached.description,
+                },
+            };
+        }
+        // Cache miss - return metadata for vision processing
+        return {
+            path: saved.path,
+            contentType: saved.contentType,
+            placeholder: "<media:sticker>",
+            stickerMetadata: {
+                emoji: sticker.emoji ?? undefined,
+                setName: sticker.set_name ?? undefined,
+                fileId: sticker.file_id,
+                fileUniqueId: sticker.file_unique_id,
+            },
+        };
+    }
+    catch (err) {
+        logVerbose(`telegram: failed to process sticker: ${String(err)}`);
+        return null;
+    }
+}
+export async function resolveMedia(ctx, maxBytes, token, transport) {
+    const msg = ctx.message;
+    const stickerResolved = await resolveStickerMedia({
+        msg,
+        ctx,
+        maxBytes,
+        token,
+        transport,
+    });
+    if (stickerResolved !== undefined) {
+        return stickerResolved;
+    }
+    const m = resolveMediaFileRef(msg);
+    if (!m?.file_id) {
+        return null;
+    }
+    const file = await resolveTelegramFileWithRetry(ctx);
+    if (!file) {
+        return null;
+    }
+    if (!file.file_path) {
+        throw new Error("Telegram getFile returned no file_path");
+    }
+    const saved = await downloadAndSaveTelegramFile({
+        filePath: file.file_path,
+        token,
+        transport: resolveRequiredTelegramTransport(transport),
+        maxBytes,
+        telegramFileName: resolveTelegramFileName(msg),
+    });
+    const placeholder = resolveTelegramMediaPlaceholder(msg) ?? "<media:document>";
+    return { path: saved.path, contentType: saved.contentType, placeholder };
+}

package/dist/telegram/bot/delivery.send.js

@@ -0,0 +1,132 @@
+import { GrammyError } from "grammy";
+import { formatErrorMessage } from "../../../../src/infra/errors.js";
+import { withTelegramApiErrorLogging } from "../api-logging.js";
+import { markdownToTelegramHtml } from "../format.js";
+import { buildTelegramThreadParams } from "./helpers.js";
+const PARSE_ERR_RE = /can't parse entities|parse entities|find end of the entity/i;
+const EMPTY_TEXT_ERR_RE = /message text is empty/i;
+const THREAD_NOT_FOUND_RE = /message thread not found/i;
+function isTelegramThreadNotFoundError(err) {
+    if (err instanceof GrammyError) {
+        return THREAD_NOT_FOUND_RE.test(err.description);
+    }
+    return THREAD_NOT_FOUND_RE.test(formatErrorMessage(err));
+}
+function hasMessageThreadIdParam(params) {
+    if (!params) {
+        return false;
+    }
+    return typeof params.message_thread_id === "number";
+}
+function removeMessageThreadIdParam(params) {
+    if (!params) {
+        return {};
+    }
+    const { message_thread_id: _ignored, ...rest } = params;
+    return rest;
+}
+export async function sendTelegramWithThreadFallback(params) {
+    const allowThreadlessRetry = params.thread?.scope === "dm";
+    const hasThreadId = hasMessageThreadIdParam(params.requestParams);
+    const shouldSuppressFirstErrorLog = (err) => allowThreadlessRetry && hasThreadId && isTelegramThreadNotFoundError(err);
+    const mergedShouldLog = params.shouldLog
+        ? (err) => params.shouldLog(err) && !shouldSuppressFirstErrorLog(err)
+        : (err) => !shouldSuppressFirstErrorLog(err);
+    try {
+        return await withTelegramApiErrorLogging({
+            operation: params.operation,
+            runtime: params.runtime,
+            shouldLog: mergedShouldLog,
+            fn: () => params.send(params.requestParams),
+        });
+    }
+    catch (err) {
+        if (!allowThreadlessRetry || !hasThreadId || !isTelegramThreadNotFoundError(err)) {
+            throw err;
+        }
+        const retryParams = removeMessageThreadIdParam(params.requestParams);
+        params.runtime.log?.(`telegram ${params.operation}: message thread not found; retrying without message_thread_id`);
+        return await withTelegramApiErrorLogging({
+            operation: `${params.operation} (threadless retry)`,
+            runtime: params.runtime,
+            fn: () => params.send(retryParams),
+        });
+    }
+}
+export function buildTelegramSendParams(opts) {
+    const threadParams = buildTelegramThreadParams(opts?.thread);
+    const params = {};
+    if (opts?.replyToMessageId) {
+        params.reply_to_message_id = opts.replyToMessageId;
+    }
+    if (threadParams) {
+        params.message_thread_id = threadParams.message_thread_id;
+    }
+    return params;
+}
+export async function sendTelegramText(bot, chatId, text, runtime, opts) {
+    const baseParams = buildTelegramSendParams({
+        replyToMessageId: opts?.replyToMessageId,
+        thread: opts?.thread,
+    });
+    // Add link_preview_options when link preview is disabled.
+    const linkPreviewEnabled = opts?.linkPreview ?? true;
+    const linkPreviewOptions = linkPreviewEnabled ? undefined : { is_disabled: true };
+    const textMode = opts?.textMode ?? "markdown";
+    const htmlText = textMode === "html" ? text : markdownToTelegramHtml(text);
+    const fallbackText = opts?.plainText ?? text;
+    const hasFallbackText = fallbackText.trim().length > 0;
+    const sendPlainFallback = async () => {
+        const res = await sendTelegramWithThreadFallback({
+            operation: "sendMessage",
+            runtime,
+            thread: opts?.thread,
+            requestParams: baseParams,
+            send: (effectiveParams) => bot.api.sendMessage(chatId, fallbackText, {
+                ...(linkPreviewOptions ? { link_preview_options: linkPreviewOptions } : {}),
+                ...(opts?.replyMarkup ? { reply_markup: opts.replyMarkup } : {}),
+                ...effectiveParams,
+            }),
+        });
+        runtime.log?.(`telegram sendMessage ok chat=${chatId} message=${res.message_id} (plain)`);
+        return res.message_id;
+    };
+    // Markdown can render to empty HTML for syntax-only chunks; recover with plain text.
+    if (!htmlText.trim()) {
+        if (!hasFallbackText) {
+            throw new Error("telegram sendMessage failed: empty formatted text and empty plain fallback");
+        }
+        return await sendPlainFallback();
+    }
+    try {
+        const res = await sendTelegramWithThreadFallback({
+            operation: "sendMessage",
+            runtime,
+            thread: opts?.thread,
+            requestParams: baseParams,
+            shouldLog: (err) => {
+                const errText = formatErrorMessage(err);
+                return !PARSE_ERR_RE.test(errText) && !EMPTY_TEXT_ERR_RE.test(errText);
+            },
+            send: (effectiveParams) => bot.api.sendMessage(chatId, htmlText, {
+                parse_mode: "HTML",
+                ...(linkPreviewOptions ? { link_preview_options: linkPreviewOptions } : {}),
+                ...(opts?.replyMarkup ? { reply_markup: opts.replyMarkup } : {}),
+                ...effectiveParams,
+            }),
+        });
+        runtime.log?.(`telegram sendMessage ok chat=${chatId} message=${res.message_id}`);
+        return res.message_id;
+    }
+    catch (err) {
+        const errText = formatErrorMessage(err);
+        if (PARSE_ERR_RE.test(errText) || EMPTY_TEXT_ERR_RE.test(errText)) {
+            if (!hasFallbackText) {
+                throw err;
+            }
+            runtime.log?.(`telegram formatted send failed; retrying without formatting: ${errText}`);
+            return await sendPlainFallback();
+        }
+        throw err;
+    }
+}

package/dist/telegram/bot/reply-threading.js

@@ -0,0 +1,46 @@
+export function createDeliveryProgress() {
+    return {
+        hasReplied: false,
+        hasDelivered: false,
+    };
+}
+export function resolveReplyToForSend(params) {
+    return params.replyToId && (params.replyToMode === "all" || !params.progress.hasReplied)
+        ? params.replyToId
+        : undefined;
+}
+export function markReplyApplied(progress, replyToId) {
+    if (replyToId && !progress.hasReplied) {
+        progress.hasReplied = true;
+    }
+}
+export function markDelivered(progress) {
+    progress.hasDelivered = true;
+}
+export async function sendChunkedTelegramReplyText(params) {
+    const applyDelivered = params.markDelivered ?? markDelivered;
+    for (let i = 0; i < params.chunks.length; i += 1) {
+        const chunk = params.chunks[i];
+        if (!chunk) {
+            continue;
+        }
+        const isFirstChunk = i === 0;
+        const replyToMessageId = resolveReplyToForSend({
+            replyToId: params.replyToId,
+            replyToMode: params.replyToMode,
+            progress: params.progress,
+        });
+        const shouldAttachQuote = Boolean(replyToMessageId) &&
+            Boolean(params.replyQuoteText) &&
+            (params.quoteOnlyOnFirstChunk !== true || isFirstChunk);
+        await params.sendChunk({
+            chunk,
+            isFirstChunk,
+            replyToMessageId,
+            replyMarkup: isFirstChunk ? params.replyMarkup : undefined,
+            replyQuoteText: shouldAttachQuote ? params.replyQuoteText : undefined,
+        });
+        markReplyApplied(params.progress, replyToMessageId);
+        applyDelivered(params.progress);
+    }
+}

package/dist/telegram/bot-message-context.body.js

@@ -0,0 +1,186 @@
+import { findModelInCatalog, loadModelCatalog, modelSupportsVision, } from "../../../src/agents/model-catalog.js";
+import { resolveDefaultModelForAgent } from "../../../src/agents/model-selection.js";
+import { hasControlCommand } from "../../../src/auto-reply/command-detection.js";
+import { recordPendingHistoryEntryIfEnabled, } from "../../../src/auto-reply/reply/history.js";
+import { buildMentionRegexes, matchesMentionWithExplicit, } from "../../../src/auto-reply/reply/mentions.js";
+import { resolveControlCommandGate } from "../../../src/channels/command-gating.js";
+import { formatLocationText } from "../../../src/channels/location.js";
+import { logInboundDrop } from "../../../src/channels/logging.js";
+import { resolveMentionGatingWithBypass } from "../../../src/channels/mention-gating.js";
+import { logVerbose } from "../../../src/globals.js";
+import { isSenderAllowed } from "./bot-access.js";
+import { buildSenderLabel, buildTelegramGroupPeerId, expandTextLinks, extractTelegramLocation, getTelegramTextParts, hasBotMention, resolveTelegramMediaPlaceholder, } from "./bot/helpers.js";
+import { isTelegramForumServiceMessage } from "./forum-service-message.js";
+async function resolveStickerVisionSupport(params) {
+    try {
+        const catalog = await loadModelCatalog({ config: params.cfg });
+        const defaultModel = resolveDefaultModelForAgent({
+            cfg: params.cfg,
+            agentId: params.agentId,
+        });
+        const entry = findModelInCatalog(catalog, defaultModel.provider, defaultModel.model);
+        if (!entry) {
+            return false;
+        }
+        return modelSupportsVision(entry);
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveTelegramInboundBody(params) {
+    const { cfg, primaryCtx, msg, allMedia, isGroup, chatId, senderId, senderUsername, resolvedThreadId, routeAgentId, effectiveGroupAllow, effectiveDmAllow, groupConfig, topicConfig, requireMention, options, groupHistories, historyLimit, logger, } = params;
+    const botUsername = primaryCtx.me?.username?.toLowerCase();
+    const mentionRegexes = buildMentionRegexes(cfg, routeAgentId);
+    const messageTextParts = getTelegramTextParts(msg);
+    const allowForCommands = isGroup ? effectiveGroupAllow : effectiveDmAllow;
+    const senderAllowedForCommands = isSenderAllowed({
+        allow: allowForCommands,
+        senderId,
+        senderUsername,
+    });
+    const useAccessGroups = cfg.commands?.useAccessGroups !== false;
+    const hasControlCommandInMessage = hasControlCommand(messageTextParts.text, cfg, {
+        botUsername,
+    });
+    const commandGate = resolveControlCommandGate({
+        useAccessGroups,
+        authorizers: [{ configured: allowForCommands.hasEntries, allowed: senderAllowedForCommands }],
+        allowTextCommands: true,
+        hasControlCommand: hasControlCommandInMessage,
+    });
+    const commandAuthorized = commandGate.commandAuthorized;
+    const historyKey = isGroup ? buildTelegramGroupPeerId(chatId, resolvedThreadId) : undefined;
+    let placeholder = resolveTelegramMediaPlaceholder(msg) ?? "";
+    const cachedStickerDescription = allMedia[0]?.stickerMetadata?.cachedDescription;
+    const stickerSupportsVision = msg.sticker
+        ? await resolveStickerVisionSupport({ cfg, agentId: routeAgentId })
+        : false;
+    const stickerCacheHit = Boolean(cachedStickerDescription) && !stickerSupportsVision;
+    if (stickerCacheHit) {
+        const emoji = allMedia[0]?.stickerMetadata?.emoji;
+        const setName = allMedia[0]?.stickerMetadata?.setName;
+        const stickerContext = [emoji, setName ? `from "${setName}"` : null].filter(Boolean).join(" ");
+        placeholder = `[Sticker${stickerContext ? ` ${stickerContext}` : ""}] ${cachedStickerDescription}`;
+    }
+    const locationData = extractTelegramLocation(msg);
+    const locationText = locationData ? formatLocationText(locationData) : undefined;
+    const rawText = expandTextLinks(messageTextParts.text, messageTextParts.entities).trim();
+    const hasUserText = Boolean(rawText || locationText);
+    let rawBody = [rawText, locationText].filter(Boolean).join("\n").trim();
+    if (!rawBody) {
+        rawBody = placeholder;
+    }
+    if (!rawBody && allMedia.length === 0) {
+        return null;
+    }
+    let bodyText = rawBody;
+    const hasAudio = allMedia.some((media) => media.contentType?.startsWith("audio/"));
+    const disableAudioPreflight = (topicConfig?.disableAudioPreflight ??
+        groupConfig?.disableAudioPreflight) === true;
+    let preflightTranscript;
+    const needsPreflightTranscription = isGroup &&
+        requireMention &&
+        hasAudio &&
+        !hasUserText &&
+        mentionRegexes.length > 0 &&
+        !disableAudioPreflight;
+    if (needsPreflightTranscription) {
+        try {
+            const { transcribeFirstAudio } = await import("../../../src/media-understanding/audio-preflight.js");
+            const tempCtx = {
+                MediaPaths: allMedia.length > 0 ? allMedia.map((m) => m.path) : undefined,
+                MediaTypes: allMedia.length > 0
+                    ? allMedia.map((m) => m.contentType).filter(Boolean)
+                    : undefined,
+            };
+            preflightTranscript = await transcribeFirstAudio({
+                ctx: tempCtx,
+                cfg,
+                agentDir: undefined,
+            });
+        }
+        catch (err) {
+            logVerbose(`telegram: audio preflight transcription failed: ${String(err)}`);
+        }
+    }
+    if (hasAudio && bodyText === "<media:audio>" && preflightTranscript) {
+        bodyText = preflightTranscript;
+    }
+    if (!bodyText && allMedia.length > 0) {
+        if (hasAudio) {
+            bodyText = preflightTranscript || "<media:audio>";
+        }
+        else {
+            bodyText = `<media:image>${allMedia.length > 1 ? ` (${allMedia.length} images)` : ""}`;
+        }
+    }
+    const hasAnyMention = messageTextParts.entities.some((ent) => ent.type === "mention");
+    const explicitlyMentioned = botUsername ? hasBotMention(msg, botUsername) : false;
+    const computedWasMentioned = matchesMentionWithExplicit({
+        text: messageTextParts.text,
+        mentionRegexes,
+        explicit: {
+            hasAnyMention,
+            isExplicitlyMentioned: explicitlyMentioned,
+            canResolveExplicit: Boolean(botUsername),
+        },
+        transcript: preflightTranscript,
+    });
+    const wasMentioned = options?.forceWasMentioned === true ? true : computedWasMentioned;
+    if (isGroup && commandGate.shouldBlock) {
+        logInboundDrop({
+            log: logVerbose,
+            channel: "telegram",
+            reason: "control command (unauthorized)",
+            target: senderId ?? "unknown",
+        });
+        return null;
+    }
+    const botId = primaryCtx.me?.id;
+    const replyFromId = msg.reply_to_message?.from?.id;
+    const replyToBotMessage = botId != null && replyFromId === botId;
+    const isReplyToServiceMessage = replyToBotMessage && isTelegramForumServiceMessage(msg.reply_to_message);
+    const implicitMention = replyToBotMessage && !isReplyToServiceMessage;
+    const canDetectMention = Boolean(botUsername) || mentionRegexes.length > 0;
+    const mentionGate = resolveMentionGatingWithBypass({
+        isGroup,
+        requireMention: Boolean(requireMention),
+        canDetectMention,
+        wasMentioned,
+        implicitMention: isGroup && Boolean(requireMention) && implicitMention,
+        hasAnyMention,
+        allowTextCommands: true,
+        hasControlCommand: hasControlCommandInMessage,
+        commandAuthorized,
+    });
+    const effectiveWasMentioned = mentionGate.effectiveWasMentioned;
+    if (isGroup && requireMention && canDetectMention && mentionGate.shouldSkip) {
+        logger.info({ chatId, reason: "no-mention" }, "skipping group message");
+        recordPendingHistoryEntryIfEnabled({
+            historyMap: groupHistories,
+            historyKey: historyKey ?? "",
+            limit: historyLimit,
+            entry: historyKey
+                ? {
+                    sender: buildSenderLabel(msg, senderId || chatId),
+                    body: rawBody,
+                    timestamp: msg.date ? msg.date * 1000 : undefined,
+                    messageId: typeof msg.message_id === "number" ? String(msg.message_id) : undefined,
+                }
+                : null,
+        });
+        return null;
+    }
+    return {
+        bodyText,
+        rawBody,
+        historyKey,
+        commandAuthorized,
+        effectiveWasMentioned,
+        canDetectMention,
+        shouldBypassMention: mentionGate.shouldBypassMention,
+        stickerCacheHit,
+        locationData: locationData ?? undefined,
+    };
+}