@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/outbound/normalize-mentions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Outbound mention normalizer for Feishu post messages. Rewrites <at>
+ * tag variants and resolves "@Name" to the canonical
+ * <at user_id="ou_xxx">Name</at> form expected by the Feishu API.
+ */
+import type { LarkAccount } from '../../core/types';
+import type { PrincipalKind } from '../inbound/user-name-cache-store';
+/**
+ * Rewrites <at> tag attribute and quote variants to the canonical
+ * `<at user_id="ou_xxx">` form. Idempotent; pure string transform.
+ *
+ * Recognized variants: `id=`, `open_id=`, `user_id=`; double-quoted,
+ * single-quoted, or unquoted; `id=all` aligned to `user_id="all"` with
+ * "Everyone" name fill. `<person>` picker tags are left untouched.
+ */
+export declare function normalizeOutboundMentionsTagPass(text: string): string;
+export type LogFn = (...args: unknown[]) => void;
+export interface NormalizeContext {
+    /** Chat where the message will be sent; keys lazy chat-member fetches. */
+    chatId: string;
+    account: LarkAccount;
+    /** Optional sink for prefetch errors during normalization. */
+    log?: LogFn;
+}
+export interface SentinelEntry {
+    name: string;
+    reason: 'not_found' | 'ambiguous';
+    candidates?: Array<{
+        openId: string;
+        kind?: PrincipalKind;
+    }>;
+}
+export interface NormalizeResult {
+    normalizedText: string;
+    sentinels: SentinelEntry[];
+}
+/**
+ * Normalizes outbound text for Feishu: rewrites <at> tag variants and
+ * resolves plain "@Name" against the per-account name cache.
+ *
+ * On cache miss, fetches the chat's bot list and retries; if still
+ * unresolved, fetches the chat's member list and retries. Names that
+ * match multiple cache entries become ambiguous sentinels for next-turn
+ * disambiguation; remaining misses are dropped without a sentinel to
+ * avoid false positives on `@` followed by non-name CJK runs.
+ */
+export declare function normalizeOutboundMentions(text: string, ctx: NormalizeContext): Promise<NormalizeResult>;

