@gguf/claw 2026.2.1 → 2026.2.3

package/dist/telegram/bot/delivery.js

@@ -1,8 +1,5 @@
 import { GrammyError, InputFile } from "grammy";
-import { markdownToTelegramChunks, markdownToTelegramHtml, renderTelegramHtmlText, } from "../format.js";
-import { withTelegramApiErrorLogging } from "../api-logging.js";
 import { chunkMarkdownTextWithMode } from "../../auto-reply/chunk.js";
-import { splitTelegramCaption } from "../caption.js";
 import { danger, logVerbose } from "../../globals.js";
 import { formatErrorMessage } from "../../infra/errors.js";
 import { mediaKindFromMime } from "../../media/constants.js";
@@ -10,14 +7,17 @@ import { fetchRemoteMedia } from "../../media/fetch.js";
 import { isGifMedia } from "../../media/mime.js";
 import { saveMediaBuffer } from "../../media/store.js";
 import { loadWebMedia } from "../../web/media.js";
+import { withTelegramApiErrorLogging } from "../api-logging.js";
+import { splitTelegramCaption } from "../caption.js";
+import { markdownToTelegramChunks, markdownToTelegramHtml, renderTelegramHtmlText, } from "../format.js";
 import { buildInlineKeyboard } from "../send.js";
-import { resolveTelegramVoiceSend } from "../voice.js";
-import { buildTelegramThreadParams, resolveTelegramReplyId } from "./helpers.js";
 import { cacheSticker, getCachedSticker } from "../sticker-cache.js";
