@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/inbound/user-name-cache.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUserNameCache = exports.clearUserNameCache = exports.UserNameCache = void 0;
+exports.batchResolveUserNames = batchResolveUserNames;
+exports.createBatchResolveNames = createBatchResolveNames;
+exports.resolveBotName = resolveBotName;
+exports.prefetchChatBots = prefetchChatBots;
+exports.prefetchChatMembers = prefetchChatMembers;
+exports.resolveUserName = resolveUserName;
+const lark_client_1 = require("../../core/lark-client.js");
+const user_name_cache_store_1 = require("./user-name-cache-store.js");
+const permission_1 = require("./permission.js");
+var user_name_cache_store_2 = require("./user-name-cache-store.js");
+Object.defineProperty(exports, "UserNameCache", { enumerable: true, get: function () { return user_name_cache_store_2.UserNameCache; } });
+Object.defineProperty(exports, "clearUserNameCache", { enumerable: true, get: function () { return user_name_cache_store_2.clearUserNameCache; } });
+Object.defineProperty(exports, "getUserNameCache", { enumerable: true, get: function () { return user_name_cache_store_2.getUserNameCache; } });
+// ---------------------------------------------------------------------------
+// Batch resolve via contact/v3/users/batch
+// ---------------------------------------------------------------------------
+/** Max user_ids per API call (Feishu limit). */
+const BATCH_SIZE = 50;
+/**
+ * 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.
+ */
+async function batchResolveUserNames(params) {
+    const { account, openIds, log } = params;
+    if (!account.configured || openIds.length === 0) {
+        return new Map();
+    }
+    const cache = (0, user_name_cache_store_1.getUserNameCache)(account.accountId);
+    const result = cache.getMany(openIds);
+    // Deduplicate missing IDs
+    const missing = [...new Set(cache.filterMissing(openIds))];
+    if (missing.length === 0)
+        return result;
+    const client = lark_client_1.LarkClient.fromAccount(account).sdk;
+    // Split into chunks of BATCH_SIZE and call SDK method
+    for (let i = 0; i < missing.length; i += BATCH_SIZE) {
+        const chunk = missing.slice(i, i + BATCH_SIZE);
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const res = await client.contact.user.batch({
+                params: {
+                    user_ids: chunk,
+                    user_id_type: 'open_id',
+                },
+            });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const items = res?.data?.items ?? [];
+            const resolved = new Set();
+            for (const item of items) {
+                const openId = item.open_id;
+                if (!openId)
+                    continue;
+                const name = item.name || item.display_name || item.nickname || item.en_name || '';
+                cache.setWithKind(openId, name, 'user');
+                result.set(openId, name);
+                resolved.add(openId);
+            }
+            // Cache empty names for IDs the API didn't return (no permission, etc.)
+            for (const id of chunk) {
+                if (!resolved.has(id)) {
+                    cache.setWithKind(id, '', 'user');
+                    result.set(id, '');
+                }
+            }
+        }
+        catch (err) {
+            log(`batchResolveUserNames: failed: ${String(err)}`);
+        }
+    }
+    return result;
+}
+/**
+ * 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.
+ */
+function createBatchResolveNames(account, log) {
+    return async (openIds) => {
+        await batchResolveUserNames({ account, openIds, log });
+    };
+}
+/**
+ * Resolve a single bot's display name via `/open-apis/bot/v3/bots/basic_batch`.
+ *
+ * Bots are not returned by the contact API, so they have their own endpoint.
+ * Names share the same account-scoped cache (keyed by openId) since both
+ * bots and users have `ou_` prefixed openIds and a single display name.
+ */
+async function resolveBotName(params) {
+    const { account, openId, log } = params;
+    if (!account.configured || !openId)
+        return {};
+    const cache = (0, user_name_cache_store_1.getUserNameCache)(account.accountId);
+    if (cache.has(openId))
+        return { name: cache.get(openId) ?? '' };
+    try {
+        const client = lark_client_1.LarkClient.fromAccount(account).sdk;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await client.request({
+            method: 'GET',
+            url: '/open-apis/bot/v3/bots/basic_batch',
+            params: { bot_ids: [openId] },
+        });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const bot = res?.data?.bots?.[openId];
+        const name = bot?.name || bot?.i18n_names?.zh_cn || bot?.i18n_names?.en_us || '';
+        // Cache even empty names to avoid repeated API calls for bots
+        // whose names we cannot resolve.
+        cache.setWithKind(openId, name, 'bot');
+        return { name: name || undefined };
+    }
+    catch (err) {
+        // Bot name resolution is best-effort: missing `bot:basic_info` scope
+        // should not surface as a permission notification to the agent. Log
+        // and cache an empty name so we don't retry, then fall back to openId.
+        const permErr = (0, permission_1.extractPermissionError)(err);
+        if (permErr) {
+            log(`feishu: permission error resolving bot name (best-effort, ignored): code=${permErr.code}`);
+        }
+        else {
+            log(`feishu: failed to resolve bot name for ${openId}: ${String(err)}`);
+        }
+        cache.setWithKind(openId, '', 'bot');
+        return {};
+    }
+}
+// ---------------------------------------------------------------------------
+// Lazy chat-member prefetch
+// ---------------------------------------------------------------------------
+/** Returns the numeric Feishu API error code from a thrown error, or null. */
+function extractApiCode(err) {
+    const permErr = (0, permission_1.extractPermissionError)(err);
+    if (typeof permErr?.code === 'number')
+        return permErr.code;
+    if (err && typeof err === 'object') {
+        const code = err.response?.data?.code;
+        if (typeof code === 'number')
+            return code;
+    }
+    return null;
+}
+/**
+ * Runs a chat-member prefetch with shared lifecycle:
+ *
+ * 1. Skip on unconfigured account or empty chatId.
+ * 2. Dedup concurrent calls per (tag, chatId) via `cache.inFlight`.
+ * 3. Skip when an in-TTL snapshot already exists.
+ * 4. On API error, cache an empty list to short-circuit retries; on
+ *    transient errors, leave the cache untouched so the next call retries.
+ */
+async function runChatPrefetch(spec, account, chatId, log) {
+    if (!account.configured || !chatId)
+        return;
+    const cache = (0, user_name_cache_store_1.getUserNameCache)(account.accountId);
+    const key = `${spec.tag}:${chatId}`;
+    const existing = cache.getInflight(key);
+    if (existing)
+        return existing;
+    if (spec.isFresh(cache, chatId))
+        return;
+    const promise = (async () => {
+        try {
+            const client = lark_client_1.LarkClient.fromAccount(account).sdk;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const res = await client.request({
+                method: 'GET',
+                url: spec.url(chatId),
+                params: spec.params,
+            });
+            const items = res?.data?.items ?? [];
+            const members = items.map(spec.parseItem).filter((m) => m !== null);
+            spec.record(cache, chatId, members);
+        }
+        catch (err) {
+            const apiCode = extractApiCode(err);
+            if (apiCode != null) {
+                // Application-level refusal: cache an empty list to short-circuit
+                // further retries. Persistent errors (e.g. missing scope) will not
+                // resolve within the cache TTL anyway.
+                log(`prefetchChat${spec.tag}[${chatId}]: API error code=${apiCode}, caching empty`);
+                spec.record(cache, chatId, []);
+            }
+            else {
+                log(`prefetchChat${spec.tag}[${chatId}]: failed: ${String(err)}`);
+            }
+        }
+        finally {
+            cache.clearInflight(key);
+        }
+    })();
+    cache.setInflight(key, promise);
+    return promise;
+}
+const CHAT_BOTS_SPEC = {
+    tag: 'Bots',
+    url: (chatId) => `/open-apis/im/v1/chats/${chatId}/members/bots`,
+    params: {},
+    parseItem: (raw) => {
+        const it = raw;
+        const openId = String(it.bot_id ?? it.open_id ?? '');
+        if (!openId)
+            return null;
+        return { openId, name: String(it.bot_name ?? it.name ?? '') };
+    },
+    isFresh: (cache, chatId) => cache.getChatBots(chatId) !== null,
+    record: (cache, chatId, members) => cache.recordChatBots(chatId, members),
+};
+function memberTypeToKind(type) {
+    return type === 'app' ? 'bot' : 'user';
+}
+const CHAT_MEMBERS_SPEC = {
+    tag: 'Members',
+    url: (chatId) => `/open-apis/im/v1/chats/${chatId}/members`,
+    params: { member_id_type: 'open_id', page_size: 100 },
+    parseItem: (raw) => {
+        const it = raw;
+        const openId = String(it.member_id ?? it.open_id ?? '');
+        if (!openId)
+            return null;
+        return { openId, name: String(it.name ?? ''), kind: memberTypeToKind(it.member_type) };
+    },
+    isFresh: (cache, chatId) => cache.getChatMembers(chatId) !== null,
+    record: (cache, chatId, members) => cache.recordChatMembers(chatId, members),
+};
+/**
+ * Fetches the bot members of a chat via
+ * `GET /open-apis/im/v1/chats/{chat_id}/members/bots` and writes them
+ * to the per-account cache.
+ */
+async function prefetchChatBots(account, chatId, log) {
+    return runChatPrefetch(CHAT_BOTS_SPEC, account, chatId, log);
+}
+/**
+ * Fetches the human members of a chat via
+ * `GET /open-apis/im/v1/chats/{chat_id}/members` and writes them to
+ * the per-account cache.
+ */
+async function prefetchChatMembers(account, chatId, log) {
+    return runChatPrefetch(CHAT_MEMBERS_SPEC, account, chatId, log);
+}
+/**
+ * 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`).
+ */
+async function resolveUserName(params) {
+    const { account, openId, log } = params;
+    if (!account.configured || !openId)
+        return {};
+    const cache = (0, user_name_cache_store_1.getUserNameCache)(account.accountId);
+    if (cache.has(openId))
+        return { name: cache.get(openId) ?? '' };
+    try {
+        const client = lark_client_1.LarkClient.fromAccount(account).sdk;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await client.contact.user.get({
+            path: { user_id: openId },
+            params: { user_id_type: 'open_id' },
+        });
+        const name = res?.data?.user?.name ||
+            res?.data?.user?.display_name ||
+            res?.data?.user?.nickname ||
+            res?.data?.user?.en_name ||
+            '';
+        // Cache even empty names to avoid repeated API calls for users
+        // whose names we cannot resolve (e.g. due to permissions).
+        cache.setWithKind(openId, name, 'user');
+        return { name: name || undefined };
+    }
+    catch (err) {
+        const permErr = (0, permission_1.extractPermissionError)(err);
+        if (permErr) {
+            log(`feishu: permission error resolving user name: code=${permErr.code}`);
+            // Cache empty name so we don't retry a known-failing openId
+            cache.setWithKind(openId, '', 'user');
+            return { permissionError: permErr };
+        }
+        log(`feishu: failed to resolve user name for ${openId}: ${String(err)}`);
+        return {};
+    }
+}

