@larksuite/openclaw-lark 2025.7.15-beta.0

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

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * FIFO-based message deduplication.
+ *
+ * Feishu WebSocket connections may redeliver messages on reconnect.
+ * This module tracks recently-seen message IDs and filters duplicates.
+ *
+ * Design choices:
+ * - FIFO eviction (not LRU) — message IDs are write-once/check-once,
+ *   no hot/cold access pattern.  FIFO naturally expires the oldest entry
+ *   first, which matches the dedup semantics.
+ * - ES2015 `Map` preserves insertion order, giving us FIFO for free.
+ * - Periodic sweep leverages FIFO ordering: iterate from oldest and
+ *   `break` at the first non-expired entry → O(expired), not O(n).
+ */
+export interface MessageDedupOpts {
+    /** Time-to-live for each entry in milliseconds (default: 5 min). */
+    ttlMs?: number;
+    /** Maximum number of tracked entries (default: 10 000). */
+    maxEntries?: number;
+}
+/**
+ * Check whether a message is too old to process.
+ *
+ * Feishu message `create_time` is a millisecond Unix timestamp encoded
+ * as a string.  When a WebSocket reconnects after a long outage, stale
+ * messages may be redelivered — this function lets callers discard them
+ * before entering the full handling pipeline.
+ */
+export declare function isMessageExpired(createTimeStr: string | undefined, expiryMs?: number): boolean;
+export declare class MessageDedup {
+    private readonly store;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly sweepTimer;
+    constructor(opts?: MessageDedupOpts);
+    /**
+     * Try to record a message ID.
+     *
+     * @param id   Unique message identifier (e.g. Feishu `message_id`).
+     * @param scope Optional scope prefix (e.g. accountId) to namespace IDs.
+     * @returns `true` if the message is **new**; `false` if it is a duplicate.
+     */
+    tryRecord(id: string, scope?: string): boolean;
+    /** Current number of tracked entries (for diagnostics). */
+    get size(): number;
+    /** Remove all entries and stop the periodic sweep. */
+    clear(): void;
+    /** Stop the periodic sweep timer and clear all tracked entries. */
+    dispose(): void;
+    /**
+     * Sweep expired entries from the front of the map.
+     * Because entries are in insertion order (FIFO), we can stop as soon as
+     * we hit one that hasn't expired yet.
+     */
+    private sweep;
+}

