@larksuite/openclaw-lark 2026.3.9

package/src/messaging/inbound/policy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Access control policies for the Feishu/Lark channel plugin.
+ *
+ * Provides allowlist matching, group configuration lookup, tool policy
+ * extraction, and group access checks.
+ */
+import type { ChannelGroupContext, GroupToolPolicyConfig } from 'openclaw/plugin-sdk';
+import type { FeishuConfig, FeishuGroupConfig } from '../../core/types';
+export interface FeishuAllowlistMatch {
+    allowed: boolean;
+    matchKey?: string;
+    matchSource?: 'wildcard' | 'id' | 'name';
+}
+/**
+ * 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 }`.
+ */
+export declare function resolveFeishuAllowlistMatch(params: {
+    allowFrom: Array<string | number>;
+    senderId: string;
+    senderName?: string | null;
+}): FeishuAllowlistMatch;
+/**
+ * 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.
+ */
+export declare function resolveFeishuGroupConfig(params: {
+    cfg?: FeishuConfig;
+    groupId?: string | null;
+}): FeishuGroupConfig | undefined;
+/**
+ * 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 配置独立生效。
+ */
+export declare function resolveFeishuGroupToolPolicy(params: ChannelGroupContext): GroupToolPolicyConfig | undefined;
+/**
+ * Determine whether an inbound group message should be processed.
+ *
+ * - `disabled` --> always rejected
+ * - `open`     --> always allowed
+ * - `allowlist` --> allowed only when the sender matches the allowlist
+ */
+export declare function isFeishuGroupAllowed(params: {
+    groupPolicy: 'open' | 'allowlist' | 'disabled';
+    allowFrom: Array<string | number>;
+    senderId: string;
+    senderName?: string | null;
+}): boolean;
+/**
+ * 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.
+ */
+export declare function splitLegacyGroupAllowFrom(rawGroupAllowFrom: Array<string | number>): {
+    legacyChatIds: string[];
+    senderAllowFrom: string[];
+};
+/**
+ * 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).
+ */
+export declare function resolveGroupSenderPolicyContext(params: {
+    groupConfig?: FeishuGroupConfig;
+    defaultConfig?: FeishuGroupConfig;
+    accountFeishuCfg?: FeishuConfig;
+    senderGroupAllowFrom: Array<string | number>;
+}): {
+    senderPolicy: 'open' | 'allowlist' | 'disabled';
+    senderAllowFrom: Array<string | number>;
+};
+//# sourceMappingURL=policy.d.ts.map

package/src/messaging/inbound/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../src/messaging/inbound/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOxE,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,SAAS,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,GAAG,oBAAoB,CAyBvB;AAMD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,GAAG,iBAAiB,GAAG,SAAS,CAiBhC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,mBAAmB,GAAG,qBAAqB,GAAG,SAAS,CAe3G;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAC/C,SAAS,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,GAAG,OAAO,CAUV;AAMD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,iBAAiB,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG;IACpF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAYA;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE;IACtD,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,gBAAgB,CAAC,EAAE,YAAY,CAAC;IAChC,oBAAoB,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAC9C,GAAG;IACF,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAChD,eAAe,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CACzC,CAaA"}

package/src/messaging/inbound/policy.js

@@ -0,0 +1,161 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Access control policies for the Feishu/Lark channel plugin.
+ *
+ * Provides allowlist matching, group configuration lookup, tool policy
+ * extraction, and group access checks.
+ */
+import { getLarkAccount } from '../../core/accounts';
+/**
+ * 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 }`.
+ */
+export 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.
+ */
+export 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 配置独立生效。
+ */
+export function resolveFeishuGroupToolPolicy(params) {
+    // 使用 getLarkAccount 获取 per-account 合并后的飞书渠道配置，
+    // 而非直接读取 cfg.channels.feishu（顶层全局配置）。
+    const account = 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
+ */
+export 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.
+ */
+export 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).
+ */
+export 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 };
+}
+//# sourceMappingURL=policy.js.map

package/src/messaging/inbound/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../../src/messaging/inbound/policy.ts"],"names":[],"mappings":"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"}

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 Feishu/Lark 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, HistoryEntry } from 'openclaw/plugin-sdk';
+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>;
+//# sourceMappingURL=reaction-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reaction-handler.d.ts","sourceRoot":"","sources":["../../../../src/messaging/inbound/reaction-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEpF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAG3D,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAepF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,QAAQ,EAAE,KAAK,GAAG,OAAO,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,GAAG,EAAE,iBAAiB,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,0BAA0B,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA8GlC;AAMD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,0BAA0B,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,WAAW,EAAE,eAAe,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAgGhB"}

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