package/src/messaging/inbound/vc-meeting-invited-handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * VC meeting invited event handler for the Lark/Feishu channel plugin.
+ *
+ * Handles `vc.bot.meeting_invited_v1` by converting the event into a
+ * synthetic natural-language inbound and dispatching it through the
+ * standard OpenClaw agent pipeline.
+ */
+import type { ClawdbotConfig, RuntimeEnv } from 'openclaw/plugin-sdk';
+import type { HistoryEntry } from 'openclaw/plugin-sdk/reply-history';
+import type { FeishuVcMeetingInvitedEvent } from '../types';
+export declare function handleFeishuVcMeetingInvited(params: {
+    cfg: ClawdbotConfig;
+    event: FeishuVcMeetingInvitedEvent;
+    runtime?: RuntimeEnv;
+    chatHistories?: Map<string, HistoryEntry[]>;
+    accountId?: string;
+}): Promise<void>;

package/src/messaging/inbound/vc-meeting-invited-handler.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * VC meeting invited event handler for the Lark/Feishu channel plugin.
+ *
+ * Handles `vc.bot.meeting_invited_v1` by converting the event into a
+ * synthetic natural-language inbound and dispatching it through the
+ * standard OpenClaw agent pipeline.
+ */
+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.handleFeishuVcMeetingInvited = handleFeishuVcMeetingInvited;
+const crypto = __importStar(require("node:crypto"));
+const synthetic_target_1 = require("../../core/synthetic-target.js");
+const accounts_1 = require("../../core/accounts.js");
+const lark_logger_1 = require("../../core/lark-logger.js");
+const dispatch_1 = require("./dispatch.js");
+const gate_effects_1 = require("./gate-effects.js");
+const gate_1 = require("./gate.js");
+const policy_1 = require("./policy.js");
+const vc_sender_1 = require("./vc-sender.js");
+const logger = (0, lark_logger_1.larkLogger)('inbound/vc-meeting-invited-handler');
+function buildSyntheticEvent(event) {
+    const meetingNo = event.meeting?.meeting_no?.trim() ?? '';
+    // Both meeting_no and inviter identity are required for this event.
+    if (!meetingNo) {
+        return null;
+    }
+    const sender = (0, vc_sender_1.resolveVcSender)(event);
+    if (!sender.senderId) {
+        return null;
+    }
+    return {
+        eventType: 'vc.bot.meeting_invited_v1',
+        source: 'feishu-vc-event',
+        eventId: event.event_id?.trim() || undefined,
+        meetingId: event.meeting?.id?.trim() || undefined,
+        meetingNo,
+        topic: event.meeting?.topic?.trim() || undefined,
+        senderId: sender.senderId,
+        senderOpenId: sender.senderOpenId,
+        senderUserId: sender.senderUserId,
+        senderUnionId: sender.senderUnionId,
+        senderName: sender.senderName,
+        inviteTime: event.invite_time?.trim() || undefined,
+        callId: event.call_id?.trim() || undefined,
+    };
+}
+function buildSyntheticContext(event) {
+    // Keep the synthetic inbound prompt in English for now: it is an
+    // agent-facing intent string rather than user-visible copy, and the final
+    // reply language is still governed by the agent/session prompt stack.
+    // If we later need locale-aware synthetic prompts, this is the single place
+    // to introduce a template or config-based language switch.
+    // Only append the call_id instruction when the invite event actually
+    // carries one. Forcing call_id="" into the prompt would assume every
+    // downstream join tool / CLI shortcut already recognises the parameter —
+    // during rollout that assumption can break auto-join. When absent we keep
+    // the legacy prompt shape so behavior degrades to the pre-call_id path.
+    const callIdInstruction = event.callId
+        ? ` When invoking the join tool, pass call_id="${event.callId}".`
+        : '';
+    const syntheticText = `Use the available tool to join the meeting with meeting number ${event.meetingNo} immediately. Do not ask for confirmation.${callIdInstruction}`;
+    const syntheticMessageId = event.eventId
+        ? `vc-invited:event:${event.eventId}`
+        : `vc-invited:${event.meetingNo}:${event.inviteTime ?? crypto.randomUUID()}`;
+    // VC-invited events have no real chat/thread — they are service-to-service
+    // triggers. Using the inviter's open_id as chatId would cause downstream
+    // senders (reply / card / media) to fire off unsolicited DMs to the inviter
+    // whenever the agent produced any output. Use a synthetic sentinel instead
+    // and let IM-facing deliverers short-circuit on it (see SYNTHETIC_VC_CHAT_ID).
+    return {
+        chatId: synthetic_target_1.SYNTHETIC_VC_CHAT_ID,
+        messageId: syntheticMessageId,
+        senderId: event.senderId,
+        senderName: event.senderName,
+        chatType: synthetic_target_1.SYNTHETIC_VC_CHAT_TYPE,
+        content: syntheticText,
+        contentType: 'text',
+        resources: [],
+        mentions: [],
+        mentionAll: false,
+        rawMessage: {
+            message_id: syntheticMessageId,
+            chat_id: synthetic_target_1.SYNTHETIC_VC_CHAT_ID,
+            chat_type: synthetic_target_1.SYNTHETIC_VC_CHAT_TYPE,
+            message_type: 'text',
+            content: JSON.stringify({ text: syntheticText }),
+            create_time: event.inviteTime ?? String(Date.now()),
+        },
+        rawSender: {
+            sender_id: {
+                ...(event.senderOpenId ? { open_id: event.senderOpenId } : {}),
+                ...(event.senderUserId ? { user_id: event.senderUserId } : {}),
+                ...(event.senderUnionId ? { union_id: event.senderUnionId } : {}),
+            },
+            sender_type: 'user',
+        },
+    };
+}
+function matchesAnySenderId(params) {
+    const candidates = [...new Set(params.senderIds.map((id) => id?.trim()).filter(Boolean))];
+    return candidates.some((candidate) => (0, policy_1.resolveFeishuAllowlistMatch)({
+        allowFrom: params.allowFrom,
+        senderId: candidate,
+    }).allowed);
+}
+async function handleFeishuVcMeetingInvited(params) {
+    const { cfg, event, runtime, chatHistories, accountId } = params;
+    const log = runtime?.log ?? ((...args) => logger.info(args.map(String).join(' ')));
+    const error = runtime?.error ?? ((...args) => logger.error(args.map(String).join(' ')));
+    const syntheticEvent = buildSyntheticEvent(event);
+    if (!syntheticEvent) {
+        log(`feishu[${accountId}]: vc invited event missing meeting_no or inviter identity, skipping`);
+        return;
+    }
+    const account = (0, accounts_1.getLarkAccount)(cfg, accountId);
+    const accountScopedCfg = {
+        ...cfg,
+        channels: { ...cfg.channels, feishu: account.config },
+    };
+    const accountFeishuCfg = account.config;
+    // ---- Access policy enforcement (DM-style) ----
+    // VC invited events are user-triggered service events. Align their access
+    // semantics with direct-message/comment flows so unpaired users cannot
+    // trigger agent behavior through event ingress.
+    const dmPolicy = accountFeishuCfg?.dmPolicy ?? 'pairing';
+    if (dmPolicy === 'disabled') {
+        log(`feishu[${accountId}]: vc invited event rejected (dmPolicy=disabled)`);
+        return;
+    }
+    if (dmPolicy !== 'open') {
+        const configAllowFrom = accountFeishuCfg?.allowFrom ?? [];
+        const storeAllowFrom = await (0, gate_1.readFeishuAllowFromStore)(account.accountId).catch(() => []);
+        const combinedAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+        const allowed = matchesAnySenderId({
+            allowFrom: combinedAllowFrom,
+            senderIds: [
+                syntheticEvent.senderOpenId,
+                syntheticEvent.senderUserId,
+                syntheticEvent.senderUnionId,
+            ],
+        });
+        if (!allowed) {
+            if (dmPolicy === 'pairing') {
+                if (syntheticEvent.senderOpenId) {
+                    log(`feishu[${accountId}]: vc inviter not paired, creating pairing request`);
+                    try {
+                        await (0, gate_effects_1.sendPairingReply)({
+                            senderId: syntheticEvent.senderOpenId,
+                            chatId: syntheticEvent.senderOpenId,
+                            accountId: account.accountId,
+                            accountScopedCfg,
+                        });
+                    }
+                    catch (pairingErr) {
+                        log(`feishu[${accountId}]: failed to create pairing request for vc inviter: ${String(pairingErr)}`);
+                    }
+                }
+                else {
+                    log(`feishu[${accountId}]: vc inviter not paired and has no open_id for pairing reply, rejecting`);
+                }
+            }
+            else {
+                log(`feishu[${accountId}]: vc invited event rejected (dmPolicy=${dmPolicy}, inviter not in allowlist)`);
+            }
+            return;
+        }
+    }
+    const ctx = buildSyntheticContext(syntheticEvent);
+    log(`feishu[${accountId}]: vc meeting invited, dispatching synthetic inbound` +
+        ` sender=${syntheticEvent.senderId} meeting_no=${syntheticEvent.meetingNo}`);
+    try {
+        await (0, dispatch_1.dispatchToAgent)({
+            ctx,
+            permissionError: undefined,
+            mediaPayload: {},
+            extraInboundFields: {
+                SyntheticEventType: syntheticEvent.eventType,
+                VcMeetingId: syntheticEvent.meetingId,
+                VcMeetingNo: syntheticEvent.meetingNo,
+                VcMeetingTopic: syntheticEvent.topic,
+                VcInviterOpenId: syntheticEvent.senderOpenId,
+                VcInviteTime: syntheticEvent.inviteTime,
+                VcCallId: syntheticEvent.callId,
+            },
+            quotedContent: undefined,
+            account,
+            accountScopedCfg,
+            runtime,
+            chatHistories,
+            historyLimit: 0,
+            // VC events do not originate from a real IM message.
+            replyToMessageId: undefined,
+            commandAuthorized: false,
+            skipTyping: true,
+        });
+    }
+    catch (err) {
+        error(`feishu[${accountId}]: error dispatching vc invited synthetic inbound: ${String(err)}`);
+    }
+}

