clawgram 2.0.0

package/dist/channel.js

@@ -0,0 +1,1233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChannelPlugin = void 0;
+const core_1 = require("openclaw/plugin-sdk/core");
+const channel_runtime_1 = require("openclaw/plugin-sdk/channel-runtime");
+const param_readers_1 = require("openclaw/plugin-sdk/param-readers");
+const tool_send_1 = require("openclaw/plugin-sdk/tool-send");
+const direct_dm_1 = require("openclaw/plugin-sdk/direct-dm");
+const channel_inbound_1 = require("openclaw/plugin-sdk/channel-inbound");
+const channel_reply_pipeline_1 = require("openclaw/plugin-sdk/channel-reply-pipeline");
+const inbound_envelope_1 = require("openclaw/plugin-sdk/inbound-envelope");
+const inbound_reply_dispatch_1 = require("openclaw/plugin-sdk/inbound-reply-dispatch");
+const channel_pairing_1 = require("openclaw/plugin-sdk/channel-pairing");
+const events_1 = require("telegram/events");
+const gramjs_client_1 = require("./gramjs-client");
+const normalize_1 = require("./normalize");
+const history_1 = require("./history");
+const joins_1 = require("./joins");
+const group_reply_address_1 = require("./group-reply-address");
+const group_visible_reply_guard_1 = require("./group-visible-reply-guard");
+const helpers_1 = require("./helpers");
+const proxy_config_1 = require("./proxy-config");
+const constants_1 = require("./constants");
+const actionLog = (0, core_1.createSubsystemLogger)("channels/clawgram");
+/**
+ * Read scope as configured for the account. Left `undefined` when the key is
+ * absent so `isChatReadable` can tell "not configured" from "configured empty" —
+ * the first means no restriction, the second denies everything.
+ */
+function readAccountReadChats(account) {
+    const raw = account?.readChats;
+    if (raw === undefined || raw === null)
+        return undefined;
+    const entries = Array.isArray(raw) ? raw : [raw];
+    return entries.map((entry) => String(entry).trim()).filter(Boolean);
+}
+function resolveAccountReadChats(cfg, accountId) {
+    return readAccountReadChats(cfg?.channels?.["clawgram"]?.accounts?.[accountId]);
+}
+function parseOptionalThreadId(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? Math.trunc(value) : undefined;
+    }
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed || !/^\d+$/.test(trimmed)) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(trimmed, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+const createChannelPlugin = (runtimes) => {
+    const resolveRuntimeAccountId = (cfg, preferred) => {
+        const configured = (0, helpers_1.resolveConfiguredAccountId)(cfg, preferred);
+        if (configured && runtimes.has(configured)) {
+            return configured;
+        }
+        if (preferred?.trim()) {
+            return preferred.trim();
+        }
+        return configured ?? runtimes.keys().next().value;
+    };
+    return {
+        id: "clawgram",
+        meta: {
+            id: "clawgram",
+            label: "Clawgram",
+            selectionLabel: "Clawgram (GramJS)",
+            docsPath: "/channels/clawgram",
+            blurb: "Connect your personal Telegram account to OpenClaw via MTProto. Your AI assistant responds as you.",
+            aliases: ["tguserbot"],
+        },
+        capabilities: {
+            chatTypes: ["direct", "group"],
+            reactions: true,
+            threads: true,
+            media: true,
+            nativeCommands: false,
+            blockStreaming: false,
+        },
+        agentPrompt: {
+            messageToolHints: () => [
+                "Use clawgram to send Telegram replies from the connected personal account.",
+                "When replying in the current Telegram chat, omit `to`/`target` and clawgram will send to the current conversation automatically.",
+                "Explicit targets may be @username, numeric Telegram user id, phone/contact resolvable by Telegram, group chat ids, or clawgram:<target>.",
+                "For Telegram forum topics, send to the group chat id and pass the topic id separately as `threadId`.",
+            ],
+            messageToolCapabilities: () => [
+                "clawgram can reply in the current Telegram conversation when no explicit target is provided.",
+                "clawgram can send text messages to direct chats and groups from the connected personal account.",
+                "clawgram supports Telegram forum topics via the `threadId` parameter on group sends.",
+            ],
+        },
+        config: {
+            listAccountIds(cfg) {
+                const accounts = cfg?.channels?.["clawgram"]?.accounts;
+                if (!accounts || typeof accounts !== "object") {
+                    return [];
+                }
+                return Object.keys(accounts);
+            },
+            resolveAccount(cfg, accountId) {
+                const account = cfg?.channels?.["clawgram"]?.accounts?.[accountId];
+                return {
+                    apiId: Number(account?.apiId),
+                    apiHash: String(account?.apiHash ?? ""),
+                    sessionString: String(account?.sessionString ?? ""),
+                    allowFrom: (0, helpers_1.resolveAllowFrom)(account?.allowFrom),
+                    groups: (0, helpers_1.resolveGroups)(account?.groups),
+                    readChats: readAccountReadChats(account),
+                    enabled: account?.enabled,
+                    accountId,
+                    proxy: (0, proxy_config_1.resolveProxyConfig)(account?.proxy),
+                };
+            },
+        },
+        gateway: {
+            startAccount: async (ctx) => {
+                const { account, accountId, channelRuntime, cfg, log } = ctx;
+                if (!channelRuntime) {
+                    throw new Error("clawgram: channelRuntime is required");
+                }
+                if (runtimes.has(accountId)) {
+                    log?.warn?.("clawgram stale runtime detected, reconnecting", { accountId });
+                    await runtimes.get(accountId)?.stop().catch(() => undefined);
+                    runtimes.delete(accountId);
+                }
+                const gram = new gramjs_client_1.GramJsClientManager(account);
+                await gram.start();
+                runtimes.set(accountId, gram);
+                const pairing = (0, channel_pairing_1.createChannelPairingController)({
+                    // The controller only reads core.channel.pairing, but its parameter is typed
+                    // as the full PluginRuntime, and ctx (hence channelRuntime) is untyped.
+                    core: { channel: channelRuntime },
+                    channel: "clawgram",
+                    accountId,
+                });
+                const me = await gram.getMe();
+                const selfId = me?.id ? String(me.id) : undefined;
+                const selfUsername = (0, helpers_1.resolveActiveUsername)(me);
+                const selfLabel = (0, helpers_1.toDisplayName)({
+                    username: selfUsername,
+                    firstName: typeof me?.firstName === "string" ? me.firstName : undefined,
+                    lastName: typeof me?.lastName === "string" ? me.lastName : undefined,
+                    fallback: selfId,
+                });
+                log?.info?.("clawgram connected ------------------------------------------", {
+                    accountId,
+                    selfId,
+                    username: selfUsername,
+                    proxy: gram.getProxySummary(),
+                });
+                const client = gram.getClient();
+                const eventBuilder = new events_1.NewMessage({});
+                const eventHandler = async (event) => {
+                    try {
+                        const rawMessage = event?.message;
+                        const rawPeerUserId = rawMessage?.peerId?.userId;
+                        const rawPeerChatId = rawMessage?.peerId?.chatId;
+                        const rawPeerChannelId = rawMessage?.peerId?.channelId;
+                        const directLike = rawPeerUserId !== undefined ||
+                            (typeof rawMessage?.chatId === "number" && rawMessage.chatId > 0);
+                        if (directLike) {
+                            log?.info?.("clawgram raw direct-like event", {
+                                accountId,
+                                messageId: String(rawMessage?.id ?? ""),
+                                chatId: String(rawMessage?.chatId ?? ""),
+                                peerUserId: String(rawPeerUserId ?? ""),
+                                peerChatId: String(rawPeerChatId ?? ""),
+                                peerChannelId: String(rawPeerChannelId ?? ""),
+                                senderId: String(rawMessage?.senderId ?? rawMessage?.fromId?.userId ?? ""),
+                                out: rawMessage?.out === true,
+                                textLength: typeof rawMessage?.message === "string" ? rawMessage.message.length : typeof rawMessage?.text === "string" ? rawMessage.text.length : 0,
+                            });
+                        }
+                        const normalized = (0, normalize_1.normalizeTelegramEvent)(event, accountId);
+                        if (!normalized) {
+                            if (directLike) {
+                                log?.info?.("clawgram normalize returned null", {
+                                    accountId,
+                                    messageId: String(rawMessage?.id ?? ""),
+                                    chatId: String(rawMessage?.chatId ?? ""),
+                                    peerUserId: String(rawPeerUserId ?? ""),
+                                });
+                            }
+                            return;
+                        }
+                        const directReplyTarget = normalized.chatType === "direct"
+                            ? undefined
+                            : await (0, helpers_1.resolveReplyTarget)(rawMessage);
+                        const senderProfile = normalized.chatType === "direct"
+                            ? await (0, helpers_1.resolveSenderProfileWithTimeout)(rawMessage, {
+                                senderId: normalized.senderId,
+                                client,
+                            }, 1500)
+                            : await (0, helpers_1.resolveSenderProfile)(rawMessage, {
+                                senderId: normalized.senderId,
+                                client,
+                            });
+                        const replyTarget = normalized.chatType === "direct"
+                            ? normalized.chatId
+                            : await (0, helpers_1.resolveChatTarget)(rawMessage);
+                        if (replyTarget) {
+                            normalized.replyTarget = replyTarget;
+                        }
+                        if (!normalized.senderUsername && senderProfile.username) {
+                            normalized.senderUsername = senderProfile.username;
+                        }
+                        if (!normalized.senderDisplay && senderProfile.display) {
+                            normalized.senderDisplay = senderProfile.display;
+                        }
+                        if (normalized.isOutgoing) {
+                            if (normalized.chatType === "direct") {
+                                log?.info?.("clawgram skipping outgoing direct event", {
+                                    accountId,
+                                    chatId: normalized.chatId,
+                                    messageId: normalized.messageId,
+                                    senderId: normalized.senderId,
+                                });
+                            }
+                            return;
+                        }
+                        if (normalized.chatType === "channel") {
+                            log?.info?.("clawgram skipping channel inbound", {
+                                accountId,
+                                chatId: normalized.chatId,
+                                chatType: normalized.chatType,
+                                messageId: normalized.messageId,
+                            });
+                            return;
+                        }
+                        const text = normalized.text?.trim();
+                        if (!text) {
+                            log?.info?.("clawgram skipping empty inbound text", {
+                                accountId,
+                                chatId: normalized.chatId,
+                                messageId: normalized.messageId,
+                            });
+                            return;
+                        }
+                        const senderId = normalized.senderId ?? normalized.chatId;
+                        const isTelegramServiceDirect = normalized.chatType === "direct" &&
+                            (normalized.chatId === "777000" || senderId === "777000");
+                        const isSavedMessagesDirect = normalized.chatType === "direct" &&
+                            Boolean(selfId) &&
+                            normalized.chatId === selfId &&
+                            senderId === selfId;
+                        if (isTelegramServiceDirect) {
+                            log?.info?.("clawgram skipping Telegram service direct chat", {
+                                accountId,
+                                chatId: normalized.chatId,
+                                messageId: normalized.messageId,
+                                senderId,
+                            });
+                            return;
+                        }
+                        if (isSavedMessagesDirect) {
+                            log?.info?.("clawgram skipping Saved Messages direct chat", {
+                                accountId,
+                                chatId: normalized.chatId,
+                                messageId: normalized.messageId,
+                                senderId,
+                                selfId,
+                            });
+                            return;
+                        }
+                        const senderUsername = normalized.senderUsername;
+                        const senderLabel = normalized.senderDisplay || normalized.senderUsername || senderId;
+                        const conversationTarget = normalized.chatType === "direct"
+                            ? normalized.chatId
+                            : normalized.replyTarget ?? normalized.chatId;
+                        const conversationFallbackTargets = [
+                            normalized.chatType === "direct" ? directReplyTarget : undefined,
+                            normalized.chatType === "direct" ? normalized.replyTarget : undefined,
+                            normalized.chatType === "direct" && normalized.senderUsername ? `@${normalized.senderUsername}` : undefined,
+                            normalized.chatId,
+                        ].filter((target, index, items) => {
+                            if (!target || target === conversationTarget) {
+                                return false;
+                            }
+                            return items.findIndex((candidate) => candidate === target) === index;
+                        });
+                        const sendTextToConversation = async (args) => {
+                            const targets = [conversationTarget, ...conversationFallbackTargets];
+                            let lastError;
+                            for (const target of targets) {
+                                try {
+                                    return await gram.sendText({
+                                        target,
+                                        text: args.text,
+                                        replyToMessageId: args.replyToMessageId,
+                                        messageThreadId: args.messageThreadId,
+                                    });
+                                }
+                                catch (error) {
+                                    lastError = error;
+                                }
+                            }
+                            throw lastError;
+                        };
+                        const accountConfig = cfg?.channels?.["clawgram"]?.accounts?.[accountId] ??
+                            cfg?.channels?.["clawgram"] ??
+                            {};
+                        const directAllowFrom = (0, helpers_1.resolveAllowFrom)(accountConfig?.allowFrom ?? account?.allowFrom);
+                        const groups = (0, helpers_1.resolveGroups)(accountConfig?.groups ?? account?.groups);
+                        const dmPolicy = "open";
+                        if (normalized.chatType === "group") {
+                            const groupConfig = (0, helpers_1.resolveGroupConfig)(groups, normalized.chatId);
+                            if (!groupConfig) {
+                                log?.info?.("clawgram skipping group not present in groups config", {
+                                    accountId,
+                                    chatId: normalized.chatId,
+                                    messageId: normalized.messageId,
+                                });
+                                return;
+                            }
+                            if (groupConfig.enabled === false) {
+                                log?.info?.("clawgram skipping disabled group", {
+                                    accountId,
+                                    chatId: normalized.chatId,
+                                    messageId: normalized.messageId,
+                                });
+                                return;
+                            }
+                            if (!(0, helpers_1.isSenderAllowed)({
+                                allowFrom: groupConfig.allowFrom,
+                                senderId,
+                                senderUsername: normalized.senderUsername,
+                            })) {
+                                log?.info?.("clawgram blocking inbound group sender by allowFrom", {
+                                    accountId,
+                                    chatId: normalized.chatId,
+                                    messageId: normalized.messageId,
+                                    senderId,
+                                    username: normalized.senderUsername,
+                                    allowFrom: groupConfig.allowFrom,
+                                });
+                                return;
+                            }
+                            const scopedGroupPeerId = (0, helpers_1.buildScopedGroupPeerId)(accountId, normalized.chatId);
+                            const { route: inboundRoute, buildEnvelope } = (0, inbound_envelope_1.resolveInboundRouteEnvelopeBuilderWithRuntime)({
+                                cfg,
+                                channel: "clawgram",
+                                accountId,
+                                peer: {
+                                    kind: "group",
+                                    id: scopedGroupPeerId,
+                                },
+                                runtime: channelRuntime,
+                                sessionStore: cfg?.session?.store,
+                            });
+                            // channelRuntime comes from the untyped ctx, so the generic route type falls
+                            // back to the minimal RouteLike. The runtime value is a ResolvedAgentRoute.
+                            const route = inboundRoute;
+                            const wasMentioned = (0, helpers_1.hasTelegramMention)({
+                                cfg,
+                                agentId: route.agentId,
+                                selfUsername,
+                                text,
+                                message: rawMessage,
+                            });
+                            const wasReplyToSelf = await (0, helpers_1.isReplyToSelfMessage)(rawMessage, selfId);
+                            const mentionDecision = (0, channel_inbound_1.resolveInboundMentionDecision)({
+                                facts: {
+                                    canDetectMention: true,
+                                    wasMentioned,
+                                    hasAnyMention: /(^|\s)@[a-zA-Z0-9_]{5,}\b/.test(text),
+                                },
+                                policy: {
+                                    isGroup: true,
+                                    requireMention: groupConfig.groupPolicy === "mention",
+                                    allowTextCommands: false,
+                                    hasControlCommand: false,
+                                    commandAuthorized: true,
+                                },
+                            });
+                            log?.info?.("clawgram group mention gate", {
+                                accountId,
+                                chatId: normalized.chatId,
+                                messageId: normalized.messageId,
+                                selfUsername,
+                                mentionedFlag: rawMessage?.mentioned === true,
+                                hasEntities: Array.isArray(rawMessage?.entities) ? rawMessage.entities.length : 0,
+                                wasMentioned,
+                                wasReplyToSelf,
+                                shouldSkip: mentionDecision.shouldSkip,
+                                text,
+                            });
+                            if (groupConfig.groupPolicy === "mention" && mentionDecision.shouldSkip && !wasReplyToSelf) {
+                                log?.info?.("clawgram skipping group message without mention", {
+                                    accountId,
+                                    chatId: normalized.chatId,
+                                    messageId: normalized.messageId,
+                                    senderId,
+                                });
+                                return;
+                            }
+                            const { storePath, body } = buildEnvelope({
+                                channel: "Telegram",
+                                from: senderLabel,
+                                body: text,
+                                timestamp: normalized.timestamp,
+                            });
+                            const conversationRouteTarget = (0, helpers_1.buildConversationTarget)(normalized.chatId);
+                            const ctxPayload = channelRuntime.reply.finalizeInboundContext({
+                                Body: body,
+                                BodyForAgent: text,
+                                RawBody: text,
+                                CommandBody: text,
+                                From: conversationRouteTarget,
+                                To: conversationRouteTarget,
+                                SessionKey: route.sessionKey,
+                                AccountId: route.accountId ?? accountId,
+                                ChatType: "group",
+                                ConversationLabel: senderLabel,
+                                SenderId: senderId,
+                                SenderUsername: normalized.senderUsername,
+                                SenderName: normalized.senderDisplay,
+                                GroupId: normalized.chatId,
+                                GroupSubject: normalized.chatId,
+                                WasMentioned: mentionDecision.effectiveWasMentioned || wasReplyToSelf,
+                                WasReplyToSelf: wasReplyToSelf,
+                                Provider: "telegram",
+                                Surface: "clawgram",
+                                MessageSid: normalized.messageId,
+                                MessageSidFull: normalized.messageId,
+                                Timestamp: normalized.timestamp,
+                                ReplyToId: normalized.replyToMessageId,
+                                MessageThreadId: normalized.messageThreadId,
+                                NativeChannelId: normalized.chatId,
+                                OriginatingChannel: "clawgram",
+                                OriginatingTo: conversationRouteTarget,
+                            });
+                            const groupReplyAddress = (0, group_reply_address_1.buildGroupReplyAddress)({
+                                senderUsername: normalized.senderUsername,
+                                senderDisplay: normalized.senderDisplay,
+                                senderId,
+                            });
+                            (0, group_reply_address_1.rememberGroupReplyAddress)({
+                                accountId: route.accountId ?? accountId,
+                                chatId: normalized.chatId,
+                                replyToId: normalized.messageId,
+                                address: groupReplyAddress,
+                            });
+                            const messageThreadId = parseOptionalThreadId(normalized.messageThreadId);
+                            const groupTypingTarget = normalized.chatId;
+                            await gram.withTyping(groupTypingTarget, async () => {
+                                log?.info?.("clawgram dispatching group reply", {
+                                    accountId,
+                                    chatId: normalized.chatId,
+                                    messageId: normalized.messageId,
+                                    routeSessionKey: route.sessionKey,
+                                    storePath,
+                                });
+                                await channelRuntime.session.recordInboundSession({
+                                    storePath,
+                                    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+                                    ctx: ctxPayload,
+                                    updateLastRoute: {
+                                        sessionKey: route.sessionKey,
+                                        channel: constants_1.CHANNEL_ID,
+                                        to: conversationRouteTarget,
+                                        accountId: route.accountId ?? accountId,
+                                    },
+                                    onRecordError: (err) => {
+                                        log?.info?.("clawgram failed to update group last route", {
+                                            accountId,
+                                            chatId: normalized.chatId,
+                                            messageId: normalized.messageId,
+                                            error: String(err),
+                                        });
+                                    },
+                                });
+                                const dispatchBase = (0, inbound_reply_dispatch_1.buildInboundReplyDispatchBase)({
+                                    cfg,
+                                    channel: "clawgram",
+                                    accountId: route.accountId ?? accountId,
+                                    route,
+                                    storePath,
+                                    ctxPayload,
+                                    core: { channel: channelRuntime },
+                                });
+                                const { onModelSelected, ...replyPipeline } = (0, channel_reply_pipeline_1.createChannelReplyPipeline)({
+                                    cfg,
+                                    agentId: route.agentId,
+                                    channel: "clawgram",
+                                    accountId: route.accountId ?? accountId,
+                                });
+                                const dispatchResult = await dispatchBase.dispatchReplyWithBufferedBlockDispatcher({
+                                    ctx: ctxPayload,
+                                    cfg,
+                                    dispatcherOptions: {
+                                        ...replyPipeline,
+                                        deliver: async (payload) => {
+                                            const outboundText = typeof payload.text === "string" ? payload.text.trim() : "";
+                                            log?.info?.("clawgram deliver group payload", {
+                                                accountId,
+                                                chatId: normalized.chatId,
+                                                messageId: normalized.messageId,
+                                                payloadText: outboundText,
+                                                payloadReplyToId: payload.replyToId ?? null,
+                                            });
+                                            if (!outboundText) {
+                                                return;
+                                            }
+                                            // The agent may decline to answer by returning the shared
+                                            // silent token. Drop it before addressing: otherwise the
+                                            // reply-address prefix turns it into a visible message.
+                                            const visibleText = (0, helpers_1.stripSilentReplyToken)(outboundText);
+                                            if (!visibleText) {
+                                                log?.info?.("clawgram suppressing silent group reply", {
+                                                    accountId,
+                                                    chatId: normalized.chatId,
+                                                    messageId: normalized.messageId,
+                                                });
+                                                return;
+                                            }
+                                            const replyToMessageId = payload.replyToId ? Number(payload.replyToId) : Number(normalized.messageId);
+                                            const rememberedAddress = (0, group_reply_address_1.consumeGroupReplyAddress)({
+                                                accountId: route.accountId ?? accountId,
+                                                chatId: normalized.chatId,
+                                                replyToId: payload.replyToId ?? normalized.messageId,
+                                            });
+                                            await sendTextToConversation({
+                                                text: (0, helpers_1.prefixReplyTextToAddress)(visibleText, rememberedAddress ?? groupReplyAddress),
+                                                replyToMessageId,
+                                                messageThreadId,
+                                            });
+                                        },
+                                        onError: (err, info) => {
+                                            log?.error?.("clawgram failed to dispatch group reply", {
+                                                accountId,
+                                                chatId: normalized.chatId,
+                                                messageId: normalized.messageId,
+                                                kind: info.kind,
+                                                error: String(err),
+                                            });
+                                        },
+                                    },
+                                    replyOptions: {
+                                        onModelSelected,
+                                    },
+                                });
+                                log?.info?.("clawgram group dispatch completed", {
+                                    accountId,
+                                    chatId: normalized.chatId,
+                                    messageId: normalized.messageId,
+                                    queuedFinal: dispatchResult?.queuedFinal ?? null,
+                                    counts: dispatchResult?.counts ?? null,
+                                });
+                                const dispatchCounts = dispatchResult?.counts ?? { tool: 0, block: 0, final: 0 };
+                                const nothingDelivered = dispatchResult?.queuedFinal !== true &&
+                                    (dispatchCounts.tool ?? 0) === 0 &&
+                                    (dispatchCounts.block ?? 0) === 0 &&
+                                    (dispatchCounts.final ?? 0) === 0;
+                                if (nothingDelivered) {
+                                    const fallbackText = (0, helpers_1.readLatestAssistantFallbackFromTranscript)(route.sessionKey, storePath);
+                                    // A suppressed silent reply legitimately delivers nothing, so
+                                    // this fallback fires right after it. Without the same check
+                                    // the token would be read back from the transcript and sent.
+                                    const visibleFallbackText = fallbackText ? (0, helpers_1.stripSilentReplyToken)(fallbackText) : "";
+                                    if (fallbackText && !visibleFallbackText) {
+                                        log?.info?.("clawgram skipping silent transcript fallback", {
+                                            accountId,
+                                            chatId: normalized.chatId,
+                                            messageId: normalized.messageId,
+                                            routeSessionKey: route.sessionKey,
+                                        });
+                                    }
+                                    else if (visibleFallbackText) {
+                                        log?.warn?.("clawgram using transcript fallback reply", {
+                                            accountId,
+                                            chatId: normalized.chatId,
+                                            messageId: normalized.messageId,
+                                            routeSessionKey: route.sessionKey,
+                                            fallbackText: visibleFallbackText,
+                                        });
+                                        await sendTextToConversation({
+                                            text: (0, helpers_1.prefixReplyTextToAddress)(visibleFallbackText, groupReplyAddress),
+                                            replyToMessageId: Number(normalized.messageId),
+                                            messageThreadId,
+                                        });
+                                    }
+                                    else {
+                                        log?.warn?.("clawgram transcript fallback unavailable", {
+                                            accountId,
+                                            chatId: normalized.chatId,
+                                            messageId: normalized.messageId,
+                                            routeSessionKey: route.sessionKey,
+                                        });
+                                    }
+                                }
+                            }, {
+                                readMessageId: Number(normalized.messageId),
+                                messageThreadId,
+                            });
+                            log?.info?.("clawgram group inbound handled", {
+                                accountId,
+                                chatId: normalized.chatId,
+                                messageId: normalized.messageId,
+                                senderId,
+                                senderLabel,
+                                wasMentioned: mentionDecision.effectiveWasMentioned,
+                                wasReplyToSelf,
+                            });
+                            return;
+                        }
+                        if (!(0, helpers_1.isSenderAllowed)({
+                            allowFrom: directAllowFrom,
+                            senderId,
+                            senderUsername: normalized.senderUsername,
+                        })) {
+                            log?.info?.("clawgram direct allowFrom mismatch", {
+                                accountId,
+                                senderId,
+                                senderUsername: normalized.senderUsername,
+                                allowFrom: directAllowFrom,
+                            });
+                            return;
+                        }
+                        const access = await (0, direct_dm_1.resolveInboundDirectDmAccessWithRuntime)({
+                            cfg,
+                            channel: "clawgram",
+                            accountId,
+                            dmPolicy,
+                            allowFrom: directAllowFrom,
+                            senderId,
+                            rawBody: text,
+                            runtime: channelRuntime.commands,
+                            isSenderAllowed: (_candidateSenderId, allowEntries) => (0, helpers_1.isSenderAllowed)({
+                                allowFrom: allowEntries,
+                                senderId,
+                                senderUsername,
+                            }),
+                            readStoreAllowFrom: pairing.readStoreForDmPolicy,
+                        });
+                        if (access.access.decision === "block") {
+                            log?.info?.("clawgram blocking inbound direct message", {
+                                accountId,
+                                chatId: normalized.chatId,
+                                messageId: normalized.messageId,
+                                senderId,
+                                reason: access.access.reason,
+                                reasonCode: access.access.reasonCode,
+                            });
+                            return;
+                        }
+                        if (access.access.decision === "pairing") {
+                            await pairing.issueChallenge({
+                                senderId,
+                                senderIdLine: `Your Telegram user id: ${senderId}`,
+                                meta: {
+                                    username: normalized.senderUsername,
+                                    name: normalized.senderDisplay,
+                                },
+                                sendPairingReply: async (pairingText) => {
+                                    await sendTextToConversation({
+                                        text: pairingText,
+                                    });
+                                },
+                                onReplyError: (err) => {
+                                    log?.info?.("clawgram pairing reply failed", {
+                                        accountId,
+                                        chatId: normalized.chatId,
+                                        senderId,
+                                        error: String(err),
+                                    });
+                                },
+                            });
+                            log?.info?.("clawgram pairing required for inbound direct message", {
+                                accountId,
+                                chatId: normalized.chatId,
+                                messageId: normalized.messageId,
+                                senderId,
+                            });
+                            return;
+                        }
+                        await gram.withTyping(conversationTarget, async () => {
+                            await (0, direct_dm_1.dispatchInboundDirectDmWithRuntime)({
+                                cfg,
+                                runtime: { channel: channelRuntime },
+                                channel: "clawgram",
+                                channelLabel: "Telegram",
+                                accountId,
+                                peer: {
+                                    kind: "direct",
+                                    id: senderId,
+                                },
+                                senderId,
+                                senderAddress: `telegram:${senderId}`,
+                                recipientAddress: selfId ? `telegram:${selfId}` : `telegram:${accountId}`,
+                                conversationLabel: senderLabel,
+                                rawBody: text,
+                                messageId: normalized.messageId,
+                                timestamp: normalized.timestamp,
+                                commandAuthorized: access.commandAuthorized,
+                                provider: "telegram",
+                                surface: "clawgram",
+                                originatingChannel: "clawgram",
+                                originatingTo: senderId,
+                                extraContext: {
+                                    SenderUsername: normalized.senderUsername,
+                                    SenderName: normalized.senderDisplay,
+                                    ReplyToId: normalized.replyToMessageId,
+                                    NativeChannelId: normalized.chatId,
+                                },
+                                deliver: async (payload) => {
+                                    const outboundText = typeof payload.text === "string" ? payload.text.trim() : "";
+                                    if (!outboundText) {
+                                        return;
+                                    }
+                                    const visibleText = (0, helpers_1.stripSilentReplyToken)(outboundText);
+                                    if (!visibleText) {
+                                        log?.info?.("clawgram suppressing silent direct reply", {
+                                            accountId,
+                                            chatId: normalized.chatId,
+                                            messageId: normalized.messageId,
+                                        });
+                                        return;
+                                    }
+                                    await sendTextToConversation({
+                                        text: visibleText,
+                                        replyToMessageId: payload.replyToId ? Number(payload.replyToId) : undefined,
+                                    });
+                                },
+                                onRecordError: (err) => {
+                                    log?.info?.("clawgram failed to record inbound session", {
+                                        accountId,
+                                        chatId: normalized.chatId,
+                                        messageId: normalized.messageId,
+                                        error: String(err),
+                                    });
+                                },
+                                onDispatchError: (err, info) => {
+                                    log?.info?.("clawgram failed to dispatch reply", {
+                                        accountId,
+                                        chatId: normalized.chatId,
+                                        messageId: normalized.messageId,
+                                        kind: info.kind,
+                                        error: String(err),
+                                    });
+                                },
+                            });
+                        }, {
+                            readMessageId: Number(normalized.messageId),
+                        });
+                        log?.info?.("clawgram inbound handled", {
+                            accountId,
+                            chatId: normalized.chatId,
+                            messageId: normalized.messageId,
+                            senderId,
+                            senderLabel,
+                        });
+                    }
+                    catch (error) {
+                        const rawMessage = event?.message;
+                        log?.error?.("clawgram inbound handling failed", {
+                            accountId,
+                            chatId: String(rawMessage?.chatId ?? rawMessage?.peerId?.userId ?? rawMessage?.peerId?.chatId ?? rawMessage?.peerId?.channelId ?? ""),
+                            messageId: String(rawMessage?.id ?? ""),
+                            error: String(error),
+                        });
+                        log?.info?.("clawgram inbound preflight failed", {
+                            accountId,
+                            chatId: String(rawMessage?.chatId ?? rawMessage?.peerId?.userId ?? rawMessage?.peerId?.chatId ?? rawMessage?.peerId?.channelId ?? ""),
+                            messageId: String(rawMessage?.id ?? ""),
+                            error: String(error),
+                        });
+                    }
+                };
+                client.addEventHandler(eventHandler, eventBuilder);
+                // Being added to a chat arrives as a service message, which `NewMessage`
+                // drops — so joins are observed on the raw update stream instead. Only
+                // additions of this account are journalled; who else joins is not ours
+                // to record.
+                const joinsJournalPath = (0, joins_1.resolveJoinsJournalPath)(account, accountId);
+                const joinEventHandler = async (update) => {
+                    try {
+                        const join = (0, joins_1.parseJoinEvent)(update?.message, selfId);
+                        if (!join) {
+                            return;
+                        }
+                        (0, joins_1.appendJoinRecord)(joinsJournalPath, join);
+                        // Ids of people stay out of the log; the chat and the fact are enough
+                        // to debug, and the journal itself holds the detail.
+                        log?.info?.("clawgram join observed", {
+                            accountId,
+                            chatId: join.chatId,
+                            via: join.via,
+                            hasInviter: join.inviterId !== undefined,
+                        });
+                    }
+                    catch (error) {
+                        log?.warn?.("clawgram join observation failed", {
+                            accountId,
+                            error: String(error),
+                        });
+                    }
+                };
+                const joinEventBuilder = new events_1.Raw({});
+                client.addEventHandler(joinEventHandler, joinEventBuilder);
+                await (0, channel_runtime_1.waitUntilAbort)(ctx.abortSignal, async () => {
+                    client.removeEventHandler(eventHandler, eventBuilder);
+                    client.removeEventHandler(joinEventHandler, joinEventBuilder);
+                    const runtime = runtimes.get(accountId);
+                    if (!runtime) {
+                        return;
+                    }
+                    await runtime.stop();
+                    runtimes.delete(accountId);
+                    console.info("clawgram disconnected", {
+                        accountId,
+                        selfLabel,
+                    });
+                });
+            },
+        },
+        messaging: {
+            targetPrefixes: [constants_1.CHANNEL_ID, "tguserbot", "telegram", "tg"],
+            normalizeTarget(raw) {
+                const normalized = (0, helpers_1.normalizeOutboundTarget)(raw);
+                return normalized || undefined;
+            },
+            inferTargetChatType(params) {
+                const kind = (0, helpers_1.inferOutboundTargetKind)(params.to);
+                if (kind === "group" || kind === "channel") {
+                    return kind;
+                }
+                if (kind === "user") {
+                    return "direct";
+                }
+                return undefined;
+            },
+            targetResolver: {
+                looksLikeId(raw, normalized) {
+                    const candidate = (normalized?.trim() || (0, helpers_1.normalizeOutboundTarget)(raw)).trim();
+                    if (!candidate) {
+                        return false;
+                    }
+                    if (candidate === "me" || candidate === "self" || candidate === "saved") {
+                        return true;
+                    }
+                    if (candidate.startsWith("@")) {
+                        return true;
+                    }
+                    return /^-?\d+$/.test(candidate);
+                },
+                async resolveTarget(params) {
+                    const target = params.normalized?.trim() || (0, helpers_1.normalizeOutboundTarget)(params.input);
+                    if (!target) {
+                        return null;
+                    }
+                    const inferredKind = (0, helpers_1.inferOutboundTargetKind)(params.input, params.preferredKind);
+                    const accountId = resolveRuntimeAccountId(params.cfg, params.accountId);
+                    const gram = accountId ? runtimes.get(accountId) : undefined;
+                    const resolved = gram ? await gram.resolvePeer(target, { kind: inferredKind }).catch(() => undefined) : undefined;
+                    const kind = resolved?.chatType === "group" || inferredKind === "group"
+                        ? "group"
+                        : resolved?.chatType === "channel" || inferredKind === "channel"
+                            ? "channel"
+                            : "user";
+                    return {
+                        to: resolved?.chatId ?? target,
+                        kind,
+                        source: "normalized",
+                    };
+                },
+            },
+            async resolveOutboundSessionRoute(params) {
+                const rawTarget = params.resolvedTarget?.to ?? params.target;
+                const targetKind = (0, helpers_1.inferOutboundTargetKind)(rawTarget, params.resolvedTarget?.kind);
+                const target = (0, helpers_1.normalizeOutboundTarget)(rawTarget);
+                if (!target) {
+                    return null;
+                }
+                const accountId = resolveRuntimeAccountId(params.cfg, params.accountId);
+                const gram = accountId ? runtimes.get(accountId) : undefined;
+                const resolved = gram ? await gram.resolvePeer(target, { kind: targetKind }).catch(() => undefined) : undefined;
+                const peerId = resolved?.chatId ?? target;
+                const chatType = resolved?.chatType === "group" || targetKind === "group"
+                    ? "group"
+                    : resolved?.chatType === "channel" || targetKind === "channel"
+                        ? "channel"
+                        : "direct";
+                const scopedPeerId = chatType === "group" || chatType === "channel"
+                    ? (0, helpers_1.buildScopedGroupPeerId)(accountId, peerId)
+                    : peerId;
+                return (0, core_1.buildChannelOutboundSessionRoute)({
+                    cfg: params.cfg,
+                    agentId: params.agentId,
+                    channel: constants_1.CHANNEL_ID,
+                    accountId,
+                    peer: {
+                        kind: (0, helpers_1.routeKindFromChatType)(chatType),
+                        id: scopedPeerId,
+                    },
+                    chatType,
+                    from: accountId ?? "default",
+                    to: target,
+                    threadId: params.threadId ?? undefined,
+                });
+            },
+            formatTargetDisplay(params) {
+                const display = params.display?.trim();
+                if (display) {
+                    return display;
+                }
+                const target = (0, helpers_1.normalizeOutboundTarget)(params.target);
+                return target.startsWith("@") ? target : `telegram:${target}`;
+            },
+        },
+        actions: {
+            describeMessageTool: ({ cfg, accountId }) => {
+                const resolvedAccountId = resolveRuntimeAccountId(cfg, accountId);
+                if (!resolvedAccountId) {
+                    return null;
+                }
+                return {
+                    actions: ["send", "read", "participants", "joins"],
+                    capabilities: [],
+                };
+            },
+            extractToolSend: ({ args }) => (0, tool_send_1.extractToolSend)(args, "sendMessage"),
+            handleAction: async ({ action, params, cfg, accountId, dryRun, toolContext }) => {
+                // `read` is what OpenClaw core dispatches (`openclaw message read`,
+                // MCP `messages_read`). `list` is accepted as a synonym so a caller that
+                // guessed the other obvious name is not silently refused.
+                if (action === "read" || action === "list") {
+                    const listParams = (0, history_1.parseListMessagesParams)(params);
+                    const listAccountId = resolveRuntimeAccountId(cfg, accountId);
+                    if (!listAccountId) {
+                        throw new Error("clawgram: no configured account found");
+                    }
+                    // Reading is not a side effect, so a dry run still answers — reporting
+                    // an empty window would look like a quiet chat rather than a no-op.
+                    if (!(0, history_1.isChatReadable)(listParams.target, resolveAccountReadChats(cfg, listAccountId))) {
+                        actionLog.warn("clawgram list refused: chat outside read scope", {
+                            accountId: listAccountId,
+                            target: listParams.target,
+                        });
+                        throw new Error(`clawgram: not-allowed-chat ${listParams.target}`);
+                    }
+                    const listGram = runtimes.get(listAccountId);
+                    if (!listGram) {
+                        throw new Error(`clawgram: runtime not found for account ${listAccountId}`);
+                    }
+                    const history = await listGram.listMessages(listParams);
+                    // Metadata only. Message text is the user's correspondence and has no
+                    // business in a log that is read while debugging something else.
+                    actionLog.info("clawgram handleAction list completed", {
+                        accountId: listAccountId,
+                        target: listParams.target,
+                        limit: listParams.limit,
+                        since: listParams.since ?? null,
+                        until: listParams.until ?? null,
+                        returned: history.messages.length,
+                        truncated: history.truncated,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        accountId: listAccountId,
+                        chatId: history.chatId ?? listParams.target,
+                        count: history.messages.length,
+                        truncated: history.truncated,
+                        messages: history.messages,
+                    });
+                }
+                // Membership is a read, so the same `readChats` scope that gates history
+                // gates it too: this cannot become a way to enumerate chats the account
+                // was never allowed to read.
+                if (action === "participants" || action === "members") {
+                    const participantsParams = (0, history_1.parseListParticipantsParams)(params);
+                    const participantsAccountId = resolveRuntimeAccountId(cfg, accountId);
+                    if (!participantsAccountId) {
+                        throw new Error("clawgram: no configured account found");
+                    }
+                    if (!(0, history_1.isChatReadable)(participantsParams.target, resolveAccountReadChats(cfg, participantsAccountId))) {
+                        actionLog.warn("clawgram participants refused: chat outside read scope", {
+                            accountId: participantsAccountId,
+                            target: participantsParams.target,
+                        });
+                        throw new Error(`clawgram: not-allowed-chat ${participantsParams.target}`);
+                    }
+                    const participantsGram = runtimes.get(participantsAccountId);
+                    if (!participantsGram) {
+                        throw new Error(`clawgram: runtime not found for account ${participantsAccountId}`);
+                    }
+                    const membership = await participantsGram.listParticipants(participantsParams);
+                    // Counts only. Member ids are personal data and have no business in a
+                    // log that is read while debugging something else.
+                    actionLog.info("clawgram handleAction participants completed", {
+                        accountId: participantsAccountId,
+                        target: participantsParams.target,
+                        limit: participantsParams.limit,
+                        returned: membership.participants.length,
+                        truncated: membership.truncated,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        accountId: participantsAccountId,
+                        chatId: membership.chatId ?? participantsParams.target,
+                        count: membership.participants.length,
+                        truncated: membership.truncated,
+                        participants: membership.participants,
+                    });
+                }
+                // Where this account was recently added, and by whom. Reading the journal
+                // has no scope check of its own: it only ever contains chats this account
+                // was put into, which is exactly what the caller is allowed to learn.
+                if (action === "joins") {
+                    const joinsParams = (0, joins_1.parseJoinsParams)(params);
+                    const joinsAccountId = resolveRuntimeAccountId(cfg, accountId);
+                    if (!joinsAccountId) {
+                        throw new Error("clawgram: no configured account found");
+                    }
+                    const journalPath = (0, joins_1.resolveJoinsJournalPath)(cfg?.channels?.["clawgram"]?.accounts?.[joinsAccountId], joinsAccountId);
+                    const selected = (0, joins_1.selectJoinRecords)((0, joins_1.readJoinRecords)(journalPath), joinsParams);
+                    actionLog.info("clawgram handleAction joins completed", {
+                        accountId: joinsAccountId,
+                        since: joinsParams.since ?? null,
+                        limit: joinsParams.limit,
+                        returned: selected.length,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        accountId: joinsAccountId,
+                        count: selected.length,
+                        joins: selected,
+                    });
+                }
+                if (action !== "send") {
+                    throw new Error(`clawgram: unsupported message action ${action}`);
+                }
+                const rawTo = (0, helpers_1.resolveActionTarget)(params, toolContext);
+                const targetKind = (0, helpers_1.inferOutboundTargetKind)(rawTo);
+                const to = (0, helpers_1.normalizeOutboundTarget)(rawTo);
+                const replyToId = (0, param_readers_1.readStringOrNumberParam)(params, "replyToId") ?? (0, param_readers_1.readStringOrNumberParam)(params, "replyTo");
+                const threadId = (0, param_readers_1.readStringOrNumberParam)(params, "threadId");
+                const messageThreadId = parseOptionalThreadId(threadId);
+                actionLog.info("clawgram handleAction send", {
+                    requestedAccountId: accountId,
+                    dryRun: dryRun === true,
+                    rawTo,
+                    to,
+                    targetKind,
+                    replyToId: replyToId ?? null,
+                    threadId: threadId ?? null,
+                    toolContextCurrentChannelId: toolContext?.currentChannelId ?? null,
+                });
+                const resolvedAccountId = resolveRuntimeAccountId(cfg, accountId);
+                if (!resolvedAccountId) {
+                    throw new Error("clawgram: no configured account found");
+                }
+                const currentChannelId = toolContext?.currentChannelId?.trim() ?? "";
+                const currentMessageId = toolContext?.currentMessageId;
+                const currentChannelTarget = currentChannelId ? (0, helpers_1.normalizeOutboundTarget)(currentChannelId) : "";
+                const sendingToCurrentGroup = Boolean(currentChannelTarget &&
+                    currentChannelTarget === to &&
+                    targetKind === "group");
+                if (sendingToCurrentGroup &&
+                    !replyToId &&
+                    currentMessageId !== null &&
+                    currentMessageId !== undefined &&
+                    (0, group_visible_reply_guard_1.hasRecentVisibleGroupReply)({
+                        accountId: resolvedAccountId,
+                        chatId: to,
+                        currentMessageId,
+                    })) {
+                    actionLog.warn("clawgram suppressing duplicate visible group reply", {
+                        accountId: resolvedAccountId,
+                        to,
+                        currentMessageId: String(currentMessageId),
+                        toolContextCurrentChannelId: currentChannelId || null,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        suppressedDuplicate: true,
+                        to,
+                        accountId: resolvedAccountId,
+                    });
+                }
+                const groupReplyAddress = (0, group_reply_address_1.consumeGroupReplyAddress)({
+                    accountId: resolvedAccountId,
+                    chatId: to,
+                    replyToId,
+                });
+                const text = (0, helpers_1.prefixReplyTextToAddress)((0, helpers_1.readMessageText)(params).replaceAll("\\n", "\n"), groupReplyAddress);
+                if (!text) {
+                    throw new Error("clawgram: message text is required");
+                }
+                if (dryRun) {
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        dryRun: true,
+                        to,
+                        accountId: resolvedAccountId,
+                    });
+                }
+                const gram = runtimes.get(resolvedAccountId);
+                if (!gram) {
+                    throw new Error(`clawgram: runtime not found for account ${resolvedAccountId}`);
+                }
+                const sent = await gram.sendText({
+                    target: to,
+                    text,
+                    targetKind,
+                    replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(rawTo, replyToId),
+                    messageThreadId,
+                });
+                if (sendingToCurrentGroup &&
+                    !replyToId &&
+                    currentMessageId !== null &&
+                    currentMessageId !== undefined) {
+                    (0, group_visible_reply_guard_1.rememberVisibleGroupReply)({
+                        accountId: resolvedAccountId,
+                        chatId: to,
+                        currentMessageId,
+                    });
+                }
+                actionLog.info("clawgram handleAction send completed", {
+                    accountId: resolvedAccountId,
+                    to,
+                    replyToId: replyToId ?? null,
+                    sentMessageId: String(sent?.id ?? ""),
+                });
+                return (0, core_1.jsonResult)({
+                    ok: true,
+                    to,
+                    accountId: resolvedAccountId,
+                    messageId: String(sent?.id ?? ""),
+                });
+            },
+        },
+        outbound: {
+            async resolveTarget(ctx) {
+                actionLog.info("clawgram outbound resolveTarget", {
+                    accountId: ctx.accountId,
+                    rawTo: ctx.to,
+                });
+                const gram = runtimes.get(ctx.accountId);
+                if (!gram) {
+                    throw new Error(`clawgram: runtime not found for account ${ctx.accountId}`);
+                }
+                const targetKind = (0, helpers_1.inferOutboundTargetKind)(ctx.to);
+                const target = (0, helpers_1.normalizeOutboundTarget)(ctx.to);
+                return {
+                    ok: true,
+                    to: (await gram.resolvePeer(target, { kind: targetKind })).chatId ?? target,
+                };
+            },
+            async sendText(ctx) {
+                actionLog.info("clawgram outbound sendText", {
+                    accountId: ctx.accountId,
+                    rawTo: ctx.to,
+                    replyToId: ctx.replyToId ?? null,
+                    threadId: ctx.threadId ?? null,
+                    text: ctx.text,
+                });
+                const gram = runtimes.get(ctx.accountId);
+                if (!gram) {
+                    throw new Error(`clawgram: runtime not found for account ${ctx.accountId}`);
+                }
+                const groupReplyAddress = (0, group_reply_address_1.consumeGroupReplyAddress)({
+                    accountId: ctx.accountId,
+                    chatId: ctx.to,
+                    replyToId: ctx.replyToId,
+                });
+                const targetKind = (0, helpers_1.inferOutboundTargetKind)(ctx.to);
+                const target = (0, helpers_1.normalizeOutboundTarget)(ctx.to);
+                const messageThreadId = parseOptionalThreadId(ctx.threadId);
+                const sent = await gram.sendText({
+                    target,
+                    text: (0, helpers_1.prefixReplyTextToAddress)(ctx.text, groupReplyAddress),
+                    targetKind,
+                    replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(ctx.to, ctx.replyToId),
+                    messageThreadId,
+                });
+                actionLog.info("clawgram outbound sendText completed", {
+                    accountId: ctx.accountId,
+                    to: target,
+                    targetKind,
+                    replyToId: ctx.replyToId ?? null,
+                    sentMessageId: String(sent?.id ?? ""),
+                });
+                return {
+                    ok: true,
+                    messageId: String(sent?.id ?? ""),
+                };
+            },
+            async sendMedia(ctx) {
+                const gram = runtimes.get(ctx.accountId);
+                if (!gram) {
+                    throw new Error(`clawgram: runtime not found for account ${ctx.accountId}`);
+                }
+                actionLog.info("clawgram outbound sendMedia", {
+                    accountId: ctx.accountId,
+                    to: ctx.to,
+                    replyToId: ctx.replyToId ?? null,
+                    threadId: ctx.threadId ?? null,
+                    filePath: ctx.filePath ?? null,
+                    mediaUrl: ctx.mediaUrl ?? null,
+                    hasText: Boolean(ctx.text),
+                    hasCaption: Boolean(ctx.caption),
+                });
+                const file = ctx.filePath ?? ctx.mediaUrl;
+                if (!file) {
+                    throw new Error("clawgram: sendMedia requires filePath or mediaUrl");
+                }
+                const messageThreadId = parseOptionalThreadId(ctx.threadId);
+                const sent = await gram.sendMedia({
+                    target: ctx.to,
+                    file,
+                    caption: ctx.caption ?? ctx.text,
+                    replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(ctx.to, ctx.replyToId),
+                    messageThreadId,
+                });
+                actionLog.info("clawgram outbound sendMedia completed", {
+                    accountId: ctx.accountId,
+                    to: ctx.to,
+                    replyToId: ctx.replyToId ?? null,
+                    sentMessageId: String(sent?.id ?? ""),
+                });
+                return {
+                    ok: true,
+                    messageId: String(sent?.id ?? ""),
+                };
+            },
+        },
+    };
+};
+exports.createChannelPlugin = createChannelPlugin;