@larksuite/openclaw-lark 2026.5.7-beta.0 → 2026.5.12-beta.0

package/package.json

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

package/src/card/reply-dispatcher-types.d.ts

@@ -90,6 +90,8 @@ export interface CreateFeishuReplyDispatcherParams {
     skipTyping?: boolean;
     /** When true, replies are sent into the thread instead of main chat. */
     replyInThread?: boolean;
+    /** Thread root id when the reply lives inside a thread; used for sentinel keying. */
+    threadId?: string;
     toolUseDisplay: ToolUseDisplayConfig;
 }
 /**

package/src/card/reply-dispatcher.js

@@ -33,7 +33,7 @@ const log = (0, lark_logger_1.larkLogger)('card/reply-dispatcher');
 // ---------------------------------------------------------------------------
 function createFeishuReplyDispatcher(params) {
     const core = lark_client_1.LarkClient.runtime;
-    const { cfg, agentId, chatId, sessionKey, replyToMessageId, accountId, replyInThread } = params;
+    const { cfg, agentId, chatId, sessionKey, replyToMessageId, accountId, replyInThread, threadId } = params;
     // Resolve account so we can read per-account config (e.g. replyMode)
     const account = (0, accounts_1.getLarkAccount)(cfg, accountId);
     const feishuCfg = account.config;
@@ -243,6 +243,7 @@ function createFeishuReplyDispatcher(params) {
                                     replyToMessageId,
                                     replyInThread,
                                     accountId,
+                                    threadId,
                                 });
                             }
                             catch (fallbackErr) {
@@ -277,6 +278,7 @@ function createFeishuReplyDispatcher(params) {
                                         replyToMessageId,
                                         replyInThread,
                                         accountId,
+                                        threadId,
                                     });
                                 }
                                 catch (fallbackErr) {
@@ -306,6 +308,7 @@ function createFeishuReplyDispatcher(params) {
                                 replyToMessageId,
                                 replyInThread,
                                 accountId,
+                                threadId,
                             });
                         }
                         catch (err) {

package/src/messaging/inbound/dispatch-builders.d.ts

@@ -12,16 +12,18 @@ import type { HistoryEntry } from 'openclaw/plugin-sdk/reply-history';
 import type { MessageContext } from '../types';
 import type { LarkClient } from '../../core/lark-client';
 import type { DispatchContext } from './dispatch-context';
+import type { SentinelEntry } from './sentinel-store';
 /**
  * Build a `[System: ...]` mention annotation when the message @-mentions
- * non-bot users.  Returns `undefined` when there are no user mentions.
+ * non-self-bot users or when the previous reply had unresolved mentions.
+ * Returns `undefined` when there is nothing to report.
  *
  * Sender identity / chat metadata are handled by the SDK's own
  * `buildInboundUserContextPrefix` (via SenderId, SenderName, ReplyToBody,
  * InboundHistory, etc.), so we only inject the mention data that the SDK
  * does not natively support.
  */
-export declare function buildMentionAnnotation(ctx: MessageContext): string | undefined;
+export declare function buildMentionAnnotation(ctx: MessageContext, sentinels?: SentinelEntry[]): string | undefined;
 /**
  * Pure function: build the annotated message body with optional quote,
  * speaker prefix, and mention annotation (for the envelope Body).
@@ -31,7 +33,7 @@ export declare function buildMentionAnnotation(ctx: MessageContext): string | un
  * the body cleaner and avoiding misleading heuristics for non-text
  * message types (merge_forward, interactive cards, etc.).
  */
-export declare function buildMessageBody(ctx: MessageContext, quotedContent?: string): string;
+export declare function buildMessageBody(ctx: MessageContext, quotedContent?: string, sentinels?: SentinelEntry[]): string;
 /**
  * Build the BodyForAgent value: the clean message content plus an
  * optional mention annotation.
@@ -51,7 +53,7 @@ export declare function buildMessageBody(ctx: MessageContext, quotedContent?: st
  * The SDK's `detectAndLoadPromptImages` will discover image paths from
  * the text and inject them as multimodal content blocks.
  */