package/src/messaging/inbound/vc-sender.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared sender-identity resolution for the VC meeting-invited event.
+ *
+ * Both the raw event handler (for diagnostics / dedup / ownership check)
+ * and the synthetic inbound builder (for dispatchToAgent) need a single,
+ * deterministic fallback chain. Keeping a dedicated module avoids drift
+ * between the two code paths when the event schema changes again.
+ */
+import type { FeishuVcMeetingInvitedEvent } from '../types';
+/** Which bucket the final senderId was picked from. */
+export type VcSenderFallback = 'inviter' | 'none';
+export interface ResolvedVcSender {
+    /**
+     * Final sender id used for logging / extraInboundFields. Sender is defined
+     * as the real inviter only; if inviter identity is missing, the event
+     * should be skipped instead of degrading to bot/config ids.
+     */
+    senderId: string;
+    /** Raw inviter-level open_id (if present); useful for agent "at inviter" use-cases. */
+    senderOpenId?: string;
+    /** Raw inviter-level user_id (if present). */
+    senderUserId?: string;
+    /** Raw inviter-level union_id (if present). */
+    senderUnionId?: string;
+    /** Human-readable name from inviter.user_name. */
+    senderName?: string;
+    /** Which bucket the senderId fell back to. */
+    fromFallback: VcSenderFallback;
+}
+/**
+ * Resolve the effective sender identity for a `vc.bot.meeting_invited_v1`
+ * event. See {@link ResolvedVcSender} for the field contract.
+ *
+ * Sender resolution order (first non-empty wins):
+ *   1. inviter.id.open_id → user_id → union_id
+ *   2. empty string + fromFallback='none'
+ */
+export declare function resolveVcSender(event: FeishuVcMeetingInvitedEvent): ResolvedVcSender;

