@colinlu50/openclaw-lark-stream 2026.3.17

package/src/card/unavailable-guard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Guard against operating on unavailable (deleted/recalled) messages.
+ *
+ * Encapsulates the terminateDueToUnavailable / shouldSkipForUnavailable
+ * logic previously scattered as closures in reply-dispatcher.ts.
+ */
+export interface UnavailableGuardParams {
+    replyToMessageId: string | undefined;
+    getCardMessageId: () => string | null;
+    onTerminate: () => void;
+}
+export declare class UnavailableGuard {
+    private terminated;
+    private readonly replyToMessageId;
+    private readonly getCardMessageId;
+    private readonly onTerminate;
+    constructor(params: UnavailableGuardParams);
+    get isTerminated(): boolean;
+    /**
+     * Check whether the reply pipeline should skip further operations.
+     * Returns true if the message is already known to be unavailable.
+     */
+    shouldSkip(source: string): boolean;
+    /**
+     * Attempt to terminate the reply pipeline due to an unavailable message.
+     *
+     * @param source - Descriptive label for the caller (for logging).
+     * @param err    - Optional error that triggered the check.
+     * @returns true if the pipeline was (or already had been) terminated.
+     */
+    terminate(source: string, err?: unknown): boolean;
+}

package/src/card/unavailable-guard.js

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Guard against operating on unavailable (deleted/recalled) messages.
+ *
+ * Encapsulates the terminateDueToUnavailable / shouldSkipForUnavailable
+ * logic previously scattered as closures in reply-dispatcher.ts.
+ */
+import { larkLogger } from '../core/lark-logger';
+import { extractLarkApiCode } from '../core/api-error';
+import { getMessageUnavailableState, isMessageUnavailable, isMessageUnavailableError, isTerminalMessageApiCode, markMessageUnavailable, } from '../core/message-unavailable';
+const log = larkLogger('card/unavailable-guard');
+// ---------------------------------------------------------------------------
+// UnavailableGuard
+// ---------------------------------------------------------------------------
+export class UnavailableGuard {
+    terminated = false;
+    replyToMessageId;
+    getCardMessageId;
+    onTerminate;
+    constructor(params) {
+        this.replyToMessageId = params.replyToMessageId;
+        this.getCardMessageId = params.getCardMessageId;
+        this.onTerminate = params.onTerminate;
+    }
+    get isTerminated() {
+        return this.terminated;
+    }
+    /**
+     * Check whether the reply pipeline should skip further operations.
+     * Returns true if the message is already known to be unavailable.
+     */
+    shouldSkip(source) {
+        if (this.terminated)
+            return true;
+        if (!this.replyToMessageId)
+            return false;
+        if (!isMessageUnavailable(this.replyToMessageId))
+            return false;
+        return this.terminate(source);
+    }
+    /**
+     * Attempt to terminate the reply pipeline due to an unavailable message.
+     *
+     * @param source - Descriptive label for the caller (for logging).
+     * @param err    - Optional error that triggered the check.
+     * @returns true if the pipeline was (or already had been) terminated.
+     */
+    terminate(source, err) {
+        if (this.terminated)
+            return true;
+        const fromError = isMessageUnavailableError(err) ? err : undefined;
+        const cardMessageId = this.getCardMessageId();
+        const state = getMessageUnavailableState(this.replyToMessageId) ?? getMessageUnavailableState(cardMessageId ?? undefined);
+        let apiCode = fromError?.apiCode ?? state?.apiCode;
+        if (!apiCode && err) {
+            const detectedCode = extractLarkApiCode(err);
+            if (isTerminalMessageApiCode(detectedCode)) {
+                const fallbackMessageId = this.replyToMessageId ?? cardMessageId ?? undefined;
+                if (fallbackMessageId) {
+                    markMessageUnavailable({
+                        messageId: fallbackMessageId,
+                        apiCode: detectedCode,
+                        operation: source,
+                    });
+                }
+                apiCode = detectedCode;
+            }
+        }
+        if (!apiCode)
+            return false;
+        this.terminated = true;
+        this.onTerminate();
+        const affectedMessageId = fromError?.messageId ?? this.replyToMessageId ?? cardMessageId ?? 'unknown';
+        log.warn('reply pipeline terminated by unavailable message', {
+            source,
+            apiCode,
+            messageId: affectedMessageId,
+        });
+        return true;
+    }
+}

