@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/inbound/policy.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Access control policies for the Lark/Feishu channel plugin.
+ *
+ * Provides allowlist matching, group configuration lookup, tool policy
+ * extraction, and group access checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFeishuAllowlistMatch = resolveFeishuAllowlistMatch;
+exports.resolveFeishuGroupConfig = resolveFeishuGroupConfig;
+exports.resolveFeishuGroupToolPolicy = resolveFeishuGroupToolPolicy;
+exports.isFeishuGroupAllowed = isFeishuGroupAllowed;
+exports.splitLegacyGroupAllowFrom = splitLegacyGroupAllowFrom;
+exports.resolveGroupSenderPolicyContext = resolveGroupSenderPolicyContext;
+const accounts_1 = require("../../core/accounts.js");
+/**
+ * Check whether a sender is permitted by a given allowlist.
+ *
+ * Entries are normalised to lowercase strings before comparison.
+ * A single "*" entry acts as a wildcard that matches everyone.
+ * When the allowlist is empty the result is `{ allowed: false }`.
+ */
+function resolveFeishuAllowlistMatch(params) {
+    const allowFrom = params.allowFrom.map((entry) => String(entry).trim().toLowerCase()).filter(Boolean);
+    if (allowFrom.length === 0) {
+        return { allowed: false };
+    }
+    // Wildcard: allow everyone
+    if (allowFrom.includes('*')) {
+        return { allowed: true, matchKey: '*', matchSource: 'wildcard' };
+    }
+    // Match by sender ID
+    const senderId = params.senderId.toLowerCase();
+    if (allowFrom.includes(senderId)) {
+        return { allowed: true, matchKey: senderId, matchSource: 'id' };
+    }
+    /*  // Match by sender display name
+      const senderName = params.senderName?.toLowerCase();
+      if (senderName && allowFrom.includes(senderName)) {
+        return { allowed: true, matchKey: senderName, matchSource: 'name' };
+      }*/
+    return { allowed: false };
+}
+// ---------------------------------------------------------------------------
+// Group configuration lookup
+// ---------------------------------------------------------------------------
+/**
+ * Look up the per-group configuration by group ID.
+ *
+ * Performs a case-insensitive lookup against the keys in `cfg.groups`.
+ * Returns `undefined` when no matching group entry is found.
+ */
+function resolveFeishuGroupConfig(params) {
+    const groups = params.cfg?.groups ?? {};
+    const groupId = params.groupId?.trim();
+    if (!groupId) {
+        return undefined;
+    }
+    // Direct (exact-key) lookup first
+    const direct = groups[groupId];
+    if (direct) {
+        return direct;
+    }
+    // Case-insensitive fallback
+    const lowered = groupId.toLowerCase();
+    const matchKey = Object.keys(groups).find((key) => key.toLowerCase() === lowered);
+    return matchKey ? groups[matchKey] : undefined;
+}
+// ---------------------------------------------------------------------------
+// Group tool policy
+// ---------------------------------------------------------------------------
+/**
+ * Extract the tool policy configuration from the group config that
+ * corresponds to the given group context.
+ *
+ * ★ 多账号配置隔离：SDK 回调传入的 params.cfg 是顶层全局配置，
+ *   cfg.channels.feishu 不包含 per-account 的覆盖值。
+ *   这里通过 getLarkAccount() 获取当前 account 合并后的配置，
+ *   确保每个账号的 groups / tool policy 配置独立生效。
+ */
+function resolveFeishuGroupToolPolicy(params) {
+    // 使用 getLarkAccount 获取 per-account 合并后的飞书渠道配置，
+    // 而非直接读取 cfg.channels.feishu（顶层全局配置）。
+    const account = (0, accounts_1.getLarkAccount)(params.cfg, params.accountId ?? undefined);
+    const accountFeishuCfg = account.config;
+    if (!accountFeishuCfg) {
+        return undefined;
+    }
+    const groupConfig = resolveFeishuGroupConfig({
+        cfg: accountFeishuCfg,
+        groupId: params.groupId,
+    });
+    return groupConfig?.tools;
+}
+// ---------------------------------------------------------------------------
+// Group access gate
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether an inbound group message should be processed.
+ *
+ * - `disabled` --> always rejected
+ * - `open`     --> always allowed
+ * - `allowlist` --> allowed only when the sender matches the allowlist
+ */
+function isFeishuGroupAllowed(params) {
+    const { groupPolicy } = params;
+    if (groupPolicy === 'disabled') {
+        return false;
+    }
+    if (groupPolicy === 'open') {
+        return true;
+    }
+    // allowlist
+    return resolveFeishuAllowlistMatch(params).allowed;
+}
+// ---------------------------------------------------------------------------
+// Legacy compat: groupAllowFrom splitting
+// ---------------------------------------------------------------------------
+/**
+ * Split a raw `groupAllowFrom` array into legacy chat-ID entries
+ * (`oc_xxx`) and sender-level entries.
+ *
+ * Older Feishu configs used `groupAllowFrom` with `oc_xxx` chat IDs to
+ * control which groups are allowed.  The correct semantic (aligned with
+ * Telegram) is sender IDs.  This function separates the two concerns so
+ * both layers can work independently.
+ */
+function splitLegacyGroupAllowFrom(rawGroupAllowFrom) {
+    const legacyChatIds = [];
+    const senderAllowFrom = [];
+    for (const entry of rawGroupAllowFrom) {
+        const str = String(entry);
+        if (str.startsWith('oc_')) {
+            legacyChatIds.push(str);
+        }
+        else {
+            senderAllowFrom.push(str);
+        }
+    }
+    return { legacyChatIds, senderAllowFrom };
+}
+// ---------------------------------------------------------------------------
+// Sender policy context resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the effective sender-level group policy and the merged
+ * `allowFrom` list for sender filtering within a group.
+ *
+ * The precedence chain for `senderPolicy` is:
+ *   per-group `groupPolicy` > default ("*") group `groupPolicy` >
+ *   global `groupPolicy` > "open" (default).
+ *
+ * The `senderAllowFrom` is the union of global (non-oc_) entries,
+ * per-group entries, and default ("*") entries (when no per-group config).
+ */
+function resolveGroupSenderPolicyContext(params) {
+    const { groupConfig, defaultConfig, accountFeishuCfg, senderGroupAllowFrom } = params;
+    const senderPolicy = groupConfig?.groupPolicy ?? defaultConfig?.groupPolicy ?? accountFeishuCfg?.groupPolicy ?? 'open';
+    const senderAllowFrom = [
+        ...senderGroupAllowFrom,
+        ...(groupConfig?.allowFrom ?? []),
+        ...(!groupConfig && defaultConfig?.allowFrom ? defaultConfig.allowFrom : []),
+    ];
+    return { senderPolicy, senderAllowFrom };
+}