@@ -0,0 +1,221 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Reaction event handler for the Feishu/Lark 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 * as crypto from 'node:crypto';
+import { DEFAULT_GROUP_HISTORY_LIMIT } from 'openclaw/plugin-sdk';
+import { getLarkAccount } from '../../core/accounts';
+import { getMessageFeishu } from '../shared/message-lookup';
+import { isThreadCapableGroup, getChatTypeFeishu } from '../../core/chat-info-cache';
+import { resolveUserName } from './user-name-cache';
+import { dispatchToAgent } from './dispatch';
+import { resolveFeishuGroupConfig } from './policy';
+import { larkLogger } from '../../core/lark-logger';
+const logger = 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.
+ */
+export async function resolveReactionContext(params) {
+    const { cfg, event, botOpenId, runtime, accountId } = params;
+    const log = runtime?.log ?? ((...args) => logger.info(args.map(String).join(' ')));
+    const account = 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([
+        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;
+    }
+    // The mget API returns app_id (cli_xxx) as sender.id for bot messages,
+    // not the bot's open_id (ou_xxx). Match against the account's appId.
+    const isBotMessage = msg.senderType === 'app' && msg.senderId === account.appId;
+    if (reactionMode === 'own' && !isBotMessage) {
+        log(`feishu[${accountId}]: reaction on non-bot message ${messageId}, skipping (senderId=${msg.senderId}, senderType=${msg.senderType}, botOpenId=${botOpenId}, appId=${account.appId})`);
+        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 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 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
+// ---------------------------------------------------------------------------
+export 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 = 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: [],
+        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 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 ? resolveFeishuGroupConfig({ cfg: accountFeishuCfg, groupId: ctx.chatId }) : undefined;
+    const defaultGroupConfig = isGroup ? accountFeishuCfg?.groups?.['*'] : undefined;
+    const historyLimit = Math.max(0, accountFeishuCfg?.historyLimit ?? accountScopedCfg.messages?.groupChat?.historyLimit ?? DEFAULT_GROUP_HISTORY_LIMIT);
+    // ---- Step E: Dispatch directly to agent ----
+    try {
+        await 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)}`);
+    }
+}
+//# sourceMappingURL=reaction-handler.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reaction-handler.js","sourceRoot":"","sources":["../../../../src/messaging/inbound/reaction-handler.ts"],"names":[],"mappings":"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"}

package/src/messaging/inbound/user-name-cache.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Account-scoped LRU cache for Feishu user display names.
+ *
+ * Provides:
+ * - `UserNameCache` — per-account LRU Map with TTL
+ * - `getUserNameCache(accountId)` — singleton registry
+ * - `batchResolveUserNames()` — batch API via `contact/v3/users/batch`
+ * - `resolveUserName()` — single-user fallback via `contact.user.get`
+ * - `clearUserNameCache()` — teardown hook (called from LarkClient.clearCache)
+ */
+import type { LarkAccount } from '../../core/types';
+import { type PermissionError } from './permission';
+export declare class UserNameCache {
+    private map;
+    private maxSize;
+    private ttlMs;
+    constructor(maxSize?: number, ttlMs?: number);
+    /** Check whether the cache holds a (possibly empty) entry for this openId. */
+    has(openId: string): boolean;
+    /** Get a cached name (refreshes LRU position). Returns `undefined` on miss or expiry. */
+    get(openId: string): string | undefined;
+    /** Write a single entry (evicts oldest if over capacity). */
+    set(openId: string, name: string): void;
+    /** Write multiple entries at once. */
+    setMany(entries: Iterable<[string, string]>): void;
+    /** Return openIds that are NOT present (or expired) in the cache. */
+    filterMissing(openIds: string[]): string[];
+    /** Bulk read — returns a Map of openId→name for all hits (including empty-string names). */
+    getMany(openIds: string[]): Map<string, string>;
+    /** Clear all entries. */
+    clear(): void;
+    private evict;
+}
+/** Get (or create) the UserNameCache for a given account. */
+export declare function getUserNameCache(accountId: string): UserNameCache;
+/**
+ * Clear user-name caches.
+ * - With `accountId`: clear that single cache.
+ * - Without: clear all caches.
+ */
+export declare function clearUserNameCache(accountId?: string): void;
+/**
+ * Batch-resolve user display names.
+ *
+ * 1. Check cache → collect misses
+ * 2. Deduplicate
+ * 3. Call `GET /open-apis/contact/v3/users/batch` in chunks of 50
+ * 4. Write results back to cache
+ * 5. Return full Map<openId, name> (cache hits + API results)
+ *
+ * Best-effort: API errors are logged but never thrown.
+ */
+export declare function batchResolveUserNames(params: {
+    account: LarkAccount;
+    openIds: string[];
+    log: (...args: unknown[]) => void;
+}): Promise<Map<string, string>>;
+/**
+ * Create a `batchResolveNames` callback for use in `ConvertContext`.
+ *
+ * The returned function calls `batchResolveUserNames` with the given
+ * account and log function, populating the TAT user-name cache.
+ */
+export declare function createBatchResolveNames(account: LarkAccount, log: (...args: unknown[]) => void): (openIds: string[]) => Promise<void>;
+export interface ResolveUserNameResult {
+    name?: string;
+    permissionError?: PermissionError;
+}
+/**
+ * Resolve a single user's display name.
+ *
+ * Checks the account-scoped cache first, then falls back to the
+ * `contact.user.get` API (same as the old `resolveFeishuSenderName`).
+ */
+export declare function resolveUserName(params: {
+    account: LarkAccount;
+    openId: string;
+    log: (...args: unknown[]) => void;
+}): Promise<ResolveUserNameResult>;
+//# sourceMappingURL=user-name-cache.d.ts.map

package/src/messaging/inbound/user-name-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-name-cache.d.ts","sourceRoot":"","sources":["../../../../src/messaging/inbound/user-name-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAc5E,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAAiC;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,SAAmB,EAAE,KAAK,SAAiB;IAK9D,8EAA8E;IAC9E,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAU5B,yFAAyF;IACzF,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAavC,6DAA6D;IAC7D,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAMvC,sCAAsC;IACtC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI;IAQlD,qEAAqE;IACrE,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAI1C,4FAA4F;IAC5F,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAU/C,yBAAyB;IACzB,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,KAAK;CAOd;AAQD,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ3D;AASD;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACnC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAmD/B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAChC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAItC;AAMD,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACnC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAqCjC"}