-export declare function buildBodyForAgent(ctx: MessageContext): string;
+export declare function buildBodyForAgent(ctx: MessageContext, sentinels?: SentinelEntry[]): string;
 /**
  * Unified call to `finalizeInboundContext`, eliminating the duplicated
  * field-mapping between permission notification and main message paths.

package/src/messaging/inbound/dispatch-builders.js

@@ -21,21 +21,48 @@ const mention_1 = require("./mention.js");
 // ---------------------------------------------------------------------------
 // Mention annotation
 // ---------------------------------------------------------------------------
+const MENTION_USAGE_HINT = 'To @mention in a reply, use `<at user_id="ou_xxx">Name</at>`; plain "@Name" won\'t notify.';
 /**
  * Build a `[System: ...]` mention annotation when the message @-mentions
- * non-bot users.  Returns `undefined` when there are no user mentions.
+ * non-self-bot users or when the previous reply had unresolved mentions.
+ * Returns `undefined` when there is nothing to report.
  *
  * Sender identity / chat metadata are handled by the SDK's own
  * `buildInboundUserContextPrefix` (via SenderId, SenderName, ReplyToBody,
  * InboundHistory, etc.), so we only inject the mention data that the SDK
  * does not natively support.
  */
-function buildMentionAnnotation(ctx) {
-    const mentions = (0, mention_1.nonBotMentions)(ctx);
+function buildMentionAnnotation(ctx, sentinels) {
+    const sections = [
+        formatMentionList((0, mention_1.nonBotMentions)(ctx)),
+        formatSentinelFeedback(sentinels),
+    ].filter((s) => !!s);
+    if (sections.length === 0)
+        return undefined;
+    sections.push(MENTION_USAGE_HINT);
+    return `[System: ${sections.join(' ')}]`;
+}
+function formatMentionList(mentions) {
     if (mentions.length === 0)
         return undefined;
-    const mentionDetails = mentions.map((t) => `${t.name} (open_id: ${t.openId})`).join(', ');
-    return `[System: This message @mentions the following users: ${mentionDetails}. Use these open_ids when performing actions involving these users. To @mention in a reply, use \`<at user_id="ou_xxx">Name</at>\`; plain "@Name" won't notify.]`;
+    const details = mentions.map((t) => `${t.name} (open_id: ${t.openId})`).join(', ');
+    return (`This message @mentions the following users: ${details}. ` +
+        `Use these open_ids when performing actions involving these users.`);
+}
+function formatSentinelFeedback(sentinels) {
+    if (!sentinels || sentinels.length === 0)
+        return undefined;
+    const lines = sentinels.map((s) => {
+        if (s.reason === 'not_found') {
+            return `"@${s.name}" was not recognized in the chat`;
+        }
+        if (s.reason === 'ambiguous' && s.candidates && s.candidates.length > 0) {
+            const ids = s.candidates.map((c) => c.openId).join(' / ');
+            return `"@${s.name}" matched multiple users (${ids}); use explicit <at user_id="...">`;
+        }
+        return `"@${s.name}" failed to resolve`;
+    });
+    return `Previous reply had unresolved mentions: ${lines.join('; ')}.`;
 }
 // ---------------------------------------------------------------------------
 // Message body builders
@@ -49,14 +76,14 @@ function buildMentionAnnotation(ctx) {
  * the body cleaner and avoiding misleading heuristics for non-text
  * message types (merge_forward, interactive cards, etc.).
  */
-function buildMessageBody(ctx, quotedContent) {
+function buildMessageBody(ctx, quotedContent, sentinels) {
     let messageBody = ctx.content;
     if (quotedContent) {
         messageBody = `[Replying to: "${quotedContent}"]\n\n${ctx.content}`;
     }
     const speaker = ctx.senderName ?? ctx.senderId;
     messageBody = `${speaker}: ${messageBody}`;
-    const mentionAnnotation = buildMentionAnnotation(ctx);
+    const mentionAnnotation = buildMentionAnnotation(ctx, sentinels);
     if (mentionAnnotation) {
         messageBody += `\n\n${mentionAnnotation}`;
     }
@@ -81,8 +108,8 @@ function buildMessageBody(ctx, quotedContent) {
  * The SDK's `detectAndLoadPromptImages` will discover image paths from
  * the text and inject them as multimodal content blocks.
  */
-function buildBodyForAgent(ctx) {
-    const mentionAnnotation = buildMentionAnnotation(ctx);
+function buildBodyForAgent(ctx, sentinels) {
+    const mentionAnnotation = buildMentionAnnotation(ctx, sentinels);
     if (mentionAnnotation) {
         return `${ctx.content}\n\n${mentionAnnotation}`;
     }

package/src/messaging/inbound/dispatch.js

@@ -35,6 +35,7 @@ const index_1 = require("../../commands/index.js");
 const send_1 = require("../outbound/send.js");
 const dispatch_commands_1 = require("./dispatch-commands.js");
 const dispatch_builders_1 = require("./dispatch-builders.js");
+const sentinel_store_1 = require("./sentinel-store.js");
 const dispatch_context_1 = require("./dispatch-context.js");
 const mention_1 = require("./mention.js");
 const gate_1 = require("./gate.js");
@@ -209,6 +210,7 @@ async function dispatchNormalMessage(dc, ctxPayload, chatHistories, historyKey,
         chatType: dc.ctx.chatType,
         skipTyping,
         replyInThread: dc.isThread,
+        threadId: dc.isThread ? dc.ctx.threadId : undefined,
         toolUseDisplay,
     });
     // Create an AbortController so the abort fast-path can cancel the
@@ -288,9 +290,14 @@ async function dispatchToAgent(params) {
             baseSessionKey: dc.route.sessionKey,
         });
     }
-    // 2. Build annotated message body
-    const messageBody = (0, dispatch_builders_1.buildMessageBody)(params.ctx, params.quotedContent);
-    // 3. Permission-error notification (optional side-effect).
+    // Consume any pending mention sentinels for this thread. Take and
+    // delete is one shot per inbound — capture once, hand to both body
+    // builders below.
+    const sentinelKey = (0, chat_queue_1.threadScopedKey)(dc.ctx.chatId, dc.isThread ? dc.ctx.threadId : undefined);
+    const sentinels = (0, sentinel_store_1.getSentinelStore)(dc.account.accountId).consumeSentinels(sentinelKey);
+    // 3. Build annotated message body
+    const messageBody = (0, dispatch_builders_1.buildMessageBody)(params.ctx, params.quotedContent, sentinels);
+    // 4. Permission-error notification (optional side-effect).
     //    Isolated so a failure here does not block the main message dispatch.
     //    Skipped for comment targets: the streaming card dispatcher inside
     //    dispatchPermissionNotification sends via IM APIs which don't
@@ -303,13 +310,13 @@ async function dispatchToAgent(params) {
             dc.error(`feishu[${dc.account.accountId}]: permission notification failed, continuing: ${String(err)}`);
         }
     }
-    // 4. Build main envelope (with group chat history)
+    // 5. Build main envelope (with group chat history)
     const { combinedBody, historyKey } = (0, dispatch_builders_1.buildEnvelopeWithHistory)(dc, messageBody, params.chatHistories, params.historyLimit);
-    // 5. Build BodyForAgent with mention annotation (if any).
+    // 6. Build BodyForAgent with mention annotation (if any).
     //    SDK >= 2026.2.10 no longer falls back to Body for BodyForAgent,
     //    so we must set it explicitly to preserve the annotation.
-    const bodyForAgent = (0, dispatch_builders_1.buildBodyForAgent)(params.ctx);
-    // 6. Build InboundHistory for SDK metadata injection (>= 2026.2.10).
+    const bodyForAgent = (0, dispatch_builders_1.buildBodyForAgent)(params.ctx, sentinels);
+    // 7. Build InboundHistory for SDK metadata injection (>= 2026.2.10).
     //    The SDK's buildInboundUserContextPrefix renders these as structured
     //    JSON blocks; earlier SDK versions simply ignore unknown fields.
     const threadHistoryKey = (0, chat_queue_1.threadScopedKey)(dc.ctx.chatId, dc.isThread ? dc.ctx.threadId : undefined);
@@ -320,7 +327,7 @@ async function dispatchToAgent(params) {
             timestamp: entry.timestamp ?? Date.now(),
         }))
         : undefined;
-    // 7. Build inbound context payload
+    // 8. Build inbound context payload
     const isBareNewOrReset = /^\/(?:new|reset)\s*$/i.test((params.ctx.content ?? '').trim());
     const groupSystemPrompt = dc.isGroup
         ? params.groupConfig?.systemPrompt?.trim() || params.defaultGroupConfig?.systemPrompt?.trim() || undefined
@@ -357,7 +364,7 @@ async function dispatchToAgent(params) {
             ...(dc.ctx.threadId ? { MessageThreadId: dc.ctx.threadId } : {}),
         },
     });