package/src/messaging/inbound/reaction-handler.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Reaction event handler for the Lark/Feishu channel plugin.
+ *
+ * Handles `im.message.reaction.created_v1` events by building a
+ * {@link MessageContext} directly and dispatching to the agent via
+ * {@link dispatchToAgent}, bypassing the full 7-stage message pipeline.
+ *
+ * Controlled by `reactionNotifications` (default: "own"):
+ *   - `"off"`  — reaction events are silently ignored.
+ *   - `"own"`  — only reactions on the bot's own messages are dispatched.
+ *   - `"all"`  — reactions on any message in the chat are dispatched.
+ */
+import type { ClawdbotConfig, RuntimeEnv } from 'openclaw/plugin-sdk';
+import type { HistoryEntry } from 'openclaw/plugin-sdk/reply-history';
+import type { FeishuReactionCreatedEvent } from '../types';
+import { type FeishuMessageInfo } from '../shared/message-lookup';
+export interface ReactionContext {
+    /** Real chatId (from message API, or `p2p:${operatorOpenId}` fallback). */
+    chatId: string;
+    /** Resolved chat type. */
+    chatType: 'p2p' | 'group';
+    /** Thread ID from the fetched message, if any. */
+    threadId?: string;
+    /** Whether the chat is thread-capable (topic or thread-mode group). */
+    threadCapable?: boolean;
+    /** Fetched message info used to build the synthetic event. */
+    msg: FeishuMessageInfo;
+}
+/**
+ * Pre-resolve reaction context before enqueuing.
+ *
+ * Performs account config checks, safety filters, API fetch of the
+ * original message, ownership verification, chat type resolution, and
+ * thread-capable detection.  Returns `null` when the reaction should
+ * be skipped (mode off, safety filter, timeout, ownership mismatch,
+ * thread-capable group with threadSession enabled).
+ *
+ * This function is intentionally separated so that the caller
+ * (event-handlers.ts) can resolve the real chatId *before* enqueuing,
+ * ensuring the reaction shares the same queue key as normal messages
+ * for the same chat.
+ */
+export declare function resolveReactionContext(params: {
+    cfg: ClawdbotConfig;
+    event: FeishuReactionCreatedEvent;
+    botOpenId?: string;
+    runtime?: RuntimeEnv;
+    accountId?: string;
+}): Promise<ReactionContext | null>;
+export declare function handleFeishuReaction(params: {
+    cfg: ClawdbotConfig;
+    event: FeishuReactionCreatedEvent;
+    botOpenId?: string;
+    runtime?: RuntimeEnv;
+    chatHistories?: Map<string, HistoryEntry[]>;
+    accountId?: string;
+    /** Pre-resolved context from resolveReactionContext(). */
+    preResolved: ReactionContext;
+}): Promise<void>;