package/src/messaging/outbound/normalize-mentions.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Outbound mention normalizer for Feishu post messages. Rewrites <at>
+ * tag variants and resolves "@Name" to the canonical
+ * <at user_id="ou_xxx">Name</at> form expected by the Feishu API.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOutboundMentionsTagPass = normalizeOutboundMentionsTagPass;
+exports.normalizeOutboundMentions = normalizeOutboundMentions;
+const user_name_cache_1 = require("../inbound/user-name-cache.js");
+/**
+ * Rewrites <at> tag attribute and quote variants to the canonical
+ * `<at user_id="ou_xxx">` form. Idempotent; pure string transform.
+ *
+ * Recognized variants: `id=`, `open_id=`, `user_id=`; double-quoted,
+ * single-quoted, or unquoted; `id=all` aligned to `user_id="all"` with
+ * "Everyone" name fill. `<person>` picker tags are left untouched.
+ */
+function normalizeOutboundMentionsTagPass(text) {
+    let out = text;
+    // <at id=all|user_id="all"|...></at> → <at user_id="all">Everyone</at>.
+    // Match an explicit closing tag so already-canonical input stays
+    // idempotent: a bare opening tag would match the optional-close form
+    // and corrupt the trailing "Everyone</at>" into a double close.
+    out = out.replace(/<at\s+(?:id|user_id|open_id)\s*=\s*["']?all["']?\s*>\s*<\/at>/gi, '<at user_id="all">Everyone</at>');
+    // Generic <at attr=ou_xxx> → <at user_id="ou_xxx">.
+    out = out.replace(/<at\s+(?:id|open_id|user_id)\s*=\s*["']?(ou_[A-Za-z0-9_-]+)["']?\s*>/gi, '<at user_id="$1">');
+    return out;
+}
+const noopLog = () => { };
+/** Spans excluded from the @Name scan: code, canonical tags, emails, URLs. */
+const MASK_PATTERNS = [
+    /```[\s\S]*?```/g,
+    /`[^`\n]*`/g,
+    /<at\s+user_id="[^"]+">[^<]*<\/at>/g,
+    /<person\s+[^>]*>[^<]*<\/person>/g,
+    /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+    /\b(?:https?|ftp|mailto):\/\/[^\s)\]<>]+/g,
+];
+// CJK range U+4E00–U+9FA5 covers ideographs so multibyte names match.
+const CANDIDATE_RE = /@([A-Za-z0-9\u4e00-\u9fa5_]+(?:[.-][A-Za-z0-9\u4e00-\u9fa5_]+)*)/g;
+const FALLBACK_PREFETCHES = [user_name_cache_1.prefetchChatBots, user_name_cache_1.prefetchChatMembers];
+/**
+ * Normalizes outbound text for Feishu: rewrites <at> tag variants and
+ * resolves plain "@Name" against the per-account name cache.
+ *
+ * On cache miss, fetches the chat's bot list and retries; if still
+ * unresolved, fetches the chat's member list and retries. Names that
+ * match multiple cache entries become ambiguous sentinels for next-turn
+ * disambiguation; remaining misses are dropped without a sentinel to
+ * avoid false positives on `@` followed by non-name CJK runs.
+ */
+async function normalizeOutboundMentions(text, ctx) {
+    let out = normalizeOutboundMentionsTagPass(text);
+    // Drop redundant `@` immediately preceding a canonical <at> tag.
+    out = out.replace(/@(<at\s+user_id="ou_[A-Za-z0-9_-]+">[^<]*<\/at>)/g, '$1');
+    const inMask = buildMaskPredicate(out);
+    const sentinels = [];
+    const replacements = [];
+    // First sweep: resolve from cache; defer misses for lazy fetch.
+    let pending = [];
+    for (const m of out.matchAll(CANDIDATE_RE)) {
+        const start = m.index;
+        if (inMask(start))
+            continue;
+        const end = start + m[0].length;
+        const r = resolveCandidate(m[1], ctx);
+        if (r.kind === 'resolved') {
+            replacements.push(makeReplacement(start, end, r));
+        }
+        else if (r.entry.reason === 'ambiguous') {
+            sentinels.push(r.entry);
+        }
+        else {
+            pending.push({ start, end, name: m[1] });
+        }
+    }
+    // Retry through each fallback in turn; remaining misses are dropped.
+    for (const prefetch of FALLBACK_PREFETCHES) {
+        if (pending.length === 0)
+            break;
+        pending = await retryWithPrefetch(pending, prefetch, ctx, replacements, sentinels);
+    }
+    return { normalizedText: applyReplacements(out, replacements), sentinels };
+}
+function buildMaskPredicate(text) {
+    const masks = [];
+    for (const re of MASK_PATTERNS) {
+        for (const m of text.matchAll(re)) {
+            masks.push([m.index, m.index + m[0].length]);
+        }
+    }
+    return (idx) => masks.some(([s, e]) => idx >= s && idx < e);
+}
+function makeReplacement(start, end, r) {
+    return { start, end, text: `<at user_id="${r.openId}">${r.displayName}</at>` };
+}
+async function retryWithPrefetch(pending, prefetch, ctx, replacements, sentinels) {
+    await prefetch(ctx.account, ctx.chatId, ctx.log ?? noopLog);
+    const stillMissing = [];
+    for (const p of pending) {
+        const r = resolveCandidate(p.name, ctx);
+        if (r.kind === 'resolved') {
+            replacements.push(makeReplacement(p.start, p.end, r));
+        }
+        else if (r.entry.reason === 'ambiguous') {
+            sentinels.push(r.entry);
+        }
+        else {
+            stillMissing.push(p);
+        }
+    }
+    return stillMissing;
+}
+/**
+ * Applies non-overlapping replacements in a single left-to-right pass.
+ * Builds an array of literal chunks then joins it once — O(n + total
+ * replacement length), no string-concat quadratic behavior.
+ */
+function applyReplacements(text, replacements) {
+    if (replacements.length === 0)
+        return text;
+    const sorted = [...replacements].sort((a, b) => a.start - b.start);
+    const out = [];
+    let cursor = 0;
+    for (const r of sorted) {
+        if (r.start < cursor)
+            continue; // drop overlapping replacements defensively
+        out.push(text.slice(cursor, r.start), r.text);
+        cursor = r.end;
+    }
+    out.push(text.slice(cursor));
+    return out.join('');
+}
+/**
+ * Aliases for "mention everyone" that may appear as plain text instead
+ * of the canonical `<at user_id="all">` tag. Match is case-insensitive.
+ */
+const ALL_ALIASES = new Set(['all', 'everyone', '所有人']);
+function resolveCandidate(name, ctx) {
+    // Literal @-everyone aliases map to the canonical Feishu @all tag,
+    // bypassing the per-account name cache. The display name "Everyone"
+    // matches what the tag-level normalizer fills in for empty <at> bodies.
+    if (ALL_ALIASES.has(name.toLowerCase())) {
+        return { kind: 'resolved', openId: 'all', displayName: 'Everyone' };
+    }
+    const cache = (0, user_name_cache_1.getUserNameCache)(ctx.account.accountId);
+    const matches = cache.lookupByName(name);
+    if (matches.length === 1) {
+        return { kind: 'resolved', openId: matches[0].openId, displayName: matches[0].name };
+    }
+    if (matches.length > 1) {
+        return {
+            kind: 'sentinel',
+            entry: {
+                name,
+                reason: 'ambiguous',
+                candidates: matches.map((m) => ({ openId: m.openId, kind: m.kind })),
+            },
+        };
+    }
+    return { kind: 'sentinel', entry: { name, reason: 'not_found' } };
+}

package/src/messaging/outbound/outbound-mention.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Outbound mention normalization + bot-peer @-mention enforcement.
+ *
+ * Why this exists: in Feishu groups, a bot only receives a message when
+ * something explicitly @-mentions its open_id with a structured `<at>`
+ * element. LLM outputs come in many "natural" @-shapes (markdown, angle
+ * brackets, template syntax) but none of them satisfy the delivery rule —
+ * only `<at user_id="ou_xxx">Name</at>` does. This module:
+ *
+ *   1. `normalizeOutboundMentions` — rewrites the six common LLM shapes
+ *      into the standard `<at>` element when the name resolves via the
+ *      per-chat mention-registry. Unknown names are left as plain text
+ *      (a recipient who's never spoken in this chat can't be @-mentioned).
+ *
+ *   2. `ensureMention` — in bot→bot group scenarios, the agent reply must
+ *      include an explicit @ of the peer bot or the peer never receives
+ *      it. When the LLM forgets to add one, prepend it as a safety net.
+ *
+ * Both are idempotent: existing standard `<at>` elements are preserved,
+ * and `ensureMention` is a no-op when the peer is already mentioned.
+ */
+/**
+ * Rewrite LLM-emitted mention shapes into the standard `<at user_id="…">`
+ * element used by Feishu for guaranteed delivery. Unknown names — those
+ * whose display name isn't in the per-chat registry — are left intact as
+ * plain text so the agent's wording survives even when delivery cannot
+ * fire.
+ */
+export declare function normalizeOutboundMentions(text: string, chatId: string): string;
+/**
+ * Ensure the reply explicitly @-mentions the given peer.
+ *
+ * Designed for bot↔bot group flows: when the peer is another bot, Feishu
+ * won't deliver the message unless an `<at user_id="ou_peer">` element is
+ * present somewhere in the text. If the LLM already mentioned the peer,
+ * no-op; otherwise, prepend a standard `<at>` so the peer wakes up.
+ */
+export declare function ensureMention(text: string, peerOpenId: string, peerName: string): string;

package/src/messaging/outbound/outbound-mention.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Outbound mention normalization + bot-peer @-mention enforcement.
+ *
+ * Why this exists: in Feishu groups, a bot only receives a message when
+ * something explicitly @-mentions its open_id with a structured `<at>`
+ * element. LLM outputs come in many "natural" @-shapes (markdown, angle
+ * brackets, template syntax) but none of them satisfy the delivery rule —
+ * only `<at user_id="ou_xxx">Name</at>` does. This module:
+ *
+ *   1. `normalizeOutboundMentions` — rewrites the six common LLM shapes
+ *      into the standard `<at>` element when the name resolves via the
+ *      per-chat mention-registry. Unknown names are left as plain text
+ *      (a recipient who's never spoken in this chat can't be @-mentioned).
+ *
+ *   2. `ensureMention` — in bot→bot group scenarios, the agent reply must
+ *      include an explicit @ of the peer bot or the peer never receives
+ *      it. When the LLM forgets to add one, prepend it as a safety net.
+ *
+ * Both are idempotent: existing standard `<at>` elements are preserved,
+ * and `ensureMention` is a no-op when the peer is already mentioned.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOutboundMentions = normalizeOutboundMentions;
+exports.ensureMention = ensureMention;
+const mention_registry_1 = require("../inbound/mention-registry.js");
+const STANDARD_AT_RE = /<at\s+user_id="[^"]*">[^<]*<\/at>/g;
+// LLM-produced mention shapes (in priority order — first match wins).
+// Each pattern captures the display name; the runner consults the registry
+// for an openId before rewriting, and leaves the original text untouched
+// when the name doesn't resolve.
+//
+// Plain `@Name` is intentionally last because the more decorated variants
+// embed an `@` and we want them to claim ownership of their match first.
+const VARIANT_PATTERNS = [
+    { re: /@\[([^\]\n]+)\]/g, group: 1 }, // @[Name]
+    { re: /@<([^>\n]+)>/g, group: 1 }, // @<Name>
+    { re: /<@([^>\n]+)>/g, group: 1 }, // <@Name>
+    { re: /<at>\s*([^<\n]+?)\s*<\/at>/g, group: 1 }, // <at>Name</at>
+    { re: /\{\{\s*([^}\n]+?)\s*\}\}/g, group: 1 }, // {{Name}}
+    // Plain @Name — single token, ASCII/CJK/digit/underscore. Won't match
+    // mid-word (preceded by a word char), so email addresses are safe.
+    { re: /(^|[^\w@])@([A-Za-z0-9_一-鿿][\w.一-鿿-]{0,30})/g, group: 2 },
+];
+/**
+ * Rewrite LLM-emitted mention shapes into the standard `<at user_id="…">`
+ * element used by Feishu for guaranteed delivery. Unknown names — those
+ * whose display name isn't in the per-chat registry — are left intact as
+ * plain text so the agent's wording survives even when delivery cannot
+ * fire.
+ */
+function normalizeOutboundMentions(text, chatId) {
+    if (!text || !chatId)
+        return text;
+    // Step 1: mask out already-standard <at> elements so the variant patterns
+    //         below never re-match them.
+    const protectedTokens = [];
+    let masked = text.replace(STANDARD_AT_RE, (m) => {
+        const idx = protectedTokens.push(m) - 1;
+        return `\x00P${idx}\x00`;
+    });
+    // Step 2: apply variant patterns in declared priority.
+    for (const { re, group } of VARIANT_PATTERNS) {
+        masked = masked.replace(re, (...args) => {
+            const match = args[0];
+            const groups = args.slice(1, args.length - 2);
+            const name = (groups[group - 1] ?? '').trim();
+            if (!name)
+                return match;
+            const openId = (0, mention_registry_1.lookupByName)(chatId, name);
+            if (!openId)
+                return match;
+            const standardAt = `<at user_id="${openId}">${name}</at>`;
+            // For the plain-@Name pattern we captured a leading word boundary in
+            // group 1 — preserve it. Other patterns matched the @-shape exactly.
+            if (group === 2) {
+                const leading = groups[0] ?? '';
+                return `${leading}${standardAt}`;
+            }
+            return standardAt;
+        });
+    }
+    // Step 3: restore protected tokens. The \x00 sentinels are intentional
+    // private-use markers that never appear in real Feishu text.
+    // eslint-disable-next-line no-control-regex
+    return masked.replace(/\x00P(\d+)\x00/g, (_, idx) => protectedTokens[Number(idx)]);
+}
+/**
+ * Ensure the reply explicitly @-mentions the given peer.
+ *
+ * Designed for bot↔bot group flows: when the peer is another bot, Feishu
+ * won't deliver the message unless an `<at user_id="ou_peer">` element is
+ * present somewhere in the text. If the LLM already mentioned the peer,
+ * no-op; otherwise, prepend a standard `<at>` so the peer wakes up.
+ */
+function ensureMention(text, peerOpenId, peerName) {
+    if (!peerOpenId)
+        return text;
+    // Already-mentioned check — match any existing <at user_id="ou_peer">
+    // element regardless of the rendered name to preserve idempotency.
+    const escaped = peerOpenId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const existingRe = new RegExp(`<at\\s+user_id="${escaped}">[^<]*<\\/at>`);
+    if (existingRe.test(text))
+        return text;
+    const standardAt = `<at user_id="${peerOpenId}">${peerName || peerOpenId}</at>`;
+    if (!text || !text.trim())
+        return standardAt;
+    return `${standardAt} ${text}`;
+}

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

@@ -0,0 +1,79 @@
+import type { ChannelOutboundAdapter } from 'openclaw/plugin-sdk/channel-send-result';
+/**
+ * Channel-specific payload for Feishu, carried in `ReplyPayload.channelData.feishu`.
+ *
+ * Callers (skills, tools, programmatic code) populate this structure to send
+ * Feishu-native content that the standard text/media path cannot express.
+ *
+ * Both card v1 (Message Card) and v2 (CardKit) formats are supported.
+ * The Feishu server distinguishes the version by the presence of `schema: "2.0"`.
+ *
+ * @example
+ * ```ts
+ * // --- v1 Message Card (default) ---
+ * const v1Reply: ReplyPayload = {
+ *   channelData: {
+ *     feishu: {
+ *       card: {
+ *         config: { wide_screen_mode: true },
+ *         header: {
+ *           title: { tag: "plain_text", content: "Task Created" },
+ *           template: "green",
+ *         },
+ *         elements: [
+ *           { tag: "div", text: { tag: "lark_md", content: "**Title:** Fix login bug" } },
+ *           { tag: "action", actions: [
+ *             { tag: "button", text: { tag: "plain_text", content: "View" }, type: "primary", url: "https://..." },
+ *           ]},
+ *         ],
+ *       },
+ *     },
+ *   },
+ * };
+ *
+ * // --- v2 CardKit ---
+ * const v2Reply: ReplyPayload = {
+ *   channelData: {
+ *     feishu: {
+ *       card: {
+ *         schema: "2.0",
+ *         config: { wide_screen_mode: true },
+ *         header: {
+ *           title: { tag: "plain_text", content: "Task Created" },
+ *           template: "green",
+ *         },
+ *         body: {
+ *           elements: [
+ *             { tag: "markdown", content: "**Title:** Fix login bug" },
+ *           ],
+ *         },
+ *       },
+ *     },
+ *   },
+ * };
+ * ```
+ */
+export interface FeishuChannelData {
+    /**
+     * A complete Feishu interactive card JSON object (v1 or v2).
+     *
+     * The card is sent as-is via `msg_type: "interactive"`. The Feishu server
+     * uses the presence of `schema: "2.0"` to determine the card version.
+     *
+     * **v1 (Message Card)** — default when no `schema` field is present.
+     * Top-level fields: `config`, `header`, `elements`.
+     * Element tags: `div`, `action`, `button`, `button_group`, `note`,
+     * `img`, `hr`, `column_set`, `markdown` (limited), `lark_md` (in div.text).
+     *
+     * **v2 (CardKit)** — activated by `schema: "2.0"`.
+     * Top-level fields: `schema`, `config`, `header`, `body.elements`.
+     * Element tags: `markdown`, `plain_text`, `hr`, `collapsible_panel`,
+     * `column_set`, `table`, `image`, `button`, `select_static`, `overflow`.
+     * Not supported in v2: `action`, `button_group`, `note`, `div` + `lark_md`.
+     *
+     * @see https://open.larkoffice.com/document/feishu-cards/card-json-v2-structure (v2)
+     * @see https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components (v1)
+     */
+    card?: Record<string, unknown>;
+}
+export declare const feishuOutbound: ChannelOutboundAdapter;

package/src/messaging/outbound/outbound.js

@@ -0,0 +1,195 @@
+"use strict";
+// SPDX-License-Identifier: MIT
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.feishuOutbound = void 0;
+const lark_client_1 = require("../../core/lark-client.js");
+const lark_logger_1 = require("../../core/lark-logger.js");
+const targets_1 = require("../../core/targets.js");
+const comment_target_1 = require("../../core/comment-target.js");
+const synthetic_target_1 = require("../../core/synthetic-target.js");
+const deliver_1 = require("./deliver.js");
+const outbound_mention_1 = require("./outbound-mention.js");
+const bot_peer_context_1 = require("./bot-peer-context.js");
+/**
+ * Apply the outbound mention safety net for the current send:
+ *  - rewrite LLM-emitted @-shapes into Feishu's standard <at> element
+ *  - when the dispatch layer marked the current reply as bot→bot in a
+ *    group (via `runWithBotPeerContext`), guarantee the peer bot is
+ *    explicitly @-mentioned so Feishu delivers the message at all.
+ */
+function applyOutboundMentions(text, chatId) {
+    const normalized = (0, outbound_mention_1.normalizeOutboundMentions)(text, chatId);
+    const peer = (0, bot_peer_context_1.currentBotPeerContext)();
+    // De-dupe the peer @ across chunks: once it has appeared on one chunk
+    // (model-written or injected), later chunks of the same dispatch skip it.
+    // Mirrors normalizeFeishuOutboundText in send.ts so both outbound paths
+    // behave the same and a long multi-chunk reply doesn't @ the peer repeatedly.
+    if (!peer || peer.mentioned)
+        return normalized;
+    const out = (0, outbound_mention_1.ensureMention)(normalized, peer.peerOpenId, peer.peerName);
+    if (out.includes(`user_id="${peer.peerOpenId}"`)) {
+        peer.mentioned = true;
+    }
+    return out;
+}
+const log = (0, lark_logger_1.larkLogger)('outbound/outbound');
+/**
+ * Map adapter-level parameters to internal send context.
+ *
+ * Mirrors the pattern used by Telegram (`resolveTelegramSendContext`) and
+ * Slack (`sendSlackOutboundMessage`) to centralise parameter mapping.
+ */
+function resolveFeishuSendContext(params) {
+    const routeTarget = (0, targets_1.parseFeishuRouteTarget)(params.to);
+    const explicitThreadId = params.threadId != null && String(params.threadId).trim() !== '' ? String(params.threadId).trim() : undefined;
+    const explicitReplyToId = params.replyToId?.trim() || undefined;
+    const replyToMessageId = explicitReplyToId ?? routeTarget.replyToMessageId;
+    const replyInThread = Boolean(explicitThreadId ?? routeTarget.threadId);
+    if (!explicitReplyToId && routeTarget.replyToMessageId) {
+        log.info('resolved reply target from encoded originating route');
+    }
+    return {
+        cfg: params.cfg,
+        to: routeTarget.target,
+        replyToMessageId,
+        replyInThread,
+        threadId: explicitThreadId,
+        accountId: params.accountId ?? undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+exports.feishuOutbound = {
+    deliveryMode: 'direct',
+    chunker: (text, limit) => lark_client_1.LarkClient.runtime.channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: 'markdown',
+    textChunkLimit: 15000,
+    sendText: async ({ cfg, to, text, accountId, replyToId, threadId }) => {
+        log.info(`sendText: target=${to}, textLength=${text.length}`);
+        // Synthetic targets (e.g. VC meeting-invited) have no real IM peer —
+        // drop the send silently so the agent pipeline stays uniform without
+        // producing unsolicited DMs. See core/synthetic-target.ts.
+        if ((0, synthetic_target_1.isSyntheticTarget)(to)) {
+            log.debug(`sendText: synthetic target ${to}, dropping outbound IM send`);
+            return { channel: 'feishu', messageId: '', chatId: to };
+        }
+        // Comment thread routing — route replies through Drive comment API
+        if ((0, comment_target_1.isCommentTarget)(to)) {
+            log.info(`sendText: detected comment target, routing through Drive comment API`);
+            const result = await (0, deliver_1.sendCommentReplyLark)({ cfg, to, text, accountId: accountId ?? undefined });
+            return { channel: 'feishu', ...result };
+        }
+        const ctx = resolveFeishuSendContext({ cfg, to, accountId, replyToId, threadId });
+        const finalText = applyOutboundMentions(text, ctx.to);
+        const result = await (0, deliver_1.sendTextLark)({ ...ctx, to: ctx.to, text: finalText });
+        return { channel: 'feishu', ...result };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots, accountId, replyToId, threadId }) => {
+        log.info(`sendMedia: target=${to}, ` + `hasText=${Boolean(text?.trim())}, mediaUrl=${mediaUrl ?? '(none)'}`);
+        // Synthetic targets — drop silently (see sendText for rationale).
+        if ((0, synthetic_target_1.isSyntheticTarget)(to)) {
+            log.debug(`sendMedia: synthetic target ${to}, dropping outbound IM send`);
+            return { channel: 'feishu', messageId: '', chatId: to };
+        }
+        // Comment thread routing — send text (with media URL appended) via Drive comment API
+        if ((0, comment_target_1.isCommentTarget)(to)) {
+            log.info(`sendMedia: detected comment target, routing through Drive comment API`);
+            const parts = [];
+            if (text?.trim())
+                parts.push(text.trim());
+            if (mediaUrl)
+                parts.push(`📎 ${mediaUrl}`);
+            const combinedText = parts.join('\n') || '(media)';
+            const result = await (0, deliver_1.sendCommentReplyLark)({ cfg, to, text: combinedText, accountId: accountId ?? undefined });
+            return { channel: 'feishu', ...result };
+        }
+        const ctx = resolveFeishuSendContext({ cfg, to, accountId, replyToId, threadId });
+        const normalizedCaption = text ? applyOutboundMentions(text, ctx.to) : text;
+        // Feishu media messages do not support inline captions — send text first.
+        // Capture the result so the no-mediaUrl path can return it without re-sending.
+        let captionResult;
+        if (normalizedCaption?.trim()) {
+            captionResult = await (0, deliver_1.sendTextLark)({ ...ctx, to: ctx.to, text: normalizedCaption });
+        }
+        // No mediaUrl — text-only flow.
+        if (!mediaUrl) {
+            log.info('sendMedia: no mediaUrl provided, falling back to text-only');
+            if (captionResult) {
+                // Caption was already sent above; return that result.
+                return { channel: 'feishu', ...captionResult };
+            }
+            // No caption text — send empty/raw text to satisfy the contract.
+            const result = await (0, deliver_1.sendTextLark)({ ...ctx, to: ctx.to, text: normalizedCaption ?? '' });
+            return { channel: 'feishu', ...result };
+        }
+        const result = await (0, deliver_1.sendMediaLark)({ ...ctx, to: ctx.to, mediaUrl, mediaLocalRoots });
+        return {
+            channel: 'feishu',
+            messageId: result.messageId,
+            chatId: result.chatId,
+            ...(result.warning ? { meta: { warnings: [result.warning] } } : {}),
+        };
+    },
+    sendPayload: async ({ cfg, to, payload, mediaLocalRoots, accountId, replyToId, threadId }) => {
+        // Synthetic targets — drop silently (see sendText for rationale).
+        if ((0, synthetic_target_1.isSyntheticTarget)(to)) {
+            log.debug(`sendPayload: synthetic target ${to}, dropping outbound IM send`);
+            return { channel: 'feishu', messageId: '', chatId: to };
+        }
+        const ctx = resolveFeishuSendContext({ cfg, to, accountId, replyToId, threadId });
+        // --- channelData.feishu: card message support ---
+        const feishuData = payload.channelData?.feishu;
+        // --- Resolve text + media from payload ---
+        const text = payload.text ?? '';
+        const mediaUrls = payload.mediaUrls?.length ? payload.mediaUrls : payload.mediaUrl ? [payload.mediaUrl] : [];
+        log.info(`sendPayload: target=${to}, ` +
+            `textLength=${text.length}, mediaCount=${mediaUrls.length}, ` +
+            `hasCard=${Boolean(feishuData?.card)}`);
+        // --- channelData.feishu.card: card message path ---
+        // Feishu card messages are standalone (msg_type="interactive"), so
+        // text and media must be sent as separate messages around the card.
+        if (feishuData?.card) {
+            if (text.trim()) {
+                await (0, deliver_1.sendTextLark)({ ...ctx, to: ctx.to, text });
+            }
+            const cardResult = await (0, deliver_1.sendCardLark)({ ...ctx, to: ctx.to, card: feishuData.card });
+            const warnings = [];
+            for (const mediaUrl of mediaUrls) {
+                const mediaResult = await (0, deliver_1.sendMediaLark)({ ...ctx, to: ctx.to, mediaUrl, mediaLocalRoots });
+                if (mediaResult.warning) {
+                    warnings.push(mediaResult.warning);
+                }
+            }
+            return {
+                channel: 'feishu',
+                messageId: cardResult.messageId,
+                chatId: cardResult.chatId,
+                ...(warnings.length > 0 ? { meta: { warnings } } : {}),
+            };
+        }
+        // --- Standard text + media orchestration (no card) ---
+        // No media: text-only
+        if (mediaUrls.length === 0) {
+            const result = await (0, deliver_1.sendTextLark)({ ...ctx, to: ctx.to, text });
+            return { channel: 'feishu', ...result };
+        }
+        // Has media: send leading text, then loop media URLs
+        if (text.trim()) {
+            await (0, deliver_1.sendTextLark)({ ...ctx, to: ctx.to, text });
+        }
+        const warnings = [];
+        let lastResult;
+        for (const mediaUrl of mediaUrls) {
+            lastResult = await (0, deliver_1.sendMediaLark)({ ...ctx, to: ctx.to, mediaUrl, mediaLocalRoots });
+            if (lastResult.warning) {
+                warnings.push(lastResult.warning);
+            }
+        }
+        return {
+            channel: 'feishu',
+            ...(lastResult ?? { messageId: '', chatId: '' }),
+            ...(warnings.length > 0 ? { meta: { warnings } } : {}),
+        };
+    },
+};