+import { resolveTelegramVoiceSend } from "../voice.js";
+import { buildTelegramThreadParams, resolveTelegramReplyId, } from "./helpers.js";
 const PARSE_ERR_RE = /can't parse entities|parse entities|find end of the entity/i;
 const VOICE_FORBIDDEN_RE = /VOICE_MESSAGES_FORBIDDEN/;
 export async function deliverReplies(params) {
-    const { replies, chatId, runtime, bot, replyToMode, textLimit, messageThreadId, linkPreview, replyQuoteText, } = params;
+    const { replies, chatId, runtime, bot, replyToMode, textLimit, thread, linkPreview, replyQuoteText, } = params;
     const chunkMode = params.chunkMode ?? "length";
     let hasReplied = false;
     let hasDelivered = false;
@@ -72,7 +72,7 @@ export async function deliverReplies(params) {
                 await sendTelegramText(bot, chatId, chunk.html, runtime, {
                     replyToMessageId: replyToId && (replyToMode === "all" || !hasReplied) ? replyToId : undefined,
                     replyQuoteText,
-                    messageThreadId,
+                    thread,
                     textMode: "html",
                     plainText: chunk.text,
                     linkPreview,
@@ -117,8 +117,8 @@ export async function deliverReplies(params) {
                 ...(shouldAttachButtonsToMedia ? { reply_markup: replyMarkup } : {}),
                 ...buildTelegramSendParams({
                     replyToMessageId,
-                    messageThreadId,
                     replyQuoteText,
+                    thread,
                 }),
             };
             if (isGif) {
@@ -184,7 +184,7 @@ export async function deliverReplies(params) {
                                 replyToId,
                                 replyToMode,
                                 hasReplied,
-                                messageThreadId,
+                                thread,
                                 linkPreview,
                                 replyMarkup,
                                 replyQuoteText,
@@ -226,7 +226,7 @@ export async function deliverReplies(params) {
                     const replyToMessageIdFollowup = replyToId && (replyToMode === "all" || !hasReplied) ? replyToId : undefined;
                     await sendTelegramText(bot, chatId, chunk.html, runtime, {
                         replyToMessageId: replyToMessageIdFollowup,
-                        messageThreadId,
+                        thread,
                         textMode: "html",
                         plainText: chunk.text,
                         linkPreview,
@@ -376,7 +376,7 @@ async function sendTelegramVoiceFallbackText(opts) {
         await sendTelegramText(opts.bot, opts.chatId, chunk.html, opts.runtime, {
             replyToMessageId: opts.replyToId && (opts.replyToMode === "all" || !hasReplied) ? opts.replyToId : undefined,
             replyQuoteText: opts.replyQuoteText,
-            messageThreadId: opts.messageThreadId,
+            thread: opts.thread,
             textMode: "html",
             plainText: chunk.text,
             linkPreview: opts.linkPreview,
@@ -389,7 +389,7 @@ async function sendTelegramVoiceFallbackText(opts) {
     return hasReplied;
 }
 function buildTelegramSendParams(opts) {
-    const threadParams = buildTelegramThreadParams(opts?.messageThreadId);
+    const threadParams = buildTelegramThreadParams(opts?.thread);
     const params = {};
     const quoteText = opts?.replyQuoteText?.trim();
     if (opts?.replyToMessageId) {
@@ -412,7 +412,7 @@ async function sendTelegramText(bot, chatId, text, runtime, opts) {
     const baseParams = buildTelegramSendParams({
         replyToMessageId: opts?.replyToMessageId,
         replyQuoteText: opts?.replyQuoteText,
-        messageThreadId: opts?.messageThreadId,
+        thread: opts?.thread,
     });
     // Add link_preview_options when link preview is disabled.
     const linkPreviewEnabled = opts?.linkPreview ?? true;

package/dist/telegram/bot/helpers.d.ts

@@ -1,5 +1,9 @@
-import { type NormalizedLocation } from "../../channels/location.js";
 import type { TelegramMessage, TelegramStreamMode } from "./types.js";
+import { type NormalizedLocation } from "../../channels/location.js";
+export type TelegramThreadSpec = {
+    id?: number;
+    scope: "dm" | "forum" | "none";
+};
 /**
  * Resolve the thread ID for Telegram forum topics.
  * For non-forum groups, returns undefined even if messageThreadId is present
@@ -10,12 +14,17 @@ export declare function resolveTelegramForumThreadId(params: {
     isForum?: boolean;
     messageThreadId?: number | null;
 }): number | undefined;
+export declare function resolveTelegramThreadSpec(params: {
+    isGroup: boolean;
+    isForum?: boolean;
+    messageThreadId?: number | null;
+}): TelegramThreadSpec;
 /**
  * Build thread params for Telegram API calls (messages, media).
  * General forum topic (id=1) must be treated like a regular supergroup send:
  * Telegram rejects sendMessage/sendMedia with message_thread_id=1 ("thread not found").
  */
-export declare function buildTelegramThreadParams(messageThreadId?: number): {
+export declare function buildTelegramThreadParams(thread?: TelegramThreadSpec | null): {
     message_thread_id: number;
 } | undefined;
 /**

package/dist/telegram/bot/helpers.js

@@ -17,17 +17,36 @@ export function resolveTelegramForumThreadId(params) {
     }
     return params.messageThreadId;
 }
+export function resolveTelegramThreadSpec(params) {
+    if (params.isGroup) {
+        const id = resolveTelegramForumThreadId({
+            isForum: params.isForum,
+            messageThreadId: params.messageThreadId,
+        });
+        return {
+            id,
+            scope: params.isForum ? "forum" : "none",
+        };
+    }
+    if (params.messageThreadId == null) {
+        return { scope: "dm" };
+    }
+    return {
+        id: params.messageThreadId,
+        scope: "dm",
+    };
+}
 /**
  * Build thread params for Telegram API calls (messages, media).
  * General forum topic (id=1) must be treated like a regular supergroup send:
  * Telegram rejects sendMessage/sendMedia with message_thread_id=1 ("thread not found").
  */
-export function buildTelegramThreadParams(messageThreadId) {
-    if (messageThreadId == null) {
+export function buildTelegramThreadParams(thread) {
+    if (!thread?.id) {
         return undefined;
     }
-    const normalized = Math.trunc(messageThreadId);
-    if (normalized === TELEGRAM_GENERAL_TOPIC_ID) {
+    const normalized = Math.trunc(thread.id);
+    if (normalized === TELEGRAM_GENERAL_TOPIC_ID && thread.scope === "forum") {
         return undefined;
     }
     return { message_thread_id: normalized };
@@ -174,7 +193,7 @@ export function describeReplyTarget(msg) {
         return null;
     }
     const sender = reply ? buildSenderName(reply) : undefined;
-    const senderLabel = sender ? `${sender}` : "unknown sender";
+    const senderLabel = sender ?? "unknown sender";
     return {
         id: reply?.message_id ? String(reply.message_id) : undefined,
         sender: senderLabel,

package/dist/telegram/bot-handlers.d.ts

@@ -1,15 +1,2 @@
-export declare const registerTelegramHandlers: ({ cfg, accountId, bot, opts, runtime, mediaMaxBytes, telegramCfg, groupAllowFrom, resolveGroupPolicy, resolveTelegramGroupConfig, shouldSkipUpdate, processMessage, logger, }: {
-    cfg: any;
-    accountId: any;
-    bot: any;
-    opts: any;
-    runtime: any;
-    mediaMaxBytes: any;
-    telegramCfg: any;
-    groupAllowFrom: any;
-    resolveGroupPolicy: any;
-    resolveTelegramGroupConfig: any;
-    shouldSkipUpdate: any;
-    processMessage: any;
-    logger: any;
-}) => void;
+import { RegisterTelegramHandlerParams } from "./bot-native-commands.js";
+export declare const registerTelegramHandlers: ({ cfg, accountId, bot, opts, runtime, mediaMaxBytes, telegramCfg, groupAllowFrom, resolveGroupPolicy, resolveTelegramGroupConfig, shouldSkipUpdate, processMessage, logger, }: RegisterTelegramHandlerParams) => void;

package/dist/telegram/bot-handlers.js

@@ -1,22 +1,22 @@
+import { resolveDefaultAgentId } from "../agents/agent-scope.js";
 // @ts-nocheck
 import { hasControlCommand } from "../auto-reply/command-detection.js";
 import { createInboundDebouncer, resolveInboundDebounceMs, } from "../auto-reply/inbound-debounce.js";
 import { buildCommandsPaginationKeyboard } from "../auto-reply/reply/commands-info.js";
-import { buildCommandsMessagePaginated } from "../auto-reply/status.js";
 import { listSkillCommandsForAgents } from "../auto-reply/skill-commands.js";
-import { resolveDefaultAgentId } from "../agents/agent-scope.js";
+import { buildCommandsMessagePaginated } from "../auto-reply/status.js";
+import { resolveChannelConfigWrites } from "../channels/plugins/config-writes.js";
 import { loadConfig } from "../config/config.js";
 import { writeConfigFile } from "../config/io.js";
 import { danger, logVerbose, warn } from "../globals.js";
-import { resolveMedia } from "./bot/delivery.js";
+import { readChannelAllowFromStore } from "../pairing/pairing-store.js";
 import { withTelegramApiErrorLogging } from "./api-logging.js";
-import { resolveTelegramForumThreadId } from "./bot/helpers.js";
 import { firstDefined, isSenderAllowed, normalizeAllowFromWithStore } from "./bot-access.js";
 import { MEDIA_GROUP_TIMEOUT_MS } from "./bot-updates.js";
+import { resolveMedia } from "./bot/delivery.js";
+import { resolveTelegramForumThreadId } from "./bot/helpers.js";
 import { migrateTelegramGroupConfig } from "./group-migration.js";
 import { resolveTelegramInlineButtonsScope } from "./inline-buttons.js";
-import { readTelegramAllowFromStore } from "./pairing-store.js";
-import { resolveChannelConfigWrites } from "../channels/plugins/config-writes.js";
 import { buildInlineKeyboard } from "./send.js";
 export const registerTelegramHandlers = ({ cfg, accountId, bot, opts, runtime, mediaMaxBytes, telegramCfg, groupAllowFrom, resolveGroupPolicy, resolveTelegramGroupConfig, shouldSkipUpdate, processMessage, logger, }) => {
     const TELEGRAM_TEXT_FRAGMENT_START_THRESHOLD_CHARS = 4000;
@@ -92,7 +92,7 @@ export const registerTelegramHandlers = ({ cfg, accountId, bot, opts, runtime, m
                     });
                 }
             }
-            const storeAllowFrom = await readTelegramAllowFromStore().catch(() => []);
+            const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
             await processMessage(primaryEntry.ctx, allMedia, storeAllowFrom);
         }
         catch (err) {
@@ -119,7 +119,7 @@ export const registerTelegramHandlers = ({ cfg, accountId, bot, opts, runtime, m
                 entities: undefined,
                 date: last.msg.date ?? first.msg.date,
             };
-            const storeAllowFrom = await readTelegramAllowFromStore().catch(() => []);
+            const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
             const baseCtx = first.ctx;
             const getFile = typeof baseCtx.getFile === "function" ? baseCtx.getFile.bind(baseCtx) : async () => ({});
             await processMessage({ message: syntheticMessage, me: baseCtx.me, getFile }, [], storeAllowFrom, { messageIdOverride: String(last.msg.message_id) });
@@ -182,7 +182,7 @@ export const registerTelegramHandlers = ({ cfg, accountId, bot, opts, runtime, m
                 messageThreadId,
             });
             const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
-            const storeAllowFrom = await readTelegramAllowFromStore().catch(() => []);
+            const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
             const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
             const effectiveGroupAllow = normalizeAllowFromWithStore({
                 allowFrom: groupAllowOverride ?? groupAllowFrom,
@@ -388,7 +388,7 @@ export const registerTelegramHandlers = ({ cfg, accountId, bot, opts, runtime, m
                 isForum,
                 messageThreadId,
             });
-            const storeAllowFrom = await readTelegramAllowFromStore().catch(() => []);
+            const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
             const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
             const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
             const effectiveGroupAllow = normalizeAllowFromWithStore({

package/dist/telegram/bot-message-context.d.ts

@@ -1,8 +1,8 @@
 import type { Bot } from "grammy";
-import { type HistoryEntry } from "../auto-reply/reply/history.js";
 import type { OpenClawConfig } from "../config/config.js";
 import type { DmPolicy, TelegramGroupConfig, TelegramTopicConfig } from "../config/types.js";
 import type { TelegramContext } from "./bot/types.js";
+import { type HistoryEntry } from "../auto-reply/reply/history.js";
 type TelegramMediaRef = {
     path: string;
     contentType?: string;
@@ -118,6 +118,7 @@ export declare const buildTelegramMessageContext: ({ primaryCtx, allMedia, store
     chatId: number;
     isGroup: boolean;
     resolvedThreadId: number | undefined;
+    threadSpec: import("./bot/helpers.js").TelegramThreadSpec;
     replyThreadId: number | undefined;
     isForum: boolean;
     historyKey: string | undefined;

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

@@ -7,22 +7,22 @@ import { formatInboundEnvelope, resolveEnvelopeFormatOptions } from "../auto-rep
 import { buildPendingHistoryContextFromMap, recordPendingHistoryEntryIfEnabled, } from "../auto-reply/reply/history.js";
 import { finalizeInboundContext } from "../auto-reply/reply/inbound-context.js";
 import { buildMentionRegexes, matchesMentionWithExplicit } from "../auto-reply/reply/mentions.js";
+import { shouldAckReaction as shouldAckReactionGate } from "../channels/ack-reactions.js";
+import { resolveControlCommandGate } from "../channels/command-gating.js";
 import { formatLocationText, toLocationContext } from "../channels/location.js";
+import { logInboundDrop } from "../channels/logging.js";
+import { resolveMentionGatingWithBypass } from "../channels/mention-gating.js";
 import { recordInboundSession } from "../channels/session.js";
 import { formatCliCommand } from "../cli/command-format.js";
 import { readSessionUpdatedAt, resolveStorePath } from "../config/sessions.js";
 import { logVerbose, shouldLogVerbose } from "../globals.js";
 import { recordChannelActivity } from "../infra/channel-activity.js";
+import { upsertChannelPairingRequest } from "../pairing/pairing-store.js";
 import { resolveAgentRoute } from "../routing/resolve-route.js";
 import { resolveThreadSessionKeys } from "../routing/session-key.js";
-import { shouldAckReaction as shouldAckReactionGate } from "../channels/ack-reactions.js";
-import { resolveMentionGatingWithBypass } from "../channels/mention-gating.js";
-import { resolveControlCommandGate } from "../channels/command-gating.js";
-import { logInboundDrop } from "../channels/logging.js";
 import { withTelegramApiErrorLogging } from "./api-logging.js";
-import { buildGroupLabel, buildSenderLabel, buildSenderName, buildTelegramGroupFrom, buildTelegramGroupPeerId, buildTypingThreadParams, expandTextLinks, normalizeForwardedContext, describeReplyTarget, extractTelegramLocation, hasBotMention, resolveTelegramForumThreadId, } from "./bot/helpers.js";
 import { firstDefined, isSenderAllowed, normalizeAllowFromWithStore, resolveSenderAllowMatch, } from "./bot-access.js";
-import { upsertTelegramPairingRequest } from "./pairing-store.js";
+import { buildGroupLabel, buildSenderLabel, buildSenderName, buildTelegramGroupFrom, buildTelegramGroupPeerId, buildTypingThreadParams, expandTextLinks, normalizeForwardedContext, describeReplyTarget, extractTelegramLocation, hasBotMention, resolveTelegramThreadSpec, } from "./bot/helpers.js";
 async function resolveStickerVisionSupport(params) {
     try {
         const catalog = await loadModelCatalog({ config: params.cfg });
@@ -51,11 +51,13 @@ export const buildTelegramMessageContext = async ({ primaryCtx, allMedia, storeA
     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({
+    const threadSpec = resolveTelegramThreadSpec({
+        isGroup,
         isForum,
         messageThreadId,
     });
-    const replyThreadId = isGroup ? resolvedThreadId : messageThreadId;
+    const resolvedThreadId = threadSpec.scope === "forum" ? threadSpec.id : undefined;
+    const replyThreadId = threadSpec.id;
     const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
     const peerId = isGroup ? buildTelegramGroupPeerId(chatId, resolvedThreadId) : String(chatId);
     const route = resolveAgentRoute({
@@ -68,8 +70,8 @@ export const buildTelegramMessageContext = async ({ primaryCtx, allMedia, storeA
         },
     });
     const baseSessionKey = route.sessionKey;
-    // DMs: use raw messageThreadId for thread sessions (not resolvedThreadId which is for forums)
-    const dmThreadId = !isGroup ? messageThreadId : undefined;
+    // DMs: use raw messageThreadId for thread sessions (not forum topic ids)
+    const dmThreadId = threadSpec.scope === "dm" ? threadSpec.id : undefined;
     const threadKeys = dmThreadId != null
         ? resolveThreadSessionKeys({ baseSessionKey, threadId: String(dmThreadId) })
         : null;
@@ -127,11 +129,14 @@ export const buildTelegramMessageContext = async ({ primaryCtx, allMedia, storeA
                     try {
                         const from = msg.from;
                         const telegramUserId = from?.id ? String(from.id) : candidate;
-                        const { code, created } = await upsertTelegramPairingRequest({
-                            chatId: candidate,
-                            username: from?.username,
-                            firstName: from?.first_name,
-                            lastName: from?.last_name,
+                        const { code, created } = await upsertChannelPairingRequest({
+                            channel: "telegram",
+                            id: telegramUserId,
+                            meta: {
+                                username: from?.username,
+                                firstName: from?.first_name,
+                                lastName: from?.last_name,
+                            },
                         });
                         if (created) {
                             logger.info({
@@ -452,8 +457,8 @@ export const buildTelegramMessageContext = async ({ primaryCtx, allMedia, storeA
         Sticker: allMedia[0]?.stickerMetadata,
         ...(locationData ? toLocationContext(locationData) : undefined),
         CommandAuthorized: commandAuthorized,
-        // For groups: use resolvedThreadId (forum topics only); for DMs: use raw messageThreadId
-        MessageThreadId: isGroup ? resolvedThreadId : messageThreadId,
+        // For groups: use resolved forum topic id; for DMs: use raw messageThreadId
+        MessageThreadId: threadSpec.id,
         IsForum: isForum,
         // Originating channel for reply routing.
         OriginatingChannel: "telegram",
@@ -495,6 +500,7 @@ export const buildTelegramMessageContext = async ({ primaryCtx, allMedia, storeA
         chatId,
         isGroup,
         resolvedThreadId,
+        threadSpec,
         replyThreadId,
         isForum,
         historyKey,

package/dist/telegram/bot-message-dispatch.d.ts

@@ -1,12 +1 @@
-export declare const dispatchTelegramMessage: ({ context, bot, cfg, runtime, replyToMode, streamMode, textLimit, telegramCfg, opts, resolveBotTopicsEnabled, }: {
-    context: any;
-    bot: any;
-    cfg: any;
-    runtime: any;
-    replyToMode: any;
-    streamMode: any;
-    textLimit: any;
-    telegramCfg: any;
-    opts: any;
-    resolveBotTopicsEnabled: any;
-}) => Promise<void>;
+export declare const dispatchTelegramMessage: ({ context, bot, cfg, runtime, replyToMode, streamMode, textLimit, telegramCfg, opts, resolveBotTopicsEnabled, }: any) => Promise<void>;

package/dist/telegram/bot-message-dispatch.js

@@ -1,7 +1,8 @@
+import { resolveAgentDir } from "../agents/agent-scope.js";
 // @ts-nocheck
 import { findModelInCatalog, loadModelCatalog, modelSupportsVision, } from "../agents/model-catalog.js";
-import { EmbeddedBlockChunker } from "../agents/pi-embedded-block-chunker.js";
 import { resolveDefaultModelForAgent } from "../agents/model-selection.js";
+import { EmbeddedBlockChunker } from "../agents/pi-embedded-block-chunker.js";
 import { resolveChunkMode } from "../auto-reply/chunk.js";
 import { clearHistoryEntriesIfEnabled } from "../auto-reply/reply/history.js";
 import { dispatchReplyWithBufferedBlockDispatcher } from "../auto-reply/reply/provider-dispatcher.js";
@@ -9,13 +10,12 @@ import { removeAckReactionAfterReply } from "../channels/ack-reactions.js";
 import { logAckFailure, logTypingFailure } from "../channels/logging.js";
 import { createReplyPrefixContext } from "../channels/reply-prefix.js";
 import { createTypingCallbacks } from "../channels/typing.js";
-import { danger, logVerbose } from "../globals.js";
 import { resolveMarkdownTableMode } from "../config/markdown-tables.js";
+import { danger, logVerbose } from "../globals.js";
 import { deliverReplies } from "./bot/delivery.js";
 import { resolveTelegramDraftStreamingChunking } from "./draft-chunking.js";
 import { createTelegramDraftStream } from "./draft-stream.js";
 import { cacheSticker, describeStickerImage } from "./sticker-cache.js";
-import { resolveAgentDir } from "../agents/agent-scope.js";
 const EMPTY_RESPONSE_FALLBACK = "No response generated. Please try again.";
 async function resolveStickerVisionSupport(cfg, agentId) {
     try {
@@ -31,11 +31,12 @@ async function resolveStickerVisionSupport(cfg, agentId) {
         return false;
     }
 }
-export const dispatchTelegramMessage = async ({ context, bot, cfg, runtime, replyToMode, streamMode, textLimit, telegramCfg, opts, resolveBotTopicsEnabled, }) => {
-    const { ctxPayload, primaryCtx, msg, chatId, isGroup, replyThreadId, historyKey, historyLimit, groupHistories, route, skillFilter, sendTyping, sendRecordVoice, ackReactionPromise, reactionApi, removeAckAfterReply, } = context;
+export const dispatchTelegramMessage = async ({ context, bot, cfg, runtime, replyToMode, streamMode, textLimit, telegramCfg, opts, resolveBotTopicsEnabled,
+// oxlint-disable-next-line typescript/no-explicit-any
+ }) => {
+    const { ctxPayload, primaryCtx, msg, chatId, isGroup, threadSpec, historyKey, historyLimit, groupHistories, route, skillFilter, sendTyping, sendRecordVoice, ackReactionPromise, reactionApi, removeAckAfterReply, } = context;
     const isPrivateChat = msg.chat.type === "private";
-    const messageThreadId = msg.message_thread_id;
-    const draftThreadId = replyThreadId ?? messageThreadId;
+    const draftThreadId = threadSpec.id;
     const draftMaxChars = Math.min(textLimit, 4096);
     const canStreamDraft = streamMode !== "off" &&
         isPrivateChat &&
@@ -47,7 +48,7 @@ export const dispatchTelegramMessage = async ({ context, bot, cfg, runtime, repl
             chatId,
             draftId: msg.message_id || Date.now(),
             maxChars: draftMaxChars,
-            messageThreadId: draftThreadId,
+            thread: threadSpec,
             log: logVerbose,
             warn: logVerbose,
         })
@@ -197,7 +198,7 @@ export const dispatchTelegramMessage = async ({ context, bot, cfg, runtime, repl
                     bot,
                     replyToMode,
                     textLimit,
-                    messageThreadId: replyThreadId,
+                    thread: threadSpec,
                     tableMode,
                     chunkMode,
                     onVoiceRecording: sendRecordVoice,
@@ -248,7 +249,7 @@ export const dispatchTelegramMessage = async ({ context, bot, cfg, runtime, repl
             bot,
             replyToMode,
             textLimit,
-            messageThreadId: replyThreadId,
+            thread: threadSpec,
             tableMode,
             chunkMode,
             linkPreview: telegramCfg.linkPreview,

package/dist/telegram/bot-native-commands.d.ts

@@ -1,8 +1,35 @@
 import type { Bot } from "grammy";
+import type { OpenClawConfig } from "../config/config.js";
 import type { ChannelGroupPolicy } from "../config/group-policy.js";
 import type { ReplyToMode, TelegramAccountConfig, TelegramGroupConfig, TelegramTopicConfig } from "../config/types.js";
-import type { OpenClawConfig } from "../config/config.js";
 import type { RuntimeEnv } from "../runtime.js";
+import { getChildLogger } from "../logging.js";
+import { TelegramUpdateKeyContext } from "./bot-updates.js";
+import { TelegramBotOptions } from "./bot.js";
+export type RegisterTelegramHandlerParams = {
+    cfg: OpenClawConfig;
+    accountId: string;
+    bot: Bot;
+    mediaMaxBytes: number;
+    opts: TelegramBotOptions;
+    runtime: RuntimeEnv;
+    telegramCfg: TelegramAccountConfig;
+    groupAllowFrom?: Array<string | number>;
+    resolveGroupPolicy: (chatId: string | number) => ChannelGroupPolicy;
+    resolveTelegramGroupConfig: (chatId: string | number, messageThreadId?: number) => {
+        groupConfig?: TelegramGroupConfig;
+        topicConfig?: TelegramTopicConfig;
+    };
+    shouldSkipUpdate: (ctx: TelegramUpdateKeyContext) => boolean;
+    processMessage: (ctx: unknown, allMedia: Array<{
+        path: string;
+        contentType?: string;
+    }>, storeAllowFrom: string[], options?: {
+        messageIdOverride?: string;
+        forceWasMentioned?: boolean;
+    }) => Promise<void>;
+    logger: ReturnType<typeof getChildLogger>;
+};
 type RegisterTelegramNativeCommandsParams = {
     bot: Bot;
     cfg: OpenClawConfig;
@@ -22,7 +49,7 @@ type RegisterTelegramNativeCommandsParams = {
         groupConfig?: TelegramGroupConfig;
         topicConfig?: TelegramTopicConfig;
     };
-    shouldSkipUpdate: (ctx: unknown) => boolean;
+    shouldSkipUpdate: (ctx: TelegramUpdateKeyContext) => boolean;
     opts: {
         token: string;
     };

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

@@ -1,23 +1,23 @@
 import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import { resolveChunkMode } from "../auto-reply/chunk.js";
 import { buildCommandTextFromArgs, findCommandByNativeName, listNativeCommandSpecs, listNativeCommandSpecsForConfig, parseCommandArgs, resolveCommandArgMenu, } from "../auto-reply/commands-registry.js";
-import { listSkillCommandsForAgents } from "../auto-reply/skill-commands.js";
-import { resolveTelegramCustomCommands } from "../config/telegram-custom-commands.js";
-import { dispatchReplyWithBufferedBlockDispatcher } from "../auto-reply/reply/provider-dispatcher.js";
 import { finalizeInboundContext } from "../auto-reply/reply/inbound-context.js";
-import { danger, logVerbose } from "../globals.js";
+import { dispatchReplyWithBufferedBlockDispatcher } from "../auto-reply/reply/provider-dispatcher.js";
+import { listSkillCommandsForAgents } from "../auto-reply/skill-commands.js";
+import { resolveCommandAuthorizedFromAuthorizers } from "../channels/command-gating.js";
 import { resolveMarkdownTableMode } from "../config/markdown-tables.js";
-import { withTelegramApiErrorLogging } from "./api-logging.js";
+import { resolveTelegramCustomCommands } from "../config/telegram-custom-commands.js";
 import { normalizeTelegramCommandName, TELEGRAM_COMMAND_NAME_PATTERN, } from "../config/telegram-custom-commands.js";
+import { danger, logVerbose } from "../globals.js";
+import { readChannelAllowFromStore } from "../pairing/pairing-store.js";
+import { executePluginCommand, getPluginCommandSpecs, matchPluginCommand, } from "../plugins/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 { withTelegramApiErrorLogging } from "./api-logging.js";
+import { firstDefined, isSenderAllowed, normalizeAllowFromWithStore } from "./bot-access.js";
 import { deliverReplies } from "./bot/delivery.js";
+import { buildTelegramThreadParams, buildSenderName, buildTelegramGroupFrom, buildTelegramGroupPeerId, resolveTelegramForumThreadId, resolveTelegramThreadSpec, } from "./bot/helpers.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";
 const EMPTY_RESPONSE_FALLBACK = "No response generated. Please try again.";
 async function resolveTelegramCommandAuth(params) {
     const { msg, bot, cfg, telegramCfg, allowFrom, groupAllowFrom, useAccessGroups, resolveGroupPolicy, resolveTelegramGroupConfig, requireAuth, } = params;
@@ -29,7 +29,7 @@ async function resolveTelegramCommandAuth(params) {
         isForum,
         messageThreadId,
     });
-    const storeAllowFrom = await readTelegramAllowFromStore().catch(() => []);
+    const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
     const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
     const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
     const effectiveGroupAllow = normalizeAllowFromWithStore({
@@ -143,7 +143,10 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
         ? listSkillCommandsForAgents(boundAgentIds ? { cfg, agentIds: boundAgentIds } : { cfg })
         : [];
     const nativeCommands = nativeEnabled
-        ? listNativeCommandSpecsForConfig(cfg, { skillCommands, provider: "telegram" })
+        ? listNativeCommandSpecsForConfig(cfg, {
+            skillCommands,
+            provider: "telegram",
+        })
         : [];
     const reservedCommands = new Set(listNativeCommandSpecs().map((command) => command.name.toLowerCase()));
     for (const command of skillCommands) {
@@ -231,7 +234,12 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                     }
                     const { chatId, isGroup, isForum, resolvedThreadId, senderId, senderUsername, groupConfig, topicConfig, commandAuthorized, } = auth;
                     const messageThreadId = msg.message_thread_id;
-                    const threadIdForSend = isGroup ? resolvedThreadId : messageThreadId;
+                    const threadSpec = resolveTelegramThreadSpec({
+                        isGroup,
+                        isForum,
+                        messageThreadId,
+                    });
+                    const threadParams = buildTelegramThreadParams(threadSpec) ?? {};
                     const commandDefinition = findCommandByNativeName(command.name, "telegram");
                     const rawText = ctx.match?.trim() ?? "";
                     const commandArgs = commandDefinition
@@ -273,7 +281,7 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                             runtime,
                             fn: () => bot.api.sendMessage(chatId, title, {
                                 ...(replyMarkup ? { reply_markup: replyMarkup } : {}),
-                                ...(threadIdForSend != null ? { message_thread_id: threadIdForSend } : {}),
+                                ...threadParams,
                             }),
                         });
                         return;
@@ -289,9 +297,12 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                     });
                     const baseSessionKey = route.sessionKey;
                     // DMs: use raw messageThreadId for thread sessions (not resolvedThreadId which is for forums)
-                    const dmThreadId = !isGroup ? messageThreadId : undefined;
+                    const dmThreadId = threadSpec.scope === "dm" ? threadSpec.id : undefined;
                     const threadKeys = dmThreadId != null
-                        ? resolveThreadSessionKeys({ baseSessionKey, threadId: String(dmThreadId) })
+                        ? resolveThreadSessionKeys({
+                            baseSessionKey,
+                            threadId: String(dmThreadId),
+                        })
                         : null;
                     const sessionKey = threadKeys?.sessionKey ?? baseSessionKey;
                     const tableMode = resolveMarkdownTableMode({
@@ -333,7 +344,7 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                         SessionKey: `telegram:slash:${senderId || chatId}`,
                         AccountId: route.accountId,
                         CommandTargetSessionKey: sessionKey,
-                        MessageThreadId: threadIdForSend,
+                        MessageThreadId: threadSpec.id,
                         IsForum: isForum,
                         // Originating context for sub-agent announce routing
                         OriginatingChannel: "telegram",
@@ -361,7 +372,7 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                                     bot,
                                     replyToMode,
                                     textLimit,
-                                    messageThreadId: threadIdForSend,
+                                    thread: threadSpec,
                                     tableMode,
                                     chunkMode,
                                     linkPreview: telegramCfg.linkPreview,
@@ -393,7 +404,7 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                             bot,
                             replyToMode,
                             textLimit,
-                            messageThreadId: threadIdForSend,
+                            thread: threadSpec,
                             tableMode,
                             chunkMode,
                             linkPreview: telegramCfg.linkPreview,
@@ -437,9 +448,13 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                     if (!auth) {
                         return;
                     }
-                    const { resolvedThreadId, senderId, commandAuthorized, isGroup } = auth;
+                    const { senderId, commandAuthorized, isGroup, isForum } = auth;
                     const messageThreadId = msg.message_thread_id;
-                    const threadIdForSend = isGroup ? resolvedThreadId : messageThreadId;
+                    const threadSpec = resolveTelegramThreadSpec({
+                        isGroup,
+                        isForum,
+                        messageThreadId,
+                    });
                     const result = await executePluginCommand({
                         command: match.command,
                         args: match.args,
@@ -463,7 +478,7 @@ export const registerTelegramNativeCommands = ({ bot, cfg, runtime, accountId, t
                         bot,
                         replyToMode,
                         textLimit,
-                        messageThreadId: threadIdForSend,
+                        thread: threadSpec,
                         tableMode,
                         chunkMode,
                         linkPreview: telegramCfg.linkPreview,