package/src/messaging/inbound/dedup.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * FIFO-based message deduplication.
+ *
+ * Feishu WebSocket connections may redeliver messages on reconnect.
+ * This module tracks recently-seen message IDs and filters duplicates.
+ *
+ * Design choices:
+ * - FIFO eviction (not LRU) — message IDs are write-once/check-once,
+ *   no hot/cold access pattern.  FIFO naturally expires the oldest entry
+ *   first, which matches the dedup semantics.
+ * - ES2015 `Map` preserves insertion order, giving us FIFO for free.
+ * - Periodic sweep leverages FIFO ordering: iterate from oldest and
+ *   `break` at the first non-expired entry → O(expired), not O(n).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageDedup = void 0;
+exports.isMessageExpired = isMessageExpired;
+const DEFAULT_TTL_MS = 12 * 60 * 60 * 1000; // 12 hours
+const DEFAULT_MAX_ENTRIES = 5_000;
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+// ---------------------------------------------------------------------------
+// Message expiry check
+// ---------------------------------------------------------------------------
+const DEFAULT_EXPIRY_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * Check whether a message is too old to process.
+ *
+ * Feishu message `create_time` is a millisecond Unix timestamp encoded
+ * as a string.  When a WebSocket reconnects after a long outage, stale
+ * messages may be redelivered — this function lets callers discard them
+ * before entering the full handling pipeline.
+ */
+function isMessageExpired(createTimeStr, expiryMs = DEFAULT_EXPIRY_MS) {
+    if (!createTimeStr)
+        return false;
+    const createTime = parseInt(createTimeStr, 10);
+    if (Number.isNaN(createTime))
+        return false;
+    return Date.now() - createTime > expiryMs;
+}
+// ---------------------------------------------------------------------------
+// Message deduplication
+// ---------------------------------------------------------------------------
+class MessageDedup {
+    store = new Map();
+    ttlMs;
+    maxEntries;
+    sweepTimer;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        // Periodic sweep — relies on FIFO ordering so we can break early.
+        this.sweepTimer = setInterval(() => this.sweep(), SWEEP_INTERVAL_MS);
+        this.sweepTimer.unref();
+    }
+    /**
+     * Try to record a message ID.
+     *
+     * @param id   Unique message identifier (e.g. Feishu `message_id`).
+     * @param scope Optional scope prefix (e.g. accountId) to namespace IDs.
+     * @returns `true` if the message is **new**; `false` if it is a duplicate.
+     */
+    tryRecord(id, scope) {
+        const key = scope ? `${scope}:${id}` : id;
+        const now = Date.now();
+        const existing = this.store.get(key);
+        if (existing !== undefined) {
+            // Entry exists — check TTL.
+            if (now - existing < this.ttlMs) {
+                // Still within TTL → duplicate.
+                return false;
+            }
+            // Expired — remove so we can re-insert at the tail (refresh position).
+            this.store.delete(key);
+        }
+        // Enforce capacity via FIFO: drop the oldest entry.
+        if (this.store.size >= this.maxEntries) {
+            const oldest = this.store.keys().next().value;
+            if (oldest !== undefined) {
+                this.store.delete(oldest);
+            }
+        }
+        this.store.set(key, now);
+        return true;
+    }
+    /** Current number of tracked entries (for diagnostics). */
+    get size() {
+        return this.store.size;
+    }
+    /** Remove all entries and stop the periodic sweep. */
+    clear() {
+        clearInterval(this.sweepTimer);
+        this.store.clear();
+    }
+    /** Stop the periodic sweep timer and clear all tracked entries. */
+    dispose() {
+        clearInterval(this.sweepTimer);
+        this.store.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    /**
+     * Sweep expired entries from the front of the map.
+     * Because entries are in insertion order (FIFO), we can stop as soon as
+     * we hit one that hasn't expired yet.
+     */
+    sweep() {
+        const now = Date.now();
+        for (const [key, ts] of this.store) {
+            if (now - ts < this.ttlMs)
+                break;
+            this.store.delete(key);
+        }
+    }
+}
+exports.MessageDedup = MessageDedup;

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

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Pure construction functions for the agent dispatch pipeline.
+ *
+ * All functions in this module are side-effect-free: they build data
+ * structures (message bodies, envelope payloads, inbound context) but
+ * never perform I/O, send messages, or mutate external state.
+ */
+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-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, sentinels?: SentinelEntry[]): string | undefined;
+/**
+ * Pure function: build the annotated message body with optional quote,
+ * speaker prefix, and mention annotation (for the envelope Body).
+ *
+ * Note: message_id and reply_to are now conveyed via system-event tags
+ * (msg:om_xxx, reply_to:om_yyy) instead of inline annotations, keeping
+ * 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, sentinels?: SentinelEntry[]): string;
+/**
+ * Build the BodyForAgent value: the clean message content plus an
+ * optional mention annotation.
+ *
+ * SDK >= 2026.2.10 changed the BodyForAgent fallback chain from
+ * `BodyForAgent ?? Body` to `BodyForAgent ?? CommandBody ?? RawBody ?? Body`,
+ * so annotations embedded only in Body never reach the AI.  Setting
+ * BodyForAgent explicitly ensures the mention annotation survives.
+ *
+ * Sender identity, reply context, and chat history are NOT duplicated
+ * here — they are injected by the SDK's `buildInboundUserContextPrefix`
+ * via the standard fields (SenderId, SenderName, ReplyToBody,
+ * InboundHistory) that we pass in buildInboundPayload.
+ *
+ * Note: media file paths are substituted into `ctx.content` upstream
+ * (handler.ts -> substituteMediaPaths) before this function is called.
+ * The SDK's `detectAndLoadPromptImages` will discover image paths from
+ * the text and inject them as multimodal content blocks.
+ */
+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.
+ */
+export declare function buildInboundPayload(dc: DispatchContext, opts: {
+    body: string;
+    bodyForAgent: string;
+    rawBody: string;
+    commandBody: string;
+    originatingTo?: string;
+    senderName: string;
+    senderId: string;
+    messageSid: string;
+    wasMentioned: boolean;
+    replyToBody?: string;
+    inboundHistory?: {
+        sender: string;
+        body: string;
+        timestamp: number;
+    }[];
+    extraFields?: Record<string, unknown>;
+}): ReturnType<typeof LarkClient.runtime.channel.reply.finalizeInboundContext>;
+/**
+ * Structured identity signals injected into the agent envelope so the LLM
+ * can tell "who is talking to me" apart — in particular whether the sender
+ * is a bot, and what the bot's own open_id is.
+ *
+ * BotOpenId is omitted when unknown (e.g. startup race before the bot info
+ * probe completes) to avoid surfacing an empty identity to the agent.
+ */
+export declare function buildFeishuIdentityFields(ctx: MessageContext, botOpenId?: string): Record<string, unknown>;
+/**
+ * Build the effective group system prompt for a Feishu group chat.
+ *
+ * Always prepends bot-at-bot guidance (self-identity + @ semantics + loop
+ * hygiene) so the agent knows which open_id is itself, how Feishu @-delivery
+ * works, and when to stop; then appends any operator-configured group
+ * systemPrompt. Returns `undefined` only when there is nothing to inject.
+ */
+export declare function buildFeishuGroupSystemPrompt(configured: string | undefined, botOpenId?: string): string | undefined;
+/**
+ * Format the agent envelope and prepend group chat history if applicable.
+ * Returns the combined body and the history key (undefined for DMs).
+ */
+export declare function buildEnvelopeWithHistory(dc: DispatchContext, messageBody: string, chatHistories: Map<string, HistoryEntry[]> | undefined, historyLimit: number): {
+    combinedBody: string;
+    historyKey: string | undefined;
+};

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

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Pure construction functions for the agent dispatch pipeline.
+ *
+ * All functions in this module are side-effect-free: they build data
+ * structures (message bodies, envelope payloads, inbound context) but
+ * never perform I/O, send messages, or mutate external state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMentionAnnotation = buildMentionAnnotation;
+exports.buildMessageBody = buildMessageBody;
+exports.buildBodyForAgent = buildBodyForAgent;
+exports.buildInboundPayload = buildInboundPayload;
+exports.buildFeishuIdentityFields = buildFeishuIdentityFields;
+exports.buildFeishuGroupSystemPrompt = buildFeishuGroupSystemPrompt;
+exports.buildEnvelopeWithHistory = buildEnvelopeWithHistory;
+const reply_history_1 = require("openclaw/plugin-sdk/reply-history");
+const chat_queue_1 = require("../../channel/chat-queue.js");
+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-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, sentinels) {
+    // When this bot itself was @-mentioned, tell the agent explicitly. The
+    // leading self-mention is stripped from the body, so without this the
+    // agent has no signal that it was the addressee and may mis-attribute
+    // instructions to another mentioned party.
+    const selfMention = ctx.mentions.find((m) => m.isBot);
+    const sections = [
+        selfMention
+            ? `You (${selfMention.name}, open_id: ${selfMention.openId}) were directly @mentioned in this message; ` +
+                `the message body is addressed to you.`
+            : undefined,
+        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 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
+// ---------------------------------------------------------------------------
+/**
+ * Pure function: build the annotated message body with optional quote,
+ * speaker prefix, and mention annotation (for the envelope Body).
+ *
+ * Note: message_id and reply_to are now conveyed via system-event tags
+ * (msg:om_xxx, reply_to:om_yyy) instead of inline annotations, keeping
+ * the body cleaner and avoiding misleading heuristics for non-text
+ * message types (merge_forward, interactive cards, etc.).
+ */
+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, sentinels);
+    if (mentionAnnotation) {
+        messageBody += `\n\n${mentionAnnotation}`;
+    }
+    return messageBody;
+}
+/**
+ * Build the BodyForAgent value: the clean message content plus an
+ * optional mention annotation.
+ *
+ * SDK >= 2026.2.10 changed the BodyForAgent fallback chain from
+ * `BodyForAgent ?? Body` to `BodyForAgent ?? CommandBody ?? RawBody ?? Body`,
+ * so annotations embedded only in Body never reach the AI.  Setting
+ * BodyForAgent explicitly ensures the mention annotation survives.
+ *
+ * Sender identity, reply context, and chat history are NOT duplicated
+ * here — they are injected by the SDK's `buildInboundUserContextPrefix`
+ * via the standard fields (SenderId, SenderName, ReplyToBody,
+ * InboundHistory) that we pass in buildInboundPayload.
+ *
+ * Note: media file paths are substituted into `ctx.content` upstream
+ * (handler.ts -> substituteMediaPaths) before this function is called.
+ * The SDK's `detectAndLoadPromptImages` will discover image paths from
+ * the text and inject them as multimodal content blocks.
+ */
+function buildBodyForAgent(ctx, sentinels) {
+    const mentionAnnotation = buildMentionAnnotation(ctx, sentinels);
+    if (mentionAnnotation) {
+        return `${ctx.content}\n\n${mentionAnnotation}`;
+    }
+    return ctx.content;
+}
+// ---------------------------------------------------------------------------
+// Inbound payload builder
+// ---------------------------------------------------------------------------
+/**
+ * Unified call to `finalizeInboundContext`, eliminating the duplicated
+ * field-mapping between permission notification and main message paths.
+ */
+function buildInboundPayload(dc, opts) {
+    return dc.core.channel.reply.finalizeInboundContext({
+        // extraFields first — fixed fields below always take precedence
+        ...opts.extraFields,
+        Body: opts.body,
+        BodyForAgent: opts.bodyForAgent,
+        RawBody: opts.rawBody,
+        CommandBody: opts.commandBody,
+        From: dc.feishuFrom,
+        To: dc.feishuTo,
+        SessionKey: dc.threadSessionKey ?? dc.route.sessionKey,
+        AccountId: dc.route.accountId,
+        ChatType: dc.isGroup ? 'group' : 'direct',
+        GroupSubject: dc.isGroup ? dc.ctx.chatId : undefined,
+        SenderName: opts.senderName,
+        SenderId: opts.senderId,
+        Provider: 'feishu',
+        Surface: 'feishu',
+        MessageSid: opts.messageSid,
+        ReplyToBody: opts.replyToBody,
+        InboundHistory: opts.inboundHistory,
+        Timestamp: dc.ctx.createTime ?? Date.now(),
+        WasMentioned: opts.wasMentioned,
+        CommandAuthorized: dc.commandAuthorized,
+        OriginatingChannel: 'feishu',
+        OriginatingTo: opts.originatingTo ?? dc.feishuTo,
+    });
+}
+// ---------------------------------------------------------------------------
+// Bot-at-Bot identity & guidance
+// ---------------------------------------------------------------------------
+/**
+ * Structured identity signals injected into the agent envelope so the LLM
+ * can tell "who is talking to me" apart — in particular whether the sender
+ * is a bot, and what the bot's own open_id is.
+ *
+ * BotOpenId is omitted when unknown (e.g. startup race before the bot info
+ * probe completes) to avoid surfacing an empty identity to the agent.
+ */
+function buildFeishuIdentityFields(ctx, botOpenId) {
+    return {
+        SenderIsBot: ctx.senderIsBot ?? false,
+        ...(botOpenId ? { BotOpenId: botOpenId } : {}),
+    };
+}
+/** Static guidance about Feishu's bot-at-bot @ semantics and loop hygiene. */
+const FEISHU_BOT_AT_BOT_GUIDANCE = 'On Feishu, another bot only receives a message when you explicitly @-mention it; ' +
+    'a plain message or a reply without an @ will NOT reach another bot. ' +
+    'When you need another bot to continue the work, @-mention it. ' +
+    'When no further action is needed, or you are asked to stop, do not reply — ' +
+    'this avoids endless bot-to-bot loops.';
+/**
+ * Build the effective group system prompt for a Feishu group chat.
+ *
+ * Always prepends bot-at-bot guidance (self-identity + @ semantics + loop
+ * hygiene) so the agent knows which open_id is itself, how Feishu @-delivery
+ * works, and when to stop; then appends any operator-configured group
+ * systemPrompt. Returns `undefined` only when there is nothing to inject.
+ */
+function buildFeishuGroupSystemPrompt(configured, botOpenId) {
+    const parts = [];
+    if (botOpenId) {
+        parts.push(`Your own Feishu open_id is "${botOpenId}"; any @-mention of this open_id refers to you.`);
+    }
+    parts.push(FEISHU_BOT_AT_BOT_GUIDANCE);
+    const trimmedConfigured = configured?.trim();
+    if (trimmedConfigured) {
+        parts.push(trimmedConfigured);
+    }
+    const merged = parts.join('\n\n').trim();
+    return merged || undefined;
+}
+// ---------------------------------------------------------------------------
+// Envelope + history builder
+// ---------------------------------------------------------------------------
+/**
+ * Format the agent envelope and prepend group chat history if applicable.
+ * Returns the combined body and the history key (undefined for DMs).
+ */
+function buildEnvelopeWithHistory(dc, messageBody, chatHistories, historyLimit) {
+    const body = dc.core.channel.reply.formatAgentEnvelope({
+        channel: 'Feishu',
+        from: dc.envelopeFrom,
+        timestamp: new Date(),
+        envelope: dc.envelopeOptions,
+        body: messageBody,
+    });
+    let combinedBody = body;
+    const historyKey = dc.isGroup ? (0, chat_queue_1.threadScopedKey)(dc.ctx.chatId, dc.isThread ? dc.ctx.threadId : undefined) : undefined;
+    if (dc.isGroup && historyKey && chatHistories) {
+        combinedBody = (0, reply_history_1.buildPendingHistoryContextFromMap)({
+            historyMap: chatHistories,
+            historyKey,
+            limit: historyLimit,
+            currentMessage: combinedBody,
+            formatEntry: (entry) => dc.core.channel.reply.formatAgentEnvelope({
+                channel: 'Feishu',
+                from: `${dc.ctx.chatId}:${entry.sender}`,
+                timestamp: entry.timestamp,
+                body: entry.body,
+                envelope: dc.envelopeOptions,
+            }),
+        });
+    }
+    return { combinedBody, historyKey };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * System command and permission notification dispatch for inbound messages.
+ *
+ * Handles control commands (/help, /reset, etc.) via plain-text delivery
+ * and permission-error notifications via the streaming card flow.
+ */
+import type { LarkClient } from '../../core/lark-client';
+import type { PermissionError } from './permission';
+import type { DispatchContext } from './dispatch-context';
+/**
+ * Dispatch a permission-error notification to the agent so it can
+ * inform the user about the missing Feishu API scope.
+ */
+export declare function dispatchPermissionNotification(dc: DispatchContext, permissionError: PermissionError, replyToMessageId?: string): Promise<void>;
+/**
+ * Dispatch a system command (/help, /reset, etc.) via plain-text delivery.
+ * No streaming card, no "Processing..." state.
+ */
+export declare function dispatchSystemCommand(dc: DispatchContext, ctxPayload: ReturnType<typeof LarkClient.runtime.channel.reply.finalizeInboundContext>, replyToMessageId?: string): Promise<void>;

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

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * System command and permission notification dispatch for inbound messages.
+ *
+ * Handles control commands (/help, /reset, etc.) via plain-text delivery
+ * and permission-error notifications via the streaming card flow.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchPermissionNotification = dispatchPermissionNotification;
+exports.dispatchSystemCommand = dispatchSystemCommand;
+const lark_logger_1 = require("../../core/lark-logger.js");
+const lark_ticket_1 = require("../../core/lark-ticket.js");
+const reply_dispatcher_1 = require("../../card/reply-dispatcher.js");
+const tool_use_trace_store_1 = require("../../card/tool-use-trace-store.js");
+const send_1 = require("../outbound/send.js");
+const dispatch_builders_1 = require("./dispatch-builders.js");
+const log = (0, lark_logger_1.larkLogger)('inbound/dispatch-commands');
+// ---------------------------------------------------------------------------
+// Permission error notification
+// ---------------------------------------------------------------------------
+/**
+ * Dispatch a permission-error notification to the agent so it can
+ * inform the user about the missing Feishu API scope.
+ */
+async function dispatchPermissionNotification(dc, permissionError, replyToMessageId) {
+    const grantUrl = permissionError.grantUrl ?? '';
+    const permissionNotifyBody = `[System: The bot encountered a Feishu API permission error. Please inform the user about this issue and provide the permission grant URL for the admin to authorize. Permission grant URL: ${grantUrl}]`;
+    const permBody = dc.core.channel.reply.formatAgentEnvelope({
+        channel: 'Feishu',
+        from: dc.envelopeFrom,
+        timestamp: new Date(),
+        envelope: dc.envelopeOptions,
+        body: permissionNotifyBody,
+    });
+    const permCtx = (0, dispatch_builders_1.buildInboundPayload)(dc, {
+        body: permBody,
+        bodyForAgent: permissionNotifyBody,
+        rawBody: permissionNotifyBody,
+        commandBody: permissionNotifyBody,
+        senderName: 'system',
+        senderId: 'system',
+        messageSid: `${dc.ctx.messageId}:permission-error`,
+        wasMentioned: false,
+    });
+    (0, tool_use_trace_store_1.startToolUseTraceRun)(dc.threadSessionKey ?? dc.route.sessionKey);
+    const { dispatcher: permDispatcher, replyOptions: permReplyOptions, markDispatchIdle: markPermIdle, markFullyComplete: markPermComplete, } = (0, reply_dispatcher_1.createFeishuReplyDispatcher)({
+        cfg: dc.accountScopedCfg,
+        agentId: dc.route.agentId,
+        chatId: dc.ctx.chatId,
+        sessionKey: dc.threadSessionKey ?? dc.route.sessionKey,
+        replyToMessageId: replyToMessageId ?? dc.ctx.messageId,
+        accountId: dc.account.accountId,
+        chatType: dc.ctx.chatType,
+        replyInThread: dc.isThread,
+        toolUseDisplay: {
+            mode: 'off',
+            showToolUse: false,
+            showToolResultDetails: false,
+            showFullPaths: false,
+        },
+    });
+    dc.log(`feishu[${dc.account.accountId}]: dispatching permission error notification to agent`);
+    await dc.core.channel.reply.dispatchReplyFromConfig({
+        ctx: permCtx,
+        cfg: dc.accountScopedCfg,
+        dispatcher: permDispatcher,
+        replyOptions: permReplyOptions,
+    });
+    await permDispatcher.waitForIdle();
+    markPermComplete();
+    markPermIdle();
+}
+// ---------------------------------------------------------------------------
+// System command dispatch
+// ---------------------------------------------------------------------------
+/**
+ * Dispatch a system command (/help, /reset, etc.) via plain-text delivery.
+ * No streaming card, no "Processing..." state.
+ */
+async function dispatchSystemCommand(dc, ctxPayload, replyToMessageId) {
+    let delivered = false;
+    const suppressToolDetails = isLifecycleSessionCommand(dc.ctx.content);
+    dc.log(`feishu[${dc.account.accountId}]: detected system command, using plain-text dispatch`);
+    log.info('system command detected, plain-text dispatch');
+    await dc.core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx: ctxPayload,
+        cfg: dc.accountScopedCfg,
+        dispatcherOptions: {
+            deliver: async (payload, info) => {
+                if (suppressToolDetails && info.kind === 'tool') {
+                    return;
+                }
+                const text = payload.text?.trim() ?? '';
+                if (!text)
+                    return;
+                await (0, send_1.sendMessageFeishu)({
+                    cfg: dc.accountScopedCfg,
+                    to: dc.ctx.chatId,
+                    text,
+                    replyToMessageId: replyToMessageId ?? dc.ctx.messageId,
+                    accountId: dc.account.accountId,
+                    replyInThread: dc.isThread,
+                });
+                delivered = true;
+            },
+            onSkip: (_payload, info) => {
+                if (info.reason !== 'silent') {
+                    dc.log(`feishu[${dc.account.accountId}]: command reply skipped (reason=${info.reason})`);
+                }
+            },
+            onError: (err, info) => {
+                dc.error(`feishu[${dc.account.accountId}]: command ${info.kind} reply failed: ${String(err)}`);
+            },
+        },
+        replyOptions: {},
+    });
+    dc.log(`feishu[${dc.account.accountId}]: system command dispatched (delivered=${delivered})`);
+    log.info(`system command dispatched (delivered=${delivered}, elapsed=${(0, lark_ticket_1.ticketElapsed)()}ms)`);
+}
+function isLifecycleSessionCommand(text) {
+    if (!text)
+        return false;
+    const match = text.trim().match(/^\/([^\s@]+)/);
+    if (!match)
+        return false;
+    const command = match[1]?.toLowerCase();
+    return command === 'new' || command === 'reset';
+}