package/src/messaging/inbound/vc-sender.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared sender-identity resolution for the VC meeting-invited event.
+ *
+ * Both the raw event handler (for diagnostics / dedup / ownership check)
+ * and the synthetic inbound builder (for dispatchToAgent) need a single,
+ * deterministic fallback chain. Keeping a dedicated module avoids drift
+ * between the two code paths when the event schema changes again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVcSender = resolveVcSender;
+/**
+ * Trim a possibly-null identifier and treat the empty string as missing.
+ *
+ * The event schema marks open_id / user_id / union_id as nullable and we
+ * have observed tenants returning empty strings in practice, so `||`/`??`
+ * alone are not enough.
+ */
+function pickId(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Resolve the effective sender identity for a `vc.bot.meeting_invited_v1`
+ * event. See {@link ResolvedVcSender} for the field contract.
+ *
+ * Sender resolution order (first non-empty wins):
+ *   1. inviter.id.open_id → user_id → union_id
+ *   2. empty string + fromFallback='none'
+ */
+function resolveVcSender(event) {
+    const inviterId = event.inviter?.id;
+    const inviterOpenId = pickId(inviterId?.open_id);
+    const inviterUserId = pickId(inviterId?.user_id);
+    const inviterUnionId = pickId(inviterId?.union_id);
+    let senderId = '';
+    let fromFallback = 'none';
+    if (inviterOpenId ?? inviterUserId ?? inviterUnionId) {
+        senderId = inviterOpenId ?? inviterUserId ?? inviterUnionId ?? '';
+        fromFallback = 'inviter';
+    }
+    return {
+        senderId,
+        senderOpenId: inviterOpenId,
+        senderUserId: inviterUserId,
+        senderUnionId: inviterUnionId,
+        senderName: pickId(event.inviter?.user_name) ?? undefined,
+        fromFallback,
+    };
+}

package/src/messaging/outbound/actions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ChannelMessageActionAdapter for the Lark/Feishu channel plugin.
+ *
+ * Implements the standard message-action interface so the framework's
+ * built-in `message` tool can route send, react, delete and other
+ * actions to Feishu.
+ *
+ * The `send` action is the unified entry-point for text, card, media,
+ * reply and attachment delivery — matching the Telegram/Discord pattern
+ * where a single action handles all outbound message types.
+ */
+import type { ChannelMessageActionAdapter } from 'openclaw/plugin-sdk';
+export declare const feishuMessageActions: ChannelMessageActionAdapter;