@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/converters/video-chat.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "video_chat" message type.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertVideoChat: ContentConverterFn;

package/src/messaging/converters/video-chat.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "video_chat" message type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertVideoChat = void 0;
+const utils_1 = require("./utils.js");
+const convertVideoChat = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const topic = parsed?.topic ?? '';
+    const meetingNo = parsed?.meet_number?.trim() ?? '';
+    const parts = [];
+    if (topic) {
+        parts.push(`Topic: ${topic}`);
+    }
+    if (parsed?.start_time) {
+        parts.push(`Start time: ${(0, utils_1.millisToDatetime)(parsed.start_time)}`);
+    }
+    if (meetingNo) {
+        parts.push(`Meeting number: ${meetingNo}`);
+    }
+    const inner = parts.join('\n') || '[video chat]';
+    return {
+        content: `<meeting>${inner}</meeting>`,
+        resources: [],
+    };
+};
+exports.convertVideoChat = convertVideoChat;

package/src/messaging/converters/video.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "video" and "media" message types.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertVideo: ContentConverterFn;

package/src/messaging/converters/video.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "video" and "media" message types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertVideo = void 0;
+const utils_1 = require("./utils.js");
+const convertVideo = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const fileKey = parsed?.file_key;
+    if (!fileKey) {
+        return { content: '[video]', resources: [] };
+    }
+    const fileName = parsed?.file_name ?? '';
+    const duration = parsed?.duration;
+    const coverKey = parsed?.image_key;
+    const nameAttr = fileName ? ` name="${fileName}"` : '';
+    const durationAttr = duration != null ? ` duration="${(0, utils_1.formatDuration)(duration)}"` : '';
+    return {
+        content: `<video key="${fileKey}"${nameAttr}${durationAttr}/>`,
+        resources: [
+            {
+                type: 'video',
+                fileKey,
+                fileName: fileName || undefined,
+                duration: duration ?? undefined,
+                coverImageKey: coverKey ?? undefined,
+            },
+        ],
+    };
+};
+exports.convertVideo = convertVideo;

package/src/messaging/converters/vote.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "vote" message type.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertVote: ContentConverterFn;

package/src/messaging/converters/vote.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "vote" message type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertVote = void 0;
+const utils_1 = require("./utils.js");
+const convertVote = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const topic = parsed?.topic ?? '';
+    const options = parsed?.options ?? [];
+    const parts = [];
+    if (topic) {
+        parts.push(topic);
+    }
+    for (const opt of options) {
+        parts.push(`• ${opt}`);
+    }
+    const inner = parts.join('\n') || '[vote]';
+    return {
+        content: `<vote>\n${inner}\n</vote>`,
+        resources: [],
+    };
+};
+exports.convertVote = convertVote;