-    // 8a. Intercept /feishu commands for i18n multi-locale card dispatch
+    // 9a. Intercept /feishu commands for i18n multi-locale card dispatch
     //     Must run BEFORE the SDK command check — the SDK does not recognise
     //     plugin-registered commands via isControlCommandMessage, so
     //     /feishu_* falls through to the AI agent otherwise.

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

@@ -4,14 +4,16 @@
  *
  * Inbound message handling pipeline for the Lark/Feishu channel plugin.
  *
- * Orchestrates a seven-stage pipeline:
+ * Orchestrates a nine-stage pipeline:
  *   1. Account resolution
  *   2. Event parsing         → parse.ts (merge_forward expanded in-place)
- *   3. Sender enrichment     → enrich.ts (lightweight, before gate)
- *   4. Policy gate           → gate.ts
- *   5. User name prefetch    → enrich.ts (batch cache warm-up)
- *   6. Content resolution    → enrich.ts (media / quote, parallel)
- *   7. Agent dispatch        → dispatch.ts
+ *   3. Empty-message guard   → early return for text-less, media-less messages
+ *   4. Sender enrichment     → enrich.ts (lightweight, before gate)
+ *   5. Policy gate           → gate.ts
+ *   6. User name prefetch    → enrich.ts (batch cache warm-up)
+ *   7. Content resolution    → enrich.ts (media / quote, parallel)
+ *   8. Command authorization → plugin-sdk/command-auth
+ *   9. Agent dispatch        → dispatch.ts
  */
 import type { ClawdbotConfig, RuntimeEnv } from 'openclaw/plugin-sdk';
 import type { HistoryEntry } from 'openclaw/plugin-sdk/reply-history';