package/src/channel/abort-detect.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Abort trigger detection for the Lark/Feishu channel plugin.
+ *
+ * Provides a fast-path check to determine whether an inbound message is
+ * an abort/stop command *before* it enters the per-chat serial queue.
+ *
+ * The trigger word list and normalisation logic are copied from the
+ * OpenClaw core (`src/auto-reply/reply/abort.ts`) so the plugin can
+ * make a lightweight decision without importing the full reply pipeline.
+ * The message still flows through `tryFastAbortFromMessage()` for
+ * authoritative handling.
+ */
+import type { FeishuMessageEvent } from '../messaging/types';
+/** Exact trigger-word match (same logic as OpenClaw core `isAbortTrigger`). */
+export declare function isAbortTrigger(text: string): boolean;
+/**
+ * Extended abort detection: matches both bare trigger words and the
+ * `/stop` command form.  Used by the monitor fast-path.
+ */
+export declare function isLikelyAbortText(text: string): boolean;
+/**
+ * Extract the raw text payload from a Feishu message event.
+ *
+ * Only handles `text` type messages.  The `message.content` field is a
+ * JSON string like `{"text":"hello"}`.  Returns `undefined` for
+ * non-text messages or parse failures.
+ *
+ * In group chats, bot mention placeholders (`@_user_N`) are stripped so
+ * a message like `@Bot stop` is detected as `stop`.
+ */
+export declare function extractRawTextFromEvent(event: FeishuMessageEvent): string | undefined;

package/src/channel/abort-detect.js

