@larksuite/openclaw-lark 2026.5.20 → 2026.6.10-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/openclaw-lark",
-  "version": "2026.5.20",
+  "version": "2026.6.10-beta.1",
   "description": "OpenClaw Lark/Feishu channel plugin",
   "exports": {
     ".": {

package/src/card/reply-mode.js

@@ -59,7 +59,14 @@ function expandAutoMode(params) {
  * markdown tables).
  */
 function shouldUseCard(text) {
-    // Table limit takes priority -- even with code blocks, too many tables will fail
+    // Markdown tables NO LONGER force a card. Feishu messages render markdown
+    // tables natively, and wrapping a reply in a card breaks bot-at-bot @
+    // delivery (cards have limited @ support). Only fenced code blocks still
+    // benefit from card rendering.
+    //
+    // The table-count guard is kept as a safety valve: when a reply also
+    // contains an excessive number of markdown tables, skip the card entirely
+    // rather than risk a card-render failure.
     const tableMatches = (0, card_error_1.findMarkdownTablesOutsideCodeBlocks)(text);
     if (tableMatches.length > card_error_1.FEISHU_CARD_TABLE_LIMIT) {
         return false;
@@ -68,9 +75,5 @@ function shouldUseCard(text) {
     if (/```[\s\S]*?```/.test(text)) {
         return true;
     }
-    // Markdown tables (header + separator rows separated by pipes)
-    if (tableMatches.length > 0) {
-        return true;
-    }
     return false;
 }

package/src/channel/abort-detect.d.ts

@@ -21,6 +21,19 @@ export declare function isAbortTrigger(text: string): boolean;
  * `/stop` command form.  Used by the monitor fast-path.
  */
 export declare function isLikelyAbortText(text: string): boolean;
+/**
+ * Whether an inbound message expresses intent to stop / interrupt the ongoing
+ * (bot-to-bot) exchange. Superset of {@link isLikelyAbortText} plus the
+ * conversational phrases above.
+ *
+ * Two consumers: (1) suppress the deterministic peer-@ backstop so a stop
+ * acknowledgement doesn't re-wake the peer bot; (2) mute an active bot loop so
+ * the in-flight ping-pong drains instead of being re-armed. Substring match —
+ * keep the list distinctive (no bare "停"/"stop") to limit false positives;
+ * the worst case is a missed forced-@ or a self-healing mute (any normal
+ * message lifts it).
+ */
+export declare function isConversationStopIntent(text: string): boolean;
 /**
  * Extract the raw text payload from a Feishu message event.
  *

package/src/channel/abort-detect.js

@@ -17,6 +17,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAbortTrigger = isAbortTrigger;
 exports.isLikelyAbortText = isLikelyAbortText;
+exports.isConversationStopIntent = isConversationStopIntent;
 exports.extractRawTextFromEvent = extractRawTextFromEvent;
 // ---------------------------------------------------------------------------
 // Trigger word list (synced with OpenClaw core abort.ts)
@@ -100,6 +101,92 @@ function isLikelyAbortText(text) {
         return true;
     return isAbortTrigger(trimmed);
 }
+// ---------------------------------------------------------------------------
+// Conversation stop-intent (broader than the exact abort triggers)
+// ---------------------------------------------------------------------------
+/**
+ * Conversational "please stop / interrupt this exchange" phrases.
+ *
+ * Deliberately SEPARATE from {@link ABORT_TRIGGERS} (which is synced word-for-
+ * word with OpenClaw core and matched by exact equality, e.g. `/stop`). These
+ * are matched by substring so natural phrasings like "中断对话" or "stop
+ * talking" are caught. The list is intentionally distinctive to avoid false
+ * positives — a false positive only means we skip the deterministic peer-@
+ * backstop for that turn (the model can still @ on its own), which is mild.
+ */
+const STOP_INTENT_PHRASES = [
+    // zh — stop / terminate / pause
+    '中断',
+    '中止',
+    '终止',
+    '停止',
+    '停下',
+    '停一下',
+    '暂停',
+    '打住',
+    '停手',
+    '收手',
+    // zh — "don't keep going / replying"
+    '别聊',
+    '别说了',
+    '别回复',
+    '别继续',
+    '别再聊',
+    '别再说',
+    '别吵',
+    '别争',
+    '不要回复',
+    '不要继续',
+    '不用回复',
+    '不用继续',
+    // zh — "wrap up / be quiet"
+    '结束对话',
+    '结束讨论',
+    '结束辩论',
+    '到此为止',
+    '闭嘴',
+    // en
+    'stop talking',
+    'stop chatting',
+    'stop debating',
+    'stop the debate',
+    'stop the conversation',
+    'stop this conversation',
+    'stop responding',
+    'stop replying',
+    'end the conversation',
+    'end conversation',
+    'end the debate',
+    'shut up',
+    'be quiet',
+    'cut it out',
+    'knock it off',
+    'wrap it up',
+    'stand down',
+];
+/**
+ * Whether an inbound message expresses intent to stop / interrupt the ongoing
+ * (bot-to-bot) exchange. Superset of {@link isLikelyAbortText} plus the
+ * conversational phrases above.
+ *
+ * Two consumers: (1) suppress the deterministic peer-@ backstop so a stop
+ * acknowledgement doesn't re-wake the peer bot; (2) mute an active bot loop so
+ * the in-flight ping-pong drains instead of being re-armed. Substring match —
+ * keep the list distinctive (no bare "停"/"stop") to limit false positives;
+ * the worst case is a missed forced-@ or a self-healing mute (any normal
+ * message lifts it).
+ */
+function isConversationStopIntent(text) {
+    if (!text)
+        return false;
+    // Drop bot mention placeholders so "@Bot 中断对话" → "中断对话".
+    const normalized = text.replace(/@_user_\d+/g, '').trim().toLowerCase();
+    if (!normalized)
+        return false;
+    if (isLikelyAbortText(normalized))
+        return true;
+    return STOP_INTENT_PHRASES.some((p) => normalized.includes(p));
+}
 /**
  * Extract the raw text payload from a Feishu message event.
  *

package/src/core/config-schema.d.ts

@@ -31,6 +31,7 @@ export declare const FeishuGroupSchema: z.ZodObject<{
     allowFrom: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>, z.ZodTransform<string[] | undefined, string | string[] | undefined>>;
     systemPrompt: z.ZodOptional<z.ZodString>;
     allowBots: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"mentions">]>>;
+    replyInThread: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const FeishuAccountConfigSchema: z.ZodObject<{
     appId: z.ZodOptional<z.ZodString>;
@@ -78,6 +79,7 @@ export declare const FeishuAccountConfigSchema: z.ZodObject<{
         allowFrom: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>, z.ZodTransform<string[] | undefined, string | string[] | undefined>>;
         systemPrompt: z.ZodOptional<z.ZodString>;
         allowBots: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"mentions">]>>;
+        replyInThread: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
     historyLimit: z.ZodOptional<z.ZodNumber>;
     dmHistoryLimit: z.ZodOptional<z.ZodNumber>;
@@ -173,6 +175,7 @@ export declare const FeishuAccountConfigSchema: z.ZodObject<{
     }>>;
     threadSession: z.ZodOptional<z.ZodBoolean>;
     allowBots: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"mentions">]>>;
+    replyInThread: z.ZodOptional<z.ZodBoolean>;
     uat: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         allowedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -225,6 +228,7 @@ export declare const FeishuConfigSchema: z.ZodObject<{
         allowFrom: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>, z.ZodTransform<string[] | undefined, string | string[] | undefined>>;
         systemPrompt: z.ZodOptional<z.ZodString>;
         allowBots: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"mentions">]>>;
+        replyInThread: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
     historyLimit: z.ZodOptional<z.ZodNumber>;
     dmHistoryLimit: z.ZodOptional<z.ZodNumber>;
@@ -320,6 +324,7 @@ export declare const FeishuConfigSchema: z.ZodObject<{
     }>>;
     threadSession: z.ZodOptional<z.ZodBoolean>;
     allowBots: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"mentions">]>>;
+    replyInThread: z.ZodOptional<z.ZodBoolean>;
     uat: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         allowedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -371,6 +376,7 @@ export declare const FeishuConfigSchema: z.ZodObject<{
             allowFrom: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>, z.ZodTransform<string[] | undefined, string | string[] | undefined>>;
             systemPrompt: z.ZodOptional<z.ZodString>;
             allowBots: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"mentions">]>>;
+            replyInThread: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>;
         historyLimit: z.ZodOptional<z.ZodNumber>;
         dmHistoryLimit: z.ZodOptional<z.ZodNumber>;
@@ -466,6 +472,7 @@ export declare const FeishuConfigSchema: z.ZodObject<{
         }>>;
         threadSession: z.ZodOptional<z.ZodBoolean>;
         allowBots: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"mentions">]>>;
+        replyInThread: z.ZodOptional<z.ZodBoolean>;
         uat: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
             allowedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/src/core/config-schema.js

@@ -132,6 +132,9 @@ exports.FeishuGroupSchema = zod_1.z.object({
     allowFrom: AllowFromSchema,
     systemPrompt: zod_1.z.string().optional(),
     allowBots: AllowBotsSchema,
+    // When true, bot-to-bot replies are allowed to stay inside a thread/topic
+    // instead of being forced to the main chat (relaxes the #32980 guard).
+    replyInThread: zod_1.z.boolean().optional(),
 });
 // ---------------------------------------------------------------------------
 // Account config schema (same shape as top-level minus `accounts`)
@@ -179,6 +182,9 @@ exports.FeishuAccountConfigSchema = zod_1.z.object({
     reactionNotifications: ReactionNotificationModeSchema,
     threadSession: zod_1.z.boolean().optional(),
     allowBots: AllowBotsSchema,
+    // Account-level default for letting bot-to-bot replies stay in a thread
+    // (per-group `replyInThread` overrides this).
+    replyInThread: zod_1.z.boolean().optional(),
     uat: exports.UATConfigSchema,
 });
 // ---------------------------------------------------------------------------

package/src/messaging/converters/content-converter-helpers.d.ts

@@ -18,8 +18,13 @@ export declare function buildConvertContextFromItem(item: ApiMessageItem, fallba
 /**
  * Resolve mention placeholders in text.
  *
- * - Bot mentions: remove the placeholder key and any preceding `@botName`
- *   entirely (with trailing whitespace).
+ * - Bot self-mention + stripBotMentions: leading-only strip. When the
+ *   self-mention sits at the very start of the message, drop it (the
+ *   `WasMentioned` envelope field already tells the agent "this message
+ *   was addressed to you", so the anchor is redundant). When it appears
+ *   mid-text, render it as plain `@Name` so the surrounding context still
+ *   reads naturally without leaving an inline anchor the LLM might echo
+ *   back into its reply.
  * - Non-bot mentions: replace the placeholder key with readable `@name`.
  */
 export declare function resolveMentions(text: string, ctx: ConvertContext): string;

package/src/messaging/converters/content-converter-helpers.js

@@ -55,8 +55,13 @@ function buildConvertContextFromItem(item, fallbackMessageId, accountId) {
 /**
  * Resolve mention placeholders in text.
  *
- * - Bot mentions: remove the placeholder key and any preceding `@botName`
- *   entirely (with trailing whitespace).
+ * - Bot self-mention + stripBotMentions: leading-only strip. When the
+ *   self-mention sits at the very start of the message, drop it (the
+ *   `WasMentioned` envelope field already tells the agent "this message
+ *   was addressed to you", so the anchor is redundant). When it appears
+ *   mid-text, render it as plain `@Name` so the surrounding context still
+ *   reads naturally without leaving an inline anchor the LLM might echo
+ *   back into its reply.
  * - Non-bot mentions: replace the placeholder key with readable `@name`.
  */
 function resolveMentions(text, ctx) {
@@ -65,8 +70,9 @@ function resolveMentions(text, ctx) {
     let result = text;
     for (const [key, info] of ctx.mentions) {
         if (info.isBot && ctx.stripBotMentions) {
-            result = result.replace(new RegExp(`@${(0, utils_1.escapeRegExp)(info.name)}\\s*`, 'g'), '').trim();
-            result = result.replace(new RegExp((0, utils_1.escapeRegExp)(key) + '\\s*', 'g'), '').trim();
+            result = result.replace(new RegExp((0, utils_1.escapeRegExp)(key), 'g'), `@${info.name}`);
+            const leadingPattern = new RegExp(`^\\s*@${(0, utils_1.escapeRegExp)(info.name)}[\\s,，:：]*`);
+            result = result.replace(leadingPattern, '').trimStart();
         }
         else {
             result = result.replace(new RegExp((0, utils_1.escapeRegExp)(key), 'g'), `@${info.name}`);

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/dispatch-builders.d.ts

@@ -76,6 +76,24 @@ export declare function buildInboundPayload(dc: DispatchContext, opts: {
     }[];
     extraFields?: Record<string, unknown>;
 }): ReturnType<typeof LarkClient.runtime.channel.reply.finalizeInboundContext>;
+/**
+ * Structured identity signals injected into the agent envelope so the LLM
+ * can tell "who is talking to me" apart — in particular whether the sender
+ * is a bot, and what the bot's own open_id is.
+ *
+ * BotOpenId is omitted when unknown (e.g. startup race before the bot info
+ * probe completes) to avoid surfacing an empty identity to the agent.
+ */
+export declare function buildFeishuIdentityFields(ctx: MessageContext, botOpenId?: string): Record<string, unknown>;
+/**
+ * Build the effective group system prompt for a Feishu group chat.
+ *
+ * Always prepends bot-at-bot guidance (self-identity + @ semantics + loop
+ * hygiene) so the agent knows which open_id is itself, how Feishu @-delivery
+ * works, and when to stop; then appends any operator-configured group
+ * systemPrompt. Returns `undefined` only when there is nothing to inject.
+ */
+export declare function buildFeishuGroupSystemPrompt(configured: string | undefined, botOpenId?: string): string | undefined;
 /**
  * Format the agent envelope and prepend group chat history if applicable.
  * Returns the combined body and the history key (undefined for DMs).