package/src/messaging/inbound/bot-content.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Reply-routing decisions for the Feishu dispatch path.
+ *
+ * In bot-to-bot group scenarios, Feishu will pull thread-style replies into
+ * a hidden "topic view" that group members cannot see (#32980). The peer bot
+ * keeps receiving messages but humans in the chat see nothing — a silent
+ * failure mode that turns bot↔bot chat into a black hole.
+ *
+ * This module centralizes the three signals that decide where a reply lands:
+ *   1. isGroup            — DMs never have the topic-view trap
+ *   2. senderIsBot        — only bot→bot triggers it
+ *   3. dc.isThread        — inbound was a thread reply (also inferred from
+ *                            root_id in topic groups when threadSession=true)
+ *
+ * Output: a routing object consumed by every outbound call site (main
+ * dispatcher + i18n command card + i18n command text fallback), so the
+ * three call sites never drift out of sync again.
+ */
+import type { MentionInfo } from '../types';
+import type { DispatchContext } from './dispatch-context';
+/** The peer a reply must explicitly @-mention so it actually reaches them. */
+export interface BotPeerTarget {
+    peerOpenId: string;
+    peerName: string;
+}
+/**
+ * Decide which peer (if any) an outbound reply must be guaranteed to
+ * @-mention, so the deterministic `ensureMention` backstop can wake them up.
+ *
+ * Deliberately INDEPENDENT of `suppressForBotPeer` (which only governs
+ * thread-vs-main routing): the addressee must be resolvable even on a
+ * human-orchestrated kickoff, where the triggering sender is a person but the
+ * conversation is meant to continue between bots.
+ *
+ *   1. Bot sender  → @ the sender back, continuing the exchange.
+ *   2. Otherwise (e.g. a human kicking off a bot debate) → if the inbound
+ *      message @-mentions exactly ONE party other than ourselves, treat that
+ *      party as the designated peer. Zero / multiple non-self mentions are
+ *      ambiguous, so we add no forced @ (avoids spamming unrelated members).
+ *
+ * Group-only: bot-at-bot @ delivery semantics don't apply to DMs.
+ */
+export declare function resolveBotPeerForMention(params: {
+    isGroup: boolean;
+    senderIsBot?: boolean;
+    senderId?: string;
+    senderName?: string;
+    mentions: MentionInfo[];
+    botOpenId?: string;
+}): BotPeerTarget | undefined;
+export interface FeishuReplyRouting {
+    /** Whether to send the reply as a thread-scoped message. */
+    replyInThread: boolean;
+    /** Effective thread_id when replying in-thread; undefined otherwise. */
+    threadId: string | undefined;
+    /** True when the peer is a bot in a group chat: suppress thread-mode reply
+     *  so the message lands in the main chat (avoiding the hidden topic view,
+     *  #32980). Consumers may also use this signal for additional bot-peer-
+     *  specific behavior (e.g. ensureMention in outbound-mention). */
+    suppressForBotPeer: boolean;
+}
+/**
+ * Resolve reply routing for the current dispatch, performing two tasks:
+ *
+ *  1. **Topic-group thread inference (may mutate `dc`).** In topic groups
+ *     (chat_mode=topic), reply events may carry `root_id` without
+ *     `thread_id`. When `threadSession` is enabled and the chat is
+ *     thread-capable, treat `root_id` as a synthetic `threadId` so replies
+ *     stay inside the topic instead of creating a new top-level message.
+ *     This step mutates `dc.isThread` and `dc.ctx.threadId` so subsequent
+ *     code (session-key resolution, sentinel scoping, history scoping)
+ *     observes the same routing decision.
+ *
+ *  2. **Reply routing decision (pure).** Computes `replyInThread` and
+ *     `suppressForBotPeer` from the post-inference state. In bot→bot group
+ *     chats `replyInThread` is forced to `false` regardless of the inbound
+ *     shape, preventing the topic-view trap.
+ */
+export declare function resolveFeishuReplyRouting(dc: DispatchContext, opts?: {
+    replyInThreadConfig?: boolean;
+}): Promise<FeishuReplyRouting>;

package/src/messaging/inbound/bot-content.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Reply-routing decisions for the Feishu dispatch path.
+ *
+ * In bot-to-bot group scenarios, Feishu will pull thread-style replies into
+ * a hidden "topic view" that group members cannot see (#32980). The peer bot
+ * keeps receiving messages but humans in the chat see nothing — a silent
+ * failure mode that turns bot↔bot chat into a black hole.
+ *
+ * This module centralizes the three signals that decide where a reply lands:
+ *   1. isGroup            — DMs never have the topic-view trap
+ *   2. senderIsBot        — only bot→bot triggers it
+ *   3. dc.isThread        — inbound was a thread reply (also inferred from
+ *                            root_id in topic groups when threadSession=true)
+ *
+ * Output: a routing object consumed by every outbound call site (main
+ * dispatcher + i18n command card + i18n command text fallback), so the
+ * three call sites never drift out of sync again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBotPeerForMention = resolveBotPeerForMention;
+exports.resolveFeishuReplyRouting = resolveFeishuReplyRouting;
+const chat_info_cache_1 = require("../../core/chat-info-cache.js");
+const lark_logger_1 = require("../../core/lark-logger.js");
+const log = (0, lark_logger_1.larkLogger)('inbound/bot-content');
+/**
+ * Decide which peer (if any) an outbound reply must be guaranteed to
+ * @-mention, so the deterministic `ensureMention` backstop can wake them up.
+ *
+ * Deliberately INDEPENDENT of `suppressForBotPeer` (which only governs
+ * thread-vs-main routing): the addressee must be resolvable even on a
+ * human-orchestrated kickoff, where the triggering sender is a person but the
+ * conversation is meant to continue between bots.
+ *
+ *   1. Bot sender  → @ the sender back, continuing the exchange.
+ *   2. Otherwise (e.g. a human kicking off a bot debate) → if the inbound
+ *      message @-mentions exactly ONE party other than ourselves, treat that
+ *      party as the designated peer. Zero / multiple non-self mentions are
+ *      ambiguous, so we add no forced @ (avoids spamming unrelated members).
+ *
+ * Group-only: bot-at-bot @ delivery semantics don't apply to DMs.
+ */
+function resolveBotPeerForMention(params) {
+    if (!params.isGroup)
+        return undefined;
+    // 1. Bot sender → keep the ping-pong going by @-ing them back.
+    if (params.senderIsBot && params.senderId) {
+        return { peerOpenId: params.senderId, peerName: params.senderName ?? params.senderId };
+    }
+    // 2. Human-orchestrated kickoff → the single non-self @-mentioned party.
+    const seen = new Set();
+    const others = [];
+    for (const m of params.mentions) {
+        if (!m.openId || m.isBot || m.openId === params.botOpenId)
+            continue;
+        if (seen.has(m.openId))
+            continue;
+        seen.add(m.openId);
+        others.push(m);
+    }
+    if (others.length === 1) {
+        return { peerOpenId: others[0].openId, peerName: others[0].name || others[0].openId };
+    }
+    return undefined;
+}
+/**
+ * Resolve reply routing for the current dispatch, performing two tasks:
+ *
+ *  1. **Topic-group thread inference (may mutate `dc`).** In topic groups
+ *     (chat_mode=topic), reply events may carry `root_id` without
+ *     `thread_id`. When `threadSession` is enabled and the chat is
+ *     thread-capable, treat `root_id` as a synthetic `threadId` so replies
+ *     stay inside the topic instead of creating a new top-level message.
+ *     This step mutates `dc.isThread` and `dc.ctx.threadId` so subsequent
+ *     code (session-key resolution, sentinel scoping, history scoping)
+ *     observes the same routing decision.
+ *
+ *  2. **Reply routing decision (pure).** Computes `replyInThread` and
+ *     `suppressForBotPeer` from the post-inference state. In bot→bot group
+ *     chats `replyInThread` is forced to `false` regardless of the inbound
+ *     shape, preventing the topic-view trap.
+ */
+async function resolveFeishuReplyRouting(dc, opts = {}) {
+    // Step 1: topic-group thread inference (async + side effects on dc)
+    if (!dc.isThread &&
+        dc.isGroup &&
+        dc.ctx.rootId &&
+        dc.account.config?.threadSession === true) {
+        const threadCapable = await (0, chat_info_cache_1.isThreadCapableGroup)({
+            cfg: dc.accountScopedCfg,
+            chatId: dc.ctx.chatId,
+            accountId: dc.account.accountId,
+        });
+        if (threadCapable) {
+            log.info(`inferred thread from root_id=${dc.ctx.rootId} in topic group ${dc.ctx.chatId}`);
+            dc.isThread = true;
+            dc.ctx = { ...dc.ctx, threadId: dc.ctx.rootId };
+        }
+    }
+    // Step 2: bot-peer suppression decision (pure read of dc state).
+    //
+    // We force a bot→bot reply out of the thread only when it would otherwise
+    // snowball an *auto-detected* threadReply into a hidden topic view (#32980).
+    // Two escape hatches keep parity with openclaw core (PR #89783):
+    //   - isTopicSession: a deliberate topic session (threadSession enabled +
+    //     inbound is in a thread) is human-visible by design — keep it threaded.
+    //   - replyInThread config: operators can opt in per-group/account.
+    const isTopicSession = dc.isThread && dc.account.config?.threadSession === true;
+    const configReplyInThread = opts.replyInThreadConfig === true;
+    const suppressForBotPeer = dc.isGroup && !!dc.ctx.senderIsBot && !isTopicSession && !configReplyInThread;
+    const replyInThread = !suppressForBotPeer && dc.isThread;
+    const threadId = replyInThread ? dc.ctx.threadId : undefined;
+    return { replyInThread, threadId, suppressForBotPeer };
+}

package/src/messaging/inbound/bot-loop-guard.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Cross-bot loop guard for bot-at-bot (ping-pong) conversations.
+ *
+ * Background: when two different bots @-mention each other in a group, each
+ * reply wakes the other, which replies again — an endless debate. The
+ * existing self-echo filter only drops a bot's *own* echo; it does nothing
+ * for A↔B loops. This module adds a deterministic hard brake: count the
+ * consecutive turns whose sender is a bot per (chat, thread), and stop
+ * auto-replying once the count exceeds a cap. Any human turn resets the
+ * counter, so a new human-driven exchange starts fresh.
+ *
+ * State is process-local and best-effort (each bot process keeps its own
+ * counter for the peer's messages it receives). Idle conversations decay so
+ * a long-quiet chat doesn't carry a stale count into a new exchange.
+ */
+/** Max consecutive bot-originated turns before auto-reply is suppressed. */
+export declare const MAX_CONSECUTIVE_BOT_TURNS = 10;
+/** Idle window after which a conversation's counter is considered stale. */
+export declare const BOT_LOOP_IDLE_RESET_MS: number;
+export interface BotTurnVerdict {
+    /** False once the consecutive bot-turn count exceeds the cap. */
+    allowed: boolean;
+    /** The current consecutive bot-turn count after this turn. */
+    count: number;
+    /** The configured cap, for logging. */
+    limit: number;
+}
+/**
+ * Record one bot-originated turn for the given conversation and decide
+ * whether the bot should still auto-reply.
+ *
+ * Increments the consecutive-bot-turn counter (resetting first if the
+ * conversation has been idle past the decay window), then returns
+ * `allowed: false` once the count exceeds {@link MAX_CONSECUTIVE_BOT_TURNS}.
+ */
+export declare function noteBotTurnAndCheck(chatId: string, threadId?: string, now?: number): BotTurnVerdict;
+/**
+ * Reset the consecutive bot-turn counter for a conversation. Called on every
+ * human turn so a human stepping in always re-arms the debate budget.
+ */
+export declare function resetBotLoop(chatId: string, threadId?: string): void;
+/** Clear all loop state. Intended for tests. */
+export declare function resetAllBotLoops(): void;
+/** Number of tracked conversations. Intended for tests. */
+export declare function botLoopStateSize(): number;

package/src/messaging/inbound/bot-loop-guard.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Cross-bot loop guard for bot-at-bot (ping-pong) conversations.
+ *
+ * Background: when two different bots @-mention each other in a group, each
+ * reply wakes the other, which replies again — an endless debate. The
+ * existing self-echo filter only drops a bot's *own* echo; it does nothing
+ * for A↔B loops. This module adds a deterministic hard brake: count the
+ * consecutive turns whose sender is a bot per (chat, thread), and stop
+ * auto-replying once the count exceeds a cap. Any human turn resets the
+ * counter, so a new human-driven exchange starts fresh.
+ *
+ * State is process-local and best-effort (each bot process keeps its own
+ * counter for the peer's messages it receives). Idle conversations decay so
+ * a long-quiet chat doesn't carry a stale count into a new exchange.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOT_LOOP_IDLE_RESET_MS = exports.MAX_CONSECUTIVE_BOT_TURNS = void 0;
+exports.noteBotTurnAndCheck = noteBotTurnAndCheck;
+exports.resetBotLoop = resetBotLoop;
+exports.resetAllBotLoops = resetAllBotLoops;
+exports.botLoopStateSize = botLoopStateSize;
+/** Max consecutive bot-originated turns before auto-reply is suppressed. */
+exports.MAX_CONSECUTIVE_BOT_TURNS = 10;
+/** Idle window after which a conversation's counter is considered stale. */
+exports.BOT_LOOP_IDLE_RESET_MS = 10 * 60 * 1000; // 10 min
+// `${chatId}:${threadId ?? ''}` -> consecutive bot-turn state
+const states = new Map();
+// Timestamp of the last stale-entry sweep, to bound sweep frequency.
+let lastSweepAt = 0;
+function loopKey(chatId, threadId) {
+    return `${chatId}:${threadId ?? ''}`;
+}
+/**
+ * Evict entries idle past the decay window. Called opportunistically from
+ * noteBotTurnAndCheck (at most once per idle window) so the Map can't grow
+ * unbounded for bot-only chats that never see a human turn to reset them.
+ * Dropping a stale entry is equivalent to leaving it: the next access would
+ * reset its count to 1 via the freshness check anyway.
+ */
+function sweepStale(now) {
+    if (now - lastSweepAt < exports.BOT_LOOP_IDLE_RESET_MS)
+        return;
+    lastSweepAt = now;
+    for (const [key, state] of states) {
+        if (now - state.updatedAt > exports.BOT_LOOP_IDLE_RESET_MS)
+            states.delete(key);
+    }
+}
+/**
+ * Record one bot-originated turn for the given conversation and decide
+ * whether the bot should still auto-reply.
+ *
+ * Increments the consecutive-bot-turn counter (resetting first if the
+ * conversation has been idle past the decay window), then returns
+ * `allowed: false` once the count exceeds {@link MAX_CONSECUTIVE_BOT_TURNS}.
+ */
+function noteBotTurnAndCheck(chatId, threadId, now = Date.now()) {
+    sweepStale(now);
+    const key = loopKey(chatId, threadId);
+    const prev = states.get(key);
+    const fresh = prev && now - prev.updatedAt <= exports.BOT_LOOP_IDLE_RESET_MS;
+    const count = (fresh ? prev.count : 0) + 1;
+    states.set(key, { count, updatedAt: now });
+    return {
+        allowed: count <= exports.MAX_CONSECUTIVE_BOT_TURNS,
+        count,
+        limit: exports.MAX_CONSECUTIVE_BOT_TURNS,
+    };
+}
+/**
+ * Reset the consecutive bot-turn counter for a conversation. Called on every
+ * human turn so a human stepping in always re-arms the debate budget.
+ */
+function resetBotLoop(chatId, threadId) {
+    states.delete(loopKey(chatId, threadId));
+}
+/** Clear all loop state. Intended for tests. */
+function resetAllBotLoops() {
+    states.clear();
+    lastSweepAt = 0;
+}
+/** Number of tracked conversations. Intended for tests. */
+function botLoopStateSize() {
+    return states.size;
+}

package/src/messaging/inbound/comment-context.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Drive comment event context resolution.
+ *
+ * Resolves the full context for a `drive.notice.comment_add_v1` event:
+ * document title, comment quoted text, and reply chain.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { FeishuDriveCommentEvent } from '../types';
+/** Resolved context for a Drive comment event. */
+export interface CommentEventTurn {
+    /** Document title (best-effort, may be undefined). */
+    docTitle?: string;
+    /** File type of the document. */
+    fileType: string;
+    /** File token of the document. */
+    fileToken: string;
+    /** Root comment ID. */
+    commentId: string;
+    /** Reply ID (if this event is a reply). */
+    replyId?: string;
+    /** Quoted text from the comment (the content being commented on). */
+    quotedText?: string;
+    /** The text of the triggering comment/reply. */
+    commentText?: string;
+    /** Reply chain context (previous replies in the thread). */
+    replyChainContext?: string;
+    /** Whether the bot was @-mentioned. */
+    isMentioned?: boolean;
+    /** Whether the source comment is a whole-document comment. */
+    isWholeComment?: boolean;
+    /** Surface prompt for the agent (context + instructions). */
+    prompt: string;
+    /** Short preview of the prompt. */
+    preview: string;
+}
+/**
+ * Infer whether a Drive comment thread is a whole-document comment.
+ *
+ * The explicit `is_whole` flag is authoritative when present. When the API
+ * omits it, the root comment's quoted anchor is the best fallback signal:
+ * whole-document comments have no quote, while anchored comments do.
+ *
+ * Note that this inference is about the root thread, so it must behave the
+ * same for both root-comment events and reply events.
+ */
+export declare function inferIsWholeComment(params: {
+    explicitIsWhole?: boolean;
+    quotedText?: string;
+}): boolean;
+/**
+ * Resolve the full context for a Drive comment event.
+ *
+ * Fetches document metadata, comment content, and reply chain.
+ */
+export declare function resolveDriveCommentEventTurn(params: {
+    cfg: ClawdbotConfig;
+    event: FeishuDriveCommentEvent;
+    accountId?: string;
+}): Promise<CommentEventTurn | null>;
+/**
+ * Parse the raw webhook payload for a `drive.notice.comment_add_v1` event.
+ *
+ * The SDK flattens the v2 envelope, so the event data may be at the
+ * top level or nested under `event`. User info and timestamp live inside
+ * `notice_meta` in the real event structure, with fallback to top-level
+ * fields for compatibility with different SDK flattening styles.
+ */
+/**
+ * Normalize a Drive comment event into a canonical shape.
+ *
+ * Real event structures vary:
+ *   - **notice_meta style**: file_token, file_type, from_user_id, timestamp
+ *     all live inside `notice_meta`; top-level only has comment_id/reply_id.
+ *   - **SDK-flattened style**: fields may be hoisted to top level.
+ *
+ * This parser checks `notice_meta.*` first, then falls back to top-level
+ * fields, so the handler can consume a single canonical shape.
+ */
+export declare function parseFeishuDriveCommentNoticeEventPayload(data: unknown): FeishuDriveCommentEvent | null;