package/src/messaging/inbound/handler.js

@@ -5,14 +5,16 @@
  *
  * Inbound message handling pipeline for the Lark/Feishu channel plugin.
  *
- * Orchestrates a seven-stage pipeline:
+ * Orchestrates a nine-stage pipeline:
  *   1. Account resolution
  *   2. Event parsing         → parse.ts (merge_forward expanded in-place)
- *   3. Sender enrichment     → enrich.ts (lightweight, before gate)
- *   4. Policy gate           → gate.ts
- *   5. User name prefetch    → enrich.ts (batch cache warm-up)
- *   6. Content resolution    → enrich.ts (media / quote, parallel)
- *   7. Agent dispatch        → dispatch.ts
+ *   3. Empty-message guard   → early return for text-less, media-less messages
+ *   4. Sender enrichment     → enrich.ts (lightweight, before gate)
+ *   5. Policy gate           → gate.ts
+ *   6. User name prefetch    → enrich.ts (batch cache warm-up)
+ *   7. Content resolution    → enrich.ts (media / quote, parallel)
+ *   8. Command authorization → plugin-sdk/command-auth
+ *   9. Agent dispatch        → dispatch.ts
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleFeishuMessage = handleFeishuMessage;
@@ -60,7 +62,16 @@ async function handleFeishuMessage(params) {
         cfg: accountScopedCfg,
         accountId: account.accountId,
     });