@@ -0,0 +1,124 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Abort trigger detection for the Lark/Feishu channel plugin.
+ *
+ * Provides a fast-path check to determine whether an inbound message is
+ * an abort/stop command *before* it enters the per-chat serial queue.
+ *
+ * The trigger word list and normalisation logic are copied from the
+ * OpenClaw core (`src/auto-reply/reply/abort.ts`) so the plugin can
+ * make a lightweight decision without importing the full reply pipeline.
+ * The message still flows through `tryFastAbortFromMessage()` for
+ * authoritative handling.
+ */
+// ---------------------------------------------------------------------------
+// Trigger word list (synced with OpenClaw core abort.ts)
+// ---------------------------------------------------------------------------
+const ABORT_TRIGGERS = new Set([
+    'stop',
+    'esc',
+    'abort',
+    'wait',
+    'exit',
+    'interrupt',
+    'detente',
+    'deten',
+    'detén',
+    'arrete',
+    'arrête',
+    '停止',
+    'やめて',
+    '止めて',
+    'रुको',
+    'توقف',
+    'стоп',
+    'остановись',
+    'останови',
+    'остановить',
+    'прекрати',
+    'halt',
+    'anhalten',
+    'aufhören',
+    'hoer auf',
+    'stopp',
+    'pare',
+    'stop openclaw',
+    'openclaw stop',
+    'stop action',
+    'stop current action',
+    'stop run',
+    'stop current run',
+    'stop agent',
+    'stop the agent',
+    "stop don't do anything",
+    'stop dont do anything',
+    'stop do not do anything',
+    'stop doing anything',
+    'do not do that',
+    'please stop',
+    'stop please',
+]);
+// ---------------------------------------------------------------------------
+// Normalisation helpers
+// ---------------------------------------------------------------------------
+const TRAILING_ABORT_PUNCTUATION_RE = /[.!?…,，。;；:：'"'")\]}]+$/u;
+function normalizeAbortTriggerText(text) {
+    return text
+        .trim()
+        .toLowerCase()
+        .replace(/['`]/g, "'")
+        .replace(/\s+/g, ' ')
+        .replace(TRAILING_ABORT_PUNCTUATION_RE, '')
+        .trim();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Exact trigger-word match (same logic as OpenClaw core `isAbortTrigger`). */
+export function isAbortTrigger(text) {
+    if (!text)
+        return false;
+    const normalized = normalizeAbortTriggerText(text);
+    return ABORT_TRIGGERS.has(normalized);
+}
+/**
+ * Extended abort detection: matches both bare trigger words and the
+ * `/stop` command form.  Used by the monitor fast-path.
+ */
+export function isLikelyAbortText(text) {
+    if (!text)
+        return false;
+    const trimmed = text.trim().toLowerCase();
+    if (trimmed === '/stop')
+        return true;
+    return isAbortTrigger(trimmed);
+}
+/**
+ * Extract the raw text payload from a Feishu message event.
+ *
+ * Only handles `text` type messages.  The `message.content` field is a
+ * JSON string like `{"text":"hello"}`.  Returns `undefined` for
+ * non-text messages or parse failures.
+ *
+ * In group chats, bot mention placeholders (`@_user_N`) are stripped so
+ * a message like `@Bot stop` is detected as `stop`.
+ */
+export function extractRawTextFromEvent(event) {
+    if (!event.message || event.message.message_type !== 'text') {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(event.message.content);
+        let text = parsed?.text;
+        if (typeof text !== 'string')
+            return undefined;
+        // Strip bot mention placeholders (@_user_1, @_user_2, etc.)
+        text = text.replace(/@_user_\d+/g, '').trim();
+        return text || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/src/channel/chat-queue.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Process-level chat task queue.
+ *
+ * Although located in channel/, this module is intentionally shared
+ * across channel, messaging, tools, and card layers as a process-level
+ * singleton. Consumers: monitor.ts, dispatch.ts, oauth.ts, auto-auth.ts.
+ *
+ * Ensures tasks targeting the same account+chat are executed serially.
+ * Used by both websocket inbound messages and synthetic message paths.
+ */
+type QueueStatus = 'queued' | 'immediate';
+export interface ActiveDispatcherEntry {
+    abortCard: () => Promise<void>;
+    abortController?: AbortController;
+}
+/**
+ * Append `:thread:{threadId}` suffix when threadId is present.
+ * Consistent with the SDK's `:thread:` separator convention.
+ */
+export declare function threadScopedKey(base: string, threadId?: string): string;
+export declare function buildQueueKey(accountId: string, chatId: string, threadId?: string): string;
+export declare function registerActiveDispatcher(key: string, entry: ActiveDispatcherEntry): void;
+export declare function unregisterActiveDispatcher(key: string): void;
+export declare function getActiveDispatcher(key: string): ActiveDispatcherEntry | undefined;
+/** Check whether the queue has an active task for the given key. */
+export declare function hasActiveTask(key: string): boolean;
+export declare function enqueueFeishuChatTask(params: {
+    accountId: string;
+    chatId: string;
+    threadId?: string;
+    task: () => Promise<void>;
+}): {
+    status: QueueStatus;
+    promise: Promise<void>;
+};
+/** @internal Test-only: reset all queue and dispatcher state. */
+export declare function _resetChatQueueState(): void;
+export {};

package/src/channel/chat-queue.js

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Process-level chat task queue.
+ *
+ * Although located in channel/, this module is intentionally shared
+ * across channel, messaging, tools, and card layers as a process-level
+ * singleton. Consumers: monitor.ts, dispatch.ts, oauth.ts, auto-auth.ts.
+ *
+ * Ensures tasks targeting the same account+chat are executed serially.
+ * Used by both websocket inbound messages and synthetic message paths.
+ */
+const chatQueues = new Map();
+const activeDispatchers = new Map();
+/**
+ * Append `:thread:{threadId}` suffix when threadId is present.
+ * Consistent with the SDK's `:thread:` separator convention.
+ */
+export function threadScopedKey(base, threadId) {
+    return threadId ? `${base}:thread:${threadId}` : base;
+}
+export function buildQueueKey(accountId, chatId, threadId) {
+    return threadScopedKey(`${accountId}:${chatId}`, threadId);
+}
+export function registerActiveDispatcher(key, entry) {
+    activeDispatchers.set(key, entry);
+}
+export function unregisterActiveDispatcher(key) {
+    activeDispatchers.delete(key);
+}
+export function getActiveDispatcher(key) {
+    return activeDispatchers.get(key);
+}
+/** Check whether the queue has an active task for the given key. */
+export function hasActiveTask(key) {
+    return chatQueues.has(key);
+}
+export function enqueueFeishuChatTask(params) {
+    const { accountId, chatId, threadId, task } = params;
+    const key = buildQueueKey(accountId, chatId, threadId);
+    const prev = chatQueues.get(key) ?? Promise.resolve();
+    const status = chatQueues.has(key) ? 'queued' : 'immediate';
+    const next = prev.then(task, task); // continue queue even if previous task failed
+    chatQueues.set(key, next);
+    const cleanup = () => {
+        if (chatQueues.get(key) === next) {
+            chatQueues.delete(key);
+        }
+    };
+    next.then(cleanup, cleanup);
+    return { status, promise: next };
+}
+/** @internal Test-only: reset all queue and dispatcher state. */
+export function _resetChatQueueState() {
+    chatQueues.clear();
+    activeDispatchers.clear();
+}

package/src/channel/config-adapter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Configuration merge helpers for Feishu account management.
+ *
+ * Centralises the pattern of merging a partial configuration patch
+ * into the Feishu section of the top-level ClawdbotConfig, handling
+ * both the default account (top-level fields) and named accounts
+ * (nested under `accounts`).
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+/** Set the `enabled` flag on a Feishu account. */
+export declare function setAccountEnabled(cfg: ClawdbotConfig, accountId: string, enabled: boolean): ClawdbotConfig;
+/** Apply an arbitrary config patch to a Feishu account. */
+export declare function applyAccountConfig(cfg: ClawdbotConfig, accountId: string, patch: Record<string, unknown>): ClawdbotConfig;
+/** Delete a Feishu account entry from the config. */
+export declare function deleteAccount(cfg: ClawdbotConfig, accountId: string): ClawdbotConfig;
+/** Collect security warnings for a Feishu account. */
+export declare function collectFeishuSecurityWarnings(params: {
+    cfg: ClawdbotConfig;
+    accountId: string;
+}): string[];

package/src/channel/config-adapter.js

@@ -0,0 +1,101 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Configuration merge helpers for Feishu account management.
+ *
+ * Centralises the pattern of merging a partial configuration patch
+ * into the Feishu section of the top-level ClawdbotConfig, handling
+ * both the default account (top-level fields) and named accounts
+ * (nested under `accounts`).
+ */
+import { DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk';
+import { getLarkAccount, getLarkAccountIds } from '../core/accounts';
+import { collectIsolationWarnings } from '../core/security-check';
+/** Generic Feishu account config merge. */
+function mergeFeishuAccountConfig(cfg, accountId, patch) {
+    const isDefault = !accountId || accountId === DEFAULT_ACCOUNT_ID;
+    if (isDefault) {
+        return {
+            ...cfg,
+            channels: {
+                ...cfg.channels,
+                feishu: { ...cfg.channels?.feishu, ...patch },
+            },
+        };
+    }
+    const feishuCfg = cfg.channels?.feishu;
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...feishuCfg,
+                accounts: {
+                    ...feishuCfg?.accounts,
+                    [accountId]: { ...feishuCfg?.accounts?.[accountId], ...patch },
+                },
+            },
+        },
+    };
+}
+/** Set the `enabled` flag on a Feishu account. */
+export function setAccountEnabled(cfg, accountId, enabled) {
+    return mergeFeishuAccountConfig(cfg, accountId, { enabled });
+}
+/** Apply an arbitrary config patch to a Feishu account. */
+export function applyAccountConfig(cfg, accountId, patch) {
+    return mergeFeishuAccountConfig(cfg, accountId, patch);
+}
+/** Delete a Feishu account entry from the config. */
+export function deleteAccount(cfg, accountId) {
+    const isDefault = !accountId || accountId === DEFAULT_ACCOUNT_ID;
+    if (isDefault) {
+        // Delete entire feishu config
+        const next = { ...cfg };
+        const nextChannels = { ...cfg.channels };
+        delete nextChannels.feishu;
+        if (Object.keys(nextChannels).length > 0) {
+            next.channels = nextChannels;
+        }
+        else {
+            delete next.channels;
+        }
+        return next;
+    }
+    // Delete specific account from accounts
+    const feishuCfg = cfg.channels?.feishu;
+    const accounts = { ...feishuCfg?.accounts };
+    delete accounts[accountId];
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...feishuCfg,
+                accounts: Object.keys(accounts).length > 0 ? accounts : undefined,
+            },
+        },
+    };
+}
+/** Collect security warnings for a Feishu account. */
+export function collectFeishuSecurityWarnings(params) {
+    const { cfg, accountId } = params;
+    const warnings = [];
+    const account = getLarkAccount(cfg, accountId);
+    const feishuCfg = account.config;
+    // cfg.channels.defaults is a cross-channel defaults object (not formally typed)
+    const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+    const groupPolicy = feishuCfg?.groupPolicy ?? defaultGroupPolicy ?? 'allowlist';
+    if (groupPolicy === 'open') {
+        warnings.push(`- Feishu[${account.accountId}] groups: groupPolicy="open" allows any group to interact (mention-gated). To restrict which groups are allowed, set groupPolicy="allowlist" and list group IDs in channels.feishu.groups. To restrict which senders can trigger the bot, set channels.feishu.groupAllowFrom with user open_ids (ou_xxx).`);
+    }
+    // Multi-account cross-tenant isolation check (only on first account to avoid duplicates)
+    const allIds = getLarkAccountIds(cfg);
+    if (allIds.length === 0 || accountId === allIds[0]) {
+        for (const w of collectIsolationWarnings(cfg)) {
+            warnings.push(w);
+        }
+    }
+    return warnings;
+}

package/src/channel/directory.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Directory listing for Feishu peers (users) and groups.
+ *
+ * Provides both config-based (offline) and live API directory
+ * lookups so the outbound subsystem and UI can resolve targets.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { FeishuDirectoryPeer, FeishuDirectoryGroup } from './types';
+export type { FeishuDirectoryPeer, FeishuDirectoryGroup } from './types';
+/**
+ * List users known from the channel config (allowFrom + dms fields).
+ *
+ * Does not make any API calls -- useful when the bot is not yet
+ * connected or when credentials are unavailable.
+ */
+export declare function listFeishuDirectoryPeers(params: {
+    cfg: ClawdbotConfig;
+    query?: string;
+    limit?: number;
+    accountId?: string;
+}): Promise<FeishuDirectoryPeer[]>;
+/**
+ * List groups known from the channel config (groups + groupAllowFrom).
+ */
+export declare function listFeishuDirectoryGroups(params: {
+    cfg: ClawdbotConfig;
+    query?: string;
+    limit?: number;
+    accountId?: string;
+}): Promise<FeishuDirectoryGroup[]>;
+/**
+ * List users via the Feishu contact/v3/users API.
+ *
+ * Falls back to config-based listing when credentials are missing or
+ * the API call fails.
+ */
+export declare function listFeishuDirectoryPeersLive(params: {
+    cfg: ClawdbotConfig;
+    query?: string;
+    limit?: number;
+    accountId?: string;
+}): Promise<FeishuDirectoryPeer[]>;
+/**
+ * List groups via the Feishu im/v1/chats API.
+ *
+ * Falls back to config-based listing when credentials are missing or
+ * the API call fails.
+ */
+export declare function listFeishuDirectoryGroupsLive(params: {
+    cfg: ClawdbotConfig;
+    query?: string;
+    limit?: number;
+    accountId?: string;
+}): Promise<FeishuDirectoryGroup[]>;