package/src/messaging/inbound/reaction-handler.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Reaction event handler for the Lark/Feishu channel plugin.
+ *
+ * Handles `im.message.reaction.created_v1` events by building a
+ * {@link MessageContext} directly and dispatching to the agent via
+ * {@link dispatchToAgent}, bypassing the full 7-stage message pipeline.
+ *
+ * Controlled by `reactionNotifications` (default: "own"):
+ *   - `"off"`  — reaction events are silently ignored.
+ *   - `"own"`  — only reactions on the bot's own messages are dispatched.
+ *   - `"all"`  — reactions on any message in the chat are dispatched.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveReactionContext = resolveReactionContext;
+exports.handleFeishuReaction = handleFeishuReaction;
+const crypto = __importStar(require("node:crypto"));
+const reply_history_1 = require("openclaw/plugin-sdk/reply-history");
+const accounts_1 = require("../../core/accounts.js");
+const message_lookup_1 = require("../shared/message-lookup.js");
+const chat_info_cache_1 = require("../../core/chat-info-cache.js");
+const lark_logger_1 = require("../../core/lark-logger.js");
+const user_name_cache_1 = require("./user-name-cache.js");
+const dispatch_1 = require("./dispatch.js");
+const policy_1 = require("./policy.js");
+const logger = (0, lark_logger_1.larkLogger)('inbound/reaction-handler');
+const REACTION_VERIFY_TIMEOUT_MS = 3_000;
+/**
+ * Pre-resolve reaction context before enqueuing.
+ *
+ * Performs account config checks, safety filters, API fetch of the
+ * original message, ownership verification, chat type resolution, and
+ * thread-capable detection.  Returns `null` when the reaction should
+ * be skipped (mode off, safety filter, timeout, ownership mismatch,
+ * thread-capable group with threadSession enabled).
+ *
+ * This function is intentionally separated so that the caller
+ * (event-handlers.ts) can resolve the real chatId *before* enqueuing,
+ * ensuring the reaction shares the same queue key as normal messages
+ * for the same chat.
+ */
+async function resolveReactionContext(params) {
+    const { cfg, event, botOpenId, runtime, accountId } = params;
+    const log = runtime?.log ?? ((...args) => logger.info(args.map(String).join(' ')));
+    const account = (0, accounts_1.getLarkAccount)(cfg, accountId);
+    const reactionMode = account.config?.reactionNotifications ?? 'own';
+    if (reactionMode === 'off') {
+        return null;
+    }
+    const emojiType = event.reaction_type?.emoji_type;
+    const messageId = event.message_id;
+    const operatorOpenId = event.user_id?.open_id ?? '';
+    if (!emojiType || !messageId || !operatorOpenId) {
+        return null;
+    }
+    // ---- Safety filters (aligned with official) ----
+    if (event.operator_type === 'app' || operatorOpenId === botOpenId) {
+        log(`feishu[${accountId}]: ignoring app/self reaction on ${messageId}`);
+        return null;
+    }
+    if (emojiType === 'Typing') {
+        return null;
+    }
+    // "own" mode requires botOpenId to verify message ownership
+    if (reactionMode === 'own' && !botOpenId) {
+        log(`feishu[${accountId}]: bot open_id unavailable, skipping reaction on ${messageId}`);
+        return null;
+    }
+    // ---- Fetch original message with timeout (fail-closed) ----
+    const msg = await Promise.race([
+        (0, message_lookup_1.getMessageFeishu)({ cfg, messageId, accountId }),
+        new Promise((resolve) => setTimeout(() => resolve(null), REACTION_VERIFY_TIMEOUT_MS)),
+    ]).catch(() => null);
+    if (!msg) {
+        log(`feishu[${accountId}]: reacted message ${messageId} not found or timed out, skipping`);
+        return null;
+    }
+    // mget API returns app_id (cli_xxx) as sender.id for bot messages.
+    const isBotMessage = msg.senderType === 'app' && msg.senderId === account.appId;
+    const isOtherBotMessage = msg.senderType === 'app' && account.appId && msg.senderId !== account.appId;
+    // 'own': only react to this bot's messages; 'all': also skip other bots' messages.
+    if ((reactionMode === 'own' && !isBotMessage) || (reactionMode === 'all' && isOtherBotMessage)) {
+        log(`feishu[${accountId}]: reaction on ${isOtherBotMessage ? 'other bot' : 'non-bot'} message ${messageId}, skipping`);
+        return null;
+    }
+    // ---- Resolve effective chatId ----
+    const rawChatId = event.chat_id?.trim() || msg.chatId?.trim() || '';
+    const effectiveChatId = rawChatId || `p2p:${operatorOpenId}`;
+    // ---- Resolve chat type ----
+    // im.message.reaction.created_v1 does NOT include chat_id or chat_type
+    // (confirmed from Feishu docs). The message GET API returns chat_id but
+    // NOT chat_type. So we must determine chat_type via im.chat.get.
+    //
+    // Determine chat type: event payload → fetched message → im.chat.get API.
+    // The first two sources are almost always empty for reaction events, so
+    // getChatTypeFeishu is the primary path.
+    let chatType = event.chat_type === 'group'
+        ? 'group'
+        : event.chat_type === 'p2p' || event.chat_type === 'private'
+            ? 'p2p'
+            : msg.chatType === 'group' || msg.chatType === 'p2p'
+                ? msg.chatType
+                : 'p2p'; // tentative default, overridden below when chatId is available
+    // When we have a real chat_id (from event or message API), query the
+    // authoritative chat type via im.chat.get. This is the only reliable
+    // source for reaction events.
+    if (rawChatId && chatType === 'p2p' && !event.chat_type && !msg.chatType) {
+        try {
+            chatType = await (0, chat_info_cache_1.getChatTypeFeishu)({ cfg, chatId: rawChatId, accountId });
+        }
+        catch {
+            // getChatTypeFeishu already logs errors and defaults to "p2p"
+        }
+    }
+    // ---- Thread session: skip for thread-capable groups ----
+    // The mget API does not return thread_id, so we cannot route the
+    // synthetic event to the correct thread session. Skip reaction handling
+    // only for thread-capable groups (topic / thread-mode); p2p and regular
+    // groups are unaffected since they have no threads.
+    let threadCapable = false;
+    const threadSessionEnabled = account.config?.threadSession === true;
+    if (rawChatId && chatType === 'group') {
+        threadCapable = await (0, chat_info_cache_1.isThreadCapableGroup)({ cfg, chatId: rawChatId, accountId });
+        if (threadSessionEnabled && threadCapable) {
+            log(`feishu[${accountId}]: reaction on thread-capable group ${rawChatId}, skipping (threadSession enabled)`);
+            return null;
+        }
+    }
+    return {
+        chatId: effectiveChatId,
+        chatType,
+        threadId: msg.threadId,
+        threadCapable,
+        msg,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+async function handleFeishuReaction(params) {
+    const { cfg, event, runtime, chatHistories, accountId, preResolved } = params;
+    const log = runtime?.log ?? ((...args) => logger.info(args.map(String).join(' ')));
+    const error = runtime?.error ?? ((...args) => logger.error(args.map(String).join(' ')));
+    const emojiType = event.reaction_type?.emoji_type ?? '';
+    const messageId = event.message_id;
+    const operatorOpenId = event.user_id?.open_id ?? '';
+    // ---- Step A: Account resolution + accountScopedCfg ----
+    const account = (0, accounts_1.getLarkAccount)(cfg, accountId);
+    const accountFeishuCfg = account.config;
+    const accountScopedCfg = {
+        ...cfg,
+        channels: { ...cfg.channels, feishu: accountFeishuCfg },
+    };
+    // ---- Step B: Build MessageContext directly ----
+    const excerpt = preResolved.msg.content.length > 200 ? `${preResolved.msg.content.slice(0, 200)}…` : preResolved.msg.content;
+    const syntheticText = excerpt
+        ? `[reacted with ${emojiType} to message ${messageId}: "${excerpt}"]`
+        : `[reacted with ${emojiType} to message ${messageId}]`;
+    const syntheticMessageId = `${messageId}:reaction:${emojiType}:${crypto.randomUUID()}`;
+    let ctx = {
+        chatId: preResolved.chatId,
+        messageId: syntheticMessageId,
+        senderId: operatorOpenId,
+        chatType: preResolved.chatType,
+        content: syntheticText,
+        contentType: 'text',
+        resources: [],
+        mentions: [],
+        mentionAll: false,
+        threadId: preResolved.threadId,
+        rawMessage: {
+            message_id: syntheticMessageId,
+            chat_id: preResolved.chatId,
+            chat_type: preResolved.chatType,
+            message_type: 'text',
+            content: JSON.stringify({ text: syntheticText }),
+            create_time: event.action_time ?? String(Date.now()),
+            thread_id: preResolved.threadId,
+        },
+        rawSender: {
+            sender_id: {
+                open_id: operatorOpenId,
+                user_id: event.user_id?.user_id,
+                union_id: event.user_id?.union_id,
+            },
+            sender_type: 'user',
+        },
+    };
+    // ---- Step C: Sender name resolution ----
+    const senderResult = await (0, user_name_cache_1.resolveUserName)({ account, openId: operatorOpenId, log });
+    if (senderResult.name) {
+        ctx = { ...ctx, senderName: senderResult.name };
+    }
+    log(`feishu[${accountId}]: reaction "${emojiType}" by ${operatorOpenId} on ${messageId} (chatId=${preResolved.chatId}, chatType=${preResolved.chatType}${preResolved.threadId ? `, thread=${preResolved.threadId}` : ''}), dispatching to AI`);
+    logger.info(`reaction "${emojiType}" by ${operatorOpenId} on ${messageId} (chatType=${preResolved.chatType})`);
+    // ---- Step D: Group config resolution ----
+    const isGroup = ctx.chatType === 'group';
+    const groupConfig = isGroup ? (0, policy_1.resolveFeishuGroupConfig)({ cfg: accountFeishuCfg, groupId: ctx.chatId }) : undefined;
+    const defaultGroupConfig = isGroup ? accountFeishuCfg?.groups?.['*'] : undefined;
+    const historyLimit = Math.max(0, accountFeishuCfg?.historyLimit ?? accountScopedCfg.messages?.groupChat?.historyLimit ?? reply_history_1.DEFAULT_GROUP_HISTORY_LIMIT);
+    // ---- Step E: Dispatch directly to agent ----
+    try {
+        await (0, dispatch_1.dispatchToAgent)({
+            ctx,
+            permissionError: undefined,
+            mediaPayload: {},
+            quotedContent: undefined,
+            account,
+            accountScopedCfg,
+            runtime,
+            chatHistories,
+            historyLimit,
+            replyToMessageId: messageId,
+            commandAuthorized: false,
+            groupConfig,
+            defaultGroupConfig,
+            skipTyping: true,
+        });
+    }
+    catch (err) {
+        error(`feishu[${accountId}]: error dispatching reaction event: ${String(err)}`);
+    }
+}

package/src/messaging/inbound/sentinel-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Per-thread store for unresolved mention feedback. The outbound
+ * normalizer records a SentinelEntry whenever an `@Name` cannot be
+ * resolved; the next inbound message on the same thread consumes
+ * (take and delete) the entries, which buildMentionAnnotation surfaces
+ * as a system note so the next reply can disambiguate.
+ *
+ * Kept separate from UserNameCache because the lifecycle differs:
+ * 10-minute TTL, per-thread keying, and take-and-delete consumption.
+ */
+export interface SentinelEntry {
+    /** Literal name as it appeared in the outbound text. */
+    name: string;
+    /** Why parsing failed. */
+    reason: 'not_found' | 'ambiguous';
+    /** Candidate open_ids when reason === 'ambiguous'. */
+    candidates?: Array<{
+        openId: string;
+        kind?: 'user' | 'bot';
+    }>;
+}
+export declare class SentinelStore {
+    private byThread;
+    private maxThreads;
+    private ttlMs;
+    constructor(maxThreads?: number, ttlMs?: number);
+    recordSentinels(threadKey: string, sentinels: SentinelEntry[]): void;
+    consumeSentinels(threadKey: string): SentinelEntry[];
+    clear(): void;
+    private evict;
+}
+export declare function getSentinelStore(accountId: string, maxThreads?: number, ttlMs?: number): SentinelStore;
+export declare function clearSentinelStore(accountId?: string): void;
+export declare function clearAllSentinelStores(): void;

package/src/messaging/inbound/sentinel-store.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Per-thread store for unresolved mention feedback. The outbound
+ * normalizer records a SentinelEntry whenever an `@Name` cannot be
+ * resolved; the next inbound message on the same thread consumes
+ * (take and delete) the entries, which buildMentionAnnotation surfaces
+ * as a system note so the next reply can disambiguate.
+ *
+ * Kept separate from UserNameCache because the lifecycle differs:
+ * 10-minute TTL, per-thread keying, and take-and-delete consumption.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentinelStore = void 0;
+exports.getSentinelStore = getSentinelStore;
+exports.clearSentinelStore = clearSentinelStore;
+exports.clearAllSentinelStores = clearAllSentinelStores;
+const DEFAULT_TTL_MS = 10 * 60 * 1000; // 10 min — short, avoid stale feedback
+const DEFAULT_MAX_THREADS = 200; // per-account
+function dedup(entries) {
+    const seen = new Set();
+    const out = [];
+    for (const e of entries) {
+        const key = `${e.reason}:${e.name}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(e);
+    }
+    return out;
+}
+class SentinelStore {
+    byThread = new Map();
+    maxThreads;
+    ttlMs;
+    constructor(maxThreads = DEFAULT_MAX_THREADS, ttlMs = DEFAULT_TTL_MS) {
+        this.maxThreads = maxThreads;
+        this.ttlMs = ttlMs;
+    }
+    recordSentinels(threadKey, sentinels) {
+        if (sentinels.length === 0)
+            return;
+        const existing = this.byThread.get(threadKey);
+        const merged = existing ? [...existing.entries, ...sentinels] : sentinels;
+        this.byThread.delete(threadKey); // bump LRU
+        this.byThread.set(threadKey, {
+            entries: dedup(merged),
+            expireAt: Date.now() + this.ttlMs,
+        });
+        this.evict();
+    }
+    consumeSentinels(threadKey) {
+        const stored = this.byThread.get(threadKey);
+        if (!stored)
+            return [];
+        this.byThread.delete(threadKey);
+        if (stored.expireAt <= Date.now())
+            return [];
+        return stored.entries;
+    }
+    clear() {
+        this.byThread.clear();
+    }
+    evict() {
+        while (this.byThread.size > this.maxThreads) {
+            const oldest = this.byThread.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.byThread.delete(oldest);
+        }
+    }
+}
+exports.SentinelStore = SentinelStore;
+const registry = new Map();
+function getSentinelStore(accountId, maxThreads, ttlMs) {
+    let store = registry.get(accountId);
+    if (!store) {
+        store = new SentinelStore(maxThreads, ttlMs);
+        registry.set(accountId, store);
+    }
+    return store;
+}
+function clearSentinelStore(accountId) {
+    if (accountId !== undefined) {
+        registry.get(accountId)?.clear();
+        registry.delete(accountId);
+    }
+    else {
+        clearAllSentinelStores();
+    }
+}
+function clearAllSentinelStores() {
+    for (const s of registry.values())
+        s.clear();
+    registry.clear();
+}

package/src/messaging/inbound/synthetic-message.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared helper for dispatching synthetic inbound text messages.
+ *
+ * Synthetic messages are used to resume the normal inbound pipeline after
+ * card actions or OAuth flows complete.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+export declare function dispatchSyntheticTextMessage(params: {
+    cfg: ClawdbotConfig;
+    accountId: string;
+    chatId: string;
+    senderOpenId: string;
+    text: string;
+    syntheticMessageId: string;
+    replyToMessageId: string;
+    chatType?: 'p2p' | 'group';
+    threadId?: string;
+    runtime?: {
+        log?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+    forceMention?: boolean;
+}): Promise<string>;