-    // 3. Enrich (lightweight): sender name + permission error tracking
+    // 3. Early reject: skip empty-text messages with no media resources.
+    //    OpenClaw 2026.4.29 adds a core-side guard for this (##74634), but
+    //    rejecting here avoids wasting cycles on enrichment, gate, and
+    //    dispatch for messages that would be silently dropped at the deliver
+    //    callback anyway.
+    if (!ctx.content.trim() && ctx.resources.length === 0) {
+        log(`feishu[${account.accountId}]: empty message ${ctx.messageId} (no text, no media), skipping`);
+        return;
+    }
+    // 4. Enrich (lightweight): sender name + permission error tracking
     const { ctx: enrichedCtx, permissionError } = await (0, enrich_1.resolveSenderInfo)({
         ctx,
         account,
@@ -70,7 +81,7 @@ async function handleFeishuMessage(params) {
     log(`feishu[${account.accountId}]: received message from ${ctx.senderId} in ${ctx.chatId} (${ctx.chatType})`);
     logger.info(`received from ${ctx.senderId} in ${ctx.chatId} (${ctx.chatType})`);
     const historyLimit = Math.max(0, accountFeishuCfg?.historyLimit ?? accountScopedCfg.messages?.groupChat?.historyLimit ?? reply_history_1.DEFAULT_GROUP_HISTORY_LIMIT);
-    // 4. Gate: policy / access-control checks (skipped for synthetic messages)
+    // 5. Gate: policy / access-control checks (skipped for synthetic messages)
     const gate = forceMention
         ? { allowed: true }
         : await (0, gate_1.checkMessageGate)({ ctx, accountFeishuCfg, account, accountScopedCfg, log });
@@ -90,15 +101,15 @@ async function handleFeishuMessage(params) {
         }
         return;
     }
-    // 5. Batch pre-warm user name cache (sender + mentions)
+    // 6. Batch pre-warm user name cache (sender + mentions)
     await (0, enrich_1.prefetchUserNames)({ ctx, account, log });
-    // 6. Enrich (heavyweight, after gate — parallel where possible)
+    // 7. Enrich (heavyweight, after gate — parallel where possible)
     const enrichParams = { ctx, accountScopedCfg, account, log };
     const [mediaResult, quotedContent] = await Promise.all([
         (0, enrich_1.resolveMedia)(enrichParams),
         (0, enrich_1.resolveQuotedContent)(enrichParams),
     ]);
-    // 6b. Replace Feishu file-key placeholders in content with local
+    // 7b. Replace Feishu file-key placeholders in content with local
     //     file paths so the SDK can detect images for native vision and
     //     the AI receives meaningful file references.
     if (mediaResult.mediaList.length > 0) {
@@ -107,7 +118,7 @@ async function handleFeishuMessage(params) {
             content: (0, enrich_1.substituteMediaPaths)(ctx.content, mediaResult.mediaList),
         };
     }
-    // 7. Compute commandAuthorized via SDK access group command gating
+    // 8. Compute commandAuthorized via SDK access group command gating
     const core = lark_client_1.LarkClient.runtime;
     const isGroup = ctx.chatType === 'group';
     const dmPolicy = accountFeishuCfg?.dmPolicy ?? 'pairing';
@@ -152,7 +163,7 @@ async function handleFeishuMessage(params) {
         shouldComputeCommandAuthorized: core.channel.commands.shouldComputeCommandAuthorized,
         resolveCommandAuthorizedFromAuthorizers: core.channel.commands.resolveCommandAuthorizedFromAuthorizers,
     });
-    // 8. Dispatch to agent
+    // 9. Dispatch to agent
     // groupConfig and defaultGroupConfig are already resolved above.
     try {
         await (0, dispatch_1.dispatchToAgent)({

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

@@ -20,9 +20,9 @@ export type { MentionInfo } from '../types';
 export declare function isMentionAll(mention: {
     key: string;
 }): boolean;
-/** Whether the bot was @-mentioned. */
+/** Whether the receiving bot itself was @-mentioned. */
 export declare function mentionedBot(ctx: MessageContext): boolean;
-/** All non-bot mentions. */
+/** All mentions excluding the receiving bot itself. */
 export declare function nonBotMentions(ctx: MessageContext): MentionInfo[];
 /**
  * Remove all @mention placeholder keys from the message text.

package/src/messaging/inbound/mention.js

@@ -34,11 +34,11 @@ const utils_1 = require("../converters/utils.js");
 function isMentionAll(mention) {
     return mention.key === '@_all';
 }
-/** Whether the bot was @-mentioned. */
+/** Whether the receiving bot itself was @-mentioned. */
 function mentionedBot(ctx) {
     return ctx.mentions.some((m) => m.isBot);
 }
-/** All non-bot mentions. */
+/** All mentions excluding the receiving bot itself. */
 function nonBotMentions(ctx) {
     return ctx.mentions.filter((m) => !m.isBot);
 }

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/user-name-cache-store.d.ts

@@ -3,19 +3,59 @@
  * SPDX-License-Identifier: MIT
  *
  * Account-scoped cache registry for Feishu user display names.
+ *
+ * Stores forward (openId → name + kind) and reverse (normalizedName → Set<openId>)
+ * indexes for mention resolution. Per-account, LRU + TTL.
  */
+export type PrincipalKind = 'user' | 'bot';
+export interface MentionMatch {
+    openId: string;
+    name: string;
+    kind?: PrincipalKind;
+}
+export interface ChatMember {
+    openId: string;
+    name: string;
+    kind: PrincipalKind;
+}
+export interface ChatMembersEntry {
+    members: ChatMember[];
+    expireAt: number;
+}
 export declare class UserNameCache {
-    private map;
+    private nameByOpenId;
+    private openIdsByName;
     private maxSize;
     private ttlMs;
-    constructor(maxSize?: number, ttlMs?: number);
+    private chatBots;
+    private chatMembers;
+    private inFlight;
+    private maxChats;
+    constructor(maxSize?: number, ttlMs?: number, maxChats?: number);
     has(openId: string): boolean;
     get(openId: string): string | undefined;
     set(openId: string, name: string): void;
+    setWithKind(openId: string, name: string, kind: PrincipalKind): void;
+    lookupByName(name: string): MentionMatch[];
     setMany(entries: Iterable<[string, string]>): void;
     filterMissing(openIds: string[]): string[];
     getMany(openIds: string[]): Map<string, string>;
+    recordChatBots(chatId: string, members: Array<{
+        openId: string;
+        name: string;
+    }>): void;
+    recordChatMembers(chatId: string, members: ChatMember[]): void;
+    getChatBots(chatId: string): ChatMembersEntry | null;
+    getChatMembers(chatId: string): ChatMembersEntry | null;
+    getInflight(key: string): Promise<void> | undefined;
+    setInflight(key: string, promise: Promise<void>): void;
+    clearInflight(key: string): void;
     clear(): void;
+    private writeEntry;
+    private writeEntryNoEvict;
+    private deleteOpenId;
+    private removeFromReverse;
+    private evictChats;
     private evict;
 }
 export declare function getUserNameCache(accountId: string): UserNameCache;