@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/card/card-error.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Unified card API error handling.
+ *
+ * Provides structured error class for CardKit API responses, sub-error
+ * parsing for the generic 230099 code, and helper predicates used by
+ * reply-dispatcher and streaming-card-controller.
+ */
+/** 卡片 API 级别错误码。 */
+export declare const CARD_ERROR: {
+    /** 发送频率限制 */
+    readonly RATE_LIMITED: 230020;
+    /** 卡片内容创建失败（通用码，需检查子错误） */
+    readonly CARD_CONTENT_FAILED: 230099;
+};
+/** 230099 子错误码，嵌套在 msg 的 ErrCode 字段中。 */
+export declare const CARD_CONTENT_SUB_ERROR: {
+    /** 卡片元素（表格等）数量超限 */
+    readonly ELEMENT_LIMIT: 11310;
+};
+export declare const FEISHU_CARD_TABLE_LIMIT = 3;
+export interface MarkdownTableMatch {
+    index: number;
+    length: number;
+    raw: string;
+}
+/** CardKit API 返回非零 code 时的结构化错误。 */
+export declare class CardKitApiError extends Error {
+    readonly code: number;
+    readonly msg: string;
+    constructor(params: {
+        api: string;
+        code: number;
+        msg: string;
+        context: string;
+    });
+}
+/**
+ * 从 msg 字符串中提取子错误码。
+ *
+ * 示例输入: "Failed to create card content, ext=ErrCode: 11310; ErrMsg: element exceeds the limit; code:230099"
+ * 返回 11310 或 null。
+ */
+export declare function extractSubCode(msg: string): number | null;
+/**
+ * 从任意抛错对象中解析卡片 API 错误结构。
+ *
+ * 返回 { code, subCode, errMsg }，如果无法提取 code 则返回 null。
+ */
+export declare function parseCardApiError(err: unknown): {
+    code: number;
+    subCode: number | null;
+    errMsg: string;
+} | null;
+/**
+ * 判断错误是否为卡片表格数量超限。
+ *
+ * 匹配条件：code 230099 + subCode 11310 + errMsg 含 "table number over limit"。
+ * 11310 是通用的元素超限码（也覆盖模板可见性、组件上限等），
+ * 必须同时检查 errMsg 确认是表格数量导致的。
+ *
+ * 实际错误格式（生产日志 2026-03-13）：
+ * "Failed to create card content, ext=ErrCode: 11310; ErrMsg: card table number over limit; ErrorValue: table; "
+ */
+export declare function isCardTableLimitError(err: unknown): boolean;
+/** 判断错误是否为卡片发送频率限制（230020）。 */
+export declare function isCardRateLimitError(err: unknown): boolean;
+/**
+ * 收集正文里可被飞书卡片实际渲染的 markdown 表格。
+ *
+ * 代码块里的示例表格不会被飞书解析成卡片表格元素，因此这里要先排除，
+ * 让 shouldUseCard() 预检和 sanitizeTextForCard() 降级逻辑使用同一份结果。
+ */
+export declare function findMarkdownTablesOutsideCodeBlocks(text: string): MarkdownTableMatch[];
+/**
+ * 对多段 markdown 文本共享一个表格预算。
+ *
+ * 段落按数组顺序消耗额度，适合处理“reasoning + 正文”这类会被飞书
+ * 作为同一张卡片渲染的多块文本。
+ */
+export declare function sanitizeTextSegmentsForCard(texts: readonly string[], tableLimit?: number): string[];
+/**
+ * 对正文中超出 tableLimit 的 markdown 表格降级为 code block，
+ * 避免飞书卡片因表格数超限触发 230099/11310。
+ *
+ * 前 tableLimit 张表格保持原样（可正常卡片渲染）；
+ * 超出部分用反引号包裹，阻止飞书将其解析为卡片表格元素。
+ */
+export declare function sanitizeTextForCard(text: string, tableLimit?: number): string;

package/src/card/card-error.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Unified card API error handling.
+ *
+ * Provides structured error class for CardKit API responses, sub-error
+ * parsing for the generic 230099 code, and helper predicates used by
+ * reply-dispatcher and streaming-card-controller.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CardKitApiError = exports.FEISHU_CARD_TABLE_LIMIT = exports.CARD_CONTENT_SUB_ERROR = exports.CARD_ERROR = void 0;
+exports.extractSubCode = extractSubCode;
+exports.parseCardApiError = parseCardApiError;
+exports.isCardTableLimitError = isCardTableLimitError;
+exports.isCardRateLimitError = isCardRateLimitError;
+exports.findMarkdownTablesOutsideCodeBlocks = findMarkdownTablesOutsideCodeBlocks;
+exports.sanitizeTextSegmentsForCard = sanitizeTextSegmentsForCard;
+exports.sanitizeTextForCard = sanitizeTextForCard;
+const api_error_1 = require("../core/api-error.js");
+// ---------------------------------------------------------------------------
+// Error code constants
+// ---------------------------------------------------------------------------
+/** 卡片 API 级别错误码。 */
+exports.CARD_ERROR = {
+    /** 发送频率限制 */
+    RATE_LIMITED: 230020,
+    /** 卡片内容创建失败（通用码，需检查子错误） */
+    CARD_CONTENT_FAILED: 230099,
+};
+/** 230099 子错误码，嵌套在 msg 的 ErrCode 字段中。 */
+exports.CARD_CONTENT_SUB_ERROR = {
+    /** 卡片元素（表格等）数量超限 */
+    ELEMENT_LIMIT: 11310,
+};
+// 经验性的飞书卡片表格上限 -- 4+ 张触发 230099/11310（2026-03 实测）。
+exports.FEISHU_CARD_TABLE_LIMIT = 3;
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+/** CardKit API 返回非零 code 时的结构化错误。 */
+class CardKitApiError extends Error {
+    code;
+    msg;
+    constructor(params) {
+        const { api, code, msg, context } = params;
+        super(`cardkit ${api} FAILED: code=${code}, msg=${msg}, ${context}`);
+        this.name = 'CardKitApiError';
+        this.code = code;
+        this.msg = msg;
+    }
+}
+exports.CardKitApiError = CardKitApiError;
+// ---------------------------------------------------------------------------
+// Sub-error extraction
+// ---------------------------------------------------------------------------
+/**
+ * 从 msg 字符串中提取子错误码。
+ *
+ * 示例输入: "Failed to create card content, ext=ErrCode: 11310; ErrMsg: element exceeds the limit; code:230099"
+ * 返回 11310 或 null。
+ */
+function extractSubCode(msg) {
+    const match = /ErrCode:\s*(\d+)/.exec(msg);
+    if (!match)
+        return null;
+    const code = Number(match[1]);
+    return Number.isFinite(code) ? code : null;
+}
+// ---------------------------------------------------------------------------
+// Structured error parsing
+// ---------------------------------------------------------------------------
+/**
+ * 从任意抛错对象中解析卡片 API 错误结构。
+ *
+ * 返回 { code, subCode, errMsg }，如果无法提取 code 则返回 null。
+ */
+function parseCardApiError(err) {
+    const code = (0, api_error_1.extractLarkApiCode)(err);
+    if (code === undefined)
+        return null;
+    // 按优先级提取 msg 文本
+    let errMsg = '';
+    if (err && typeof err === 'object') {
+        const e = err;
+        if (typeof e.msg === 'string') {
+            errMsg = e.msg;
+        }
+        else if (typeof e.response?.data?.msg === 'string') {
+            // Axios errors: response.data.msg carries the Feishu detail with ErrCode
+            errMsg = e.response.data.msg;
+        }
+        else if (typeof e.message === 'string') {
+            // Fallback to generic Error.message (e.g. CardKitApiError)
+            errMsg = e.message;
+        }
+    }
+    const subCode = extractSubCode(errMsg);
+    return { code, subCode, errMsg };
+}
+// ---------------------------------------------------------------------------
+// Helper predicates
+// ---------------------------------------------------------------------------
+/**
+ * 判断错误是否为卡片表格数量超限。
+ *
+ * 匹配条件：code 230099 + subCode 11310 + errMsg 含 "table number over limit"。
+ * 11310 是通用的元素超限码（也覆盖模板可见性、组件上限等），
+ * 必须同时检查 errMsg 确认是表格数量导致的。
+ *
+ * 实际错误格式（生产日志 2026-03-13）：
+ * "Failed to create card content, ext=ErrCode: 11310; ErrMsg: card table number over limit; ErrorValue: table; "
+ */
+function isCardTableLimitError(err) {
+    const parsed = parseCardApiError(err);
+    if (!parsed)
+        return false;
+    return (parsed.code === exports.CARD_ERROR.CARD_CONTENT_FAILED &&
+        parsed.subCode === exports.CARD_CONTENT_SUB_ERROR.ELEMENT_LIMIT &&
+        /table number over limit/i.test(parsed.errMsg));
+}
+/** 判断错误是否为卡片发送频率限制（230020）。 */
+function isCardRateLimitError(err) {
+    const parsed = parseCardApiError(err);
+    if (!parsed)
+        return false;
+    return parsed.code === exports.CARD_ERROR.RATE_LIMITED;
+}
+// ---------------------------------------------------------------------------
+// Text sanitization
+// ---------------------------------------------------------------------------
+/**
+ * 收集正文里可被飞书卡片实际渲染的 markdown 表格。
+ *
+ * 代码块里的示例表格不会被飞书解析成卡片表格元素，因此这里要先排除，
+ * 让 shouldUseCard() 预检和 sanitizeTextForCard() 降级逻辑使用同一份结果。
+ */
+function findMarkdownTablesOutsideCodeBlocks(text) {
+    const codeBlockRanges = [];
+    const codeBlockRegex = /```[\s\S]*?```/g;
+    let codeBlockMatch = codeBlockRegex.exec(text);
+    while (codeBlockMatch != null) {
+        codeBlockRanges.push({
+            start: codeBlockMatch.index,
+            end: codeBlockMatch.index + codeBlockMatch[0].length,
+        });
+        codeBlockMatch = codeBlockRegex.exec(text);
+    }
+    const isInsideCodeBlock = (idx) => codeBlockRanges.some((range) => idx >= range.start && idx < range.end);
+    const tableRegex = /\|.+\|[\r\n]+\|[-:| ]+\|[\s\S]*?(?=\n\n|\n(?!\|)|$)/g;
+    const matches = [];
+    let tableMatch = tableRegex.exec(text);
+    while (tableMatch != null) {
+        if (!isInsideCodeBlock(tableMatch.index)) {
+            matches.push({
+                index: tableMatch.index,
+                length: tableMatch[0].length,
+                raw: tableMatch[0],
+            });
+        }
+        tableMatch = tableRegex.exec(text);
+    }
+    return matches;
+}
+/**
+ * 对多段 markdown 文本共享一个表格预算。
+ *
+ * 段落按数组顺序消耗额度，适合处理“reasoning + 正文”这类会被飞书
+ * 作为同一张卡片渲染的多块文本。
+ */
+function sanitizeTextSegmentsForCard(texts, tableLimit = exports.FEISHU_CARD_TABLE_LIMIT) {
+    let remainingTableBudget = tableLimit;
+    return texts.map((text) => {
+        const matches = findMarkdownTablesOutsideCodeBlocks(text);
+        if (matches.length <= remainingTableBudget) {
+            remainingTableBudget -= matches.length;
+            return text;
+        }
+        const sanitizedText = wrapTablesBeyondLimit(text, matches, Math.max(remainingTableBudget, 0));
+        remainingTableBudget = 0;
+        return sanitizedText;
+    });
+}
+/**
+ * 对正文中超出 tableLimit 的 markdown 表格降级为 code block，
+ * 避免飞书卡片因表格数超限触发 230099/11310。
+ *
+ * 前 tableLimit 张表格保持原样（可正常卡片渲染）；
+ * 超出部分用反引号包裹，阻止飞书将其解析为卡片表格元素。
+ */
+function sanitizeTextForCard(text, tableLimit = exports.FEISHU_CARD_TABLE_LIMIT) {
+    return sanitizeTextSegmentsForCard([text], tableLimit)[0];
+}
+function wrapTablesBeyondLimit(text, matches, keepCount) {
+    if (matches.length <= keepCount)
+        return text;
+    // Back-to-front replacement keeps the original indices stable.
+    let result = text;
+    for (let i = matches.length - 1; i >= keepCount; i--) {
+        const { index, length, raw } = matches[i];
+        const replacement = `\`\`\`\n${raw}\n\`\`\``;
+        result = result.slice(0, index) + replacement + result.slice(index + length);
+    }
+    return result;
+}

package/src/card/cardkit.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * CardKit streaming APIs for Lark/Feishu.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { FeishuSendResult } from '../messaging/types';
+/**
+ * Create a card entity via the CardKit API.
+ *
+ * Returns the card_id directly, bypassing the idConvert step.
+ * The card can then be sent via IM API and streamed via CardKit.
+ */
+export declare function createCardEntity(params: {
+    cfg: ClawdbotConfig;
+    card: Record<string, unknown>;
+    accountId?: string;
+}): Promise<string | null>;
+/**
+ * Stream text content to a specific card element using the CardKit API.
+ *
+ * The card automatically diffs the new content against the previous
+ * content and renders incremental changes with a typewriter animation.
+ *
+ * @param params.cardId    - CardKit card ID (from `convertMessageToCardId`).
+ * @param params.elementId - The element ID to update (e.g. `STREAMING_ELEMENT_ID`).
+ * @param params.content   - The full cumulative text (not a delta).
+ * @param params.sequence  - Monotonically increasing sequence number.
+ */
+export declare function streamCardContent(params: {
+    cfg: ClawdbotConfig;
+    cardId: string;
+    elementId: string;
+    content: string;
+    sequence: number;
+    accountId?: string;
+}): Promise<void>;
+/**
+ * Fully replace a card using the CardKit API.
+ *
+ * Used for the final "complete" state update (with action buttons, green
+ * header, etc.) after streaming finishes.
+ *
+ * @param params.cardId   - CardKit card ID.
+ * @param params.card     - The new card JSON content.
+ * @param params.sequence - Monotonically increasing sequence number.
+ */
+export declare function updateCardKitCard(params: {
+    cfg: ClawdbotConfig;
+    cardId: string;
+    card: Record<string, unknown>;
+    sequence: number;
+    accountId?: string;
+}): Promise<void>;
+export declare function updateCardKitCardForAuth(params: {
+    cfg: ClawdbotConfig;
+    cardId: string;
+    card: Record<string, unknown>;
+    sequence: number;
+    accountId?: string;
+}): Promise<void>;
+/**
+ * Send an interactive card message by referencing a CardKit card_id.
+ *
+ * The content format is: {"type":"card","data":{"card_id":"xxx"}}
+ * This links the IM message to the CardKit card entity, enabling
+ * streaming updates via cardElement.content().
+ */
+export declare function sendCardByCardId(params: {
+    cfg: ClawdbotConfig;
+    to: string;
+    cardId: string;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+    accountId?: string;
+}): Promise<FeishuSendResult>;
+/**
+ * Close (or open) the streaming mode on a CardKit card.
+ *
+ * Must be called after streaming is complete to restore normal card
+ * behaviour (forwarding, interaction callbacks, etc.).
+ */
+export declare function setCardStreamingMode(params: {
+    cfg: ClawdbotConfig;
+    cardId: string;
+    streamingMode: boolean;
+    sequence: number;
+    accountId?: string;
+}): Promise<void>;

package/src/card/cardkit.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * CardKit streaming APIs for Lark/Feishu.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCardEntity = createCardEntity;
+exports.streamCardContent = streamCardContent;
+exports.updateCardKitCard = updateCardKitCard;
+exports.updateCardKitCardForAuth = updateCardKitCardForAuth;
+exports.sendCardByCardId = sendCardByCardId;
+exports.setCardStreamingMode = setCardStreamingMode;
+const lark_client_1 = require("../core/lark-client.js");
+const lark_logger_1 = require("../core/lark-logger.js");
+const message_unavailable_1 = require("../core/message-unavailable.js");
+const targets_1 = require("../core/targets.js");
+const card_error_1 = require("./card-error.js");
+const log = (0, lark_logger_1.larkLogger)('card/cardkit');
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * 记录 CardKit API 响应日志，检测错误码并抛出异常。
+ *
+ * 默认 fail-fast：body-level 非零 code 视为业务错误，立即抛出，
+ * 由调用方（streaming-card-controller 等）统一走 catch → guard 处理。
+ */
+function logCardKitResponse(params) {
+    const { resp, api, context } = params;
+    const { code, msg } = resp;
+    log.info(`cardkit ${api} response`, { code, msg, context });
+    if (code && code !== 0) {
+        log.warn(`cardkit ${api} FAILED`, {
+            code,
+            msg,
+            context,
+            fullResponse: resp,
+        });
+        throw new card_error_1.CardKitApiError({ api, code, msg: msg ?? '', context });
+    }
+}
+// ---------------------------------------------------------------------------
+// CardKit streaming APIs
+// ---------------------------------------------------------------------------
+/**
+ * Create a card entity via the CardKit API.
+ *
+ * Returns the card_id directly, bypassing the idConvert step.
+ * The card can then be sent via IM API and streamed via CardKit.
+ */
+async function createCardEntity(params) {
+    const { cfg, card, accountId } = params;
+    const client = lark_client_1.LarkClient.fromCfg(cfg, accountId).sdk;
+    // SDK 返回类型不完整，运行时包含 code/msg/data 字段
+    const response = (await client.cardkit.v1.card.create({
+        data: {
+            type: 'card_json',
+            data: JSON.stringify(card),
+        },
+    }));
+    // 兼容不同 SDK 包装层：优先 data.card_id，回退顶层 card_id
+    const cardId = (response.data?.card_id ?? response.card_id) ?? null;
+    logCardKitResponse({
+        resp: response,
+        api: 'card.create',
+        context: `cardId=${cardId}`,
+    });
+    return cardId;
+}
+/**
+ * Stream text content to a specific card element using the CardKit API.
+ *
+ * The card automatically diffs the new content against the previous
+ * content and renders incremental changes with a typewriter animation.
+ *
+ * @param params.cardId    - CardKit card ID (from `convertMessageToCardId`).
+ * @param params.elementId - The element ID to update (e.g. `STREAMING_ELEMENT_ID`).
+ * @param params.content   - The full cumulative text (not a delta).
+ * @param params.sequence  - Monotonically increasing sequence number.
+ */
+async function streamCardContent(params) {
+    const { cfg, cardId, elementId, content, sequence, accountId } = params;
+    const client = lark_client_1.LarkClient.fromCfg(cfg, accountId).sdk;
+    // SDK 返回类型不完整，运行时包含 code/msg 字段
+    const resp = (await client.cardkit.v1.cardElement.content({
+        data: { content, sequence },
+        path: { card_id: cardId, element_id: elementId },
+    }));
+    logCardKitResponse({
+        resp,
+        api: 'cardElement.content',
+        context: `seq=${sequence}, contentLen=${content.length}`,
+    });
+}
+/**
+ * Fully replace a card using the CardKit API.
+ *
+ * Used for the final "complete" state update (with action buttons, green
+ * header, etc.) after streaming finishes.
+ *
+ * @param params.cardId   - CardKit card ID.
+ * @param params.card     - The new card JSON content.
+ * @param params.sequence - Monotonically increasing sequence number.
+ */
+async function updateCardKitCard(params) {
+    const { cfg, cardId, card, sequence, accountId } = params;
+    const client = lark_client_1.LarkClient.fromCfg(cfg, accountId).sdk;
+    // SDK 返回类型不完整，运行时包含 code/msg 字段
+    const resp = (await client.cardkit.v1.card.update({
+        data: {
+            card: { type: 'card_json', data: JSON.stringify(card) },
+            sequence,
+        },
+        path: { card_id: cardId },
+    }));
+    logCardKitResponse({
+        resp,
+        api: 'card.update',
+        context: `seq=${sequence}, cardId=${cardId}`,
+    });
+}
+async function updateCardKitCardForAuth(params) {
+    return updateCardKitCard(params);
+}
+/**
+ * Send an interactive card message by referencing a CardKit card_id.
+ *
+ * The content format is: {"type":"card","data":{"card_id":"xxx"}}
+ * This links the IM message to the CardKit card entity, enabling
+ * streaming updates via cardElement.content().
+ */
+async function sendCardByCardId(params) {
+    const { cfg, to, cardId, replyToMessageId, replyInThread, accountId } = params;
+    const client = lark_client_1.LarkClient.fromCfg(cfg, accountId).sdk;
+    const contentPayload = JSON.stringify({
+        type: 'card',
+        data: { card_id: cardId },
+    });
+    if (replyToMessageId) {
+        // 规范化 message_id，处理合成 ID（如 "om_xxx:auth-complete"）
+        const normalizedId = (0, targets_1.normalizeMessageId)(replyToMessageId);
+        const response = await (0, message_unavailable_1.runWithMessageUnavailableGuard)({
+            messageId: normalizedId,
+            operation: 'im.message.reply(interactive.cardkit)',
+            fn: () => client.im.message.reply({
+                path: { message_id: normalizedId },
+                data: {
+                    content: contentPayload,
+                    msg_type: 'interactive',
+                    reply_in_thread: replyInThread,
+                },
+            }),
+        });
+        return {
+            messageId: response?.data?.message_id ?? '',
+            chatId: response?.data?.chat_id ?? '',
+        };
+    }
+    const target = (0, targets_1.normalizeFeishuTarget)(to);
+    if (!target) {
+        throw new Error(`[feishu-send] Invalid target: "${to}"`);
+    }
+    const receiveIdType = (0, targets_1.resolveReceiveIdType)(target);
+    const response = await client.im.message.create({
+        // SDK 类型将 receive_id_type 限定为字面量联合，但运行时接受动态值
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        params: { receive_id_type: receiveIdType },
+        data: {
+            receive_id: target,
+            msg_type: 'interactive',
+            content: contentPayload,
+        },
+    });
+    return {
+        messageId: response?.data?.message_id ?? '',
+        chatId: response?.data?.chat_id ?? '',
+    };
+}
+/**
+ * Close (or open) the streaming mode on a CardKit card.
+ *
+ * Must be called after streaming is complete to restore normal card
+ * behaviour (forwarding, interaction callbacks, etc.).
+ */
+async function setCardStreamingMode(params) {
+    const { cfg, cardId, streamingMode, sequence, accountId } = params;
+    const client = lark_client_1.LarkClient.fromCfg(cfg, accountId).sdk;
+    // SDK 返回类型不完整，运行时包含 code/msg 字段
+    const resp = (await client.cardkit.v1.card.settings({
+        data: {
+            settings: JSON.stringify({ streaming_mode: streamingMode }),
+            sequence,
+        },
+        path: { card_id: cardId },
+    }));
+    logCardKitResponse({
+        resp,
+        api: 'card.settings',
+        context: `seq=${sequence}, streaming_mode=${streamingMode}`,
+    });
+}

package/src/card/flush-controller.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Generic throttled flush controller.
+ *
+ * A pure scheduling primitive that manages timer-based throttling,
+ * mutex-guarded flushing, and reflush-on-conflict. Contains no
+ * business logic — the actual flush work is provided via a callback.
+ */
+export declare class FlushController {
+    private readonly doFlush;
+    private flushInProgress;
+    private flushResolvers;
+    private needsReflush;
+    private pendingFlushTimer;
+    private lastUpdateTime;
+    private isCompleted;
+    constructor(doFlush: () => Promise<void>);
+    /** Mark the controller as completed — no more flushes after current one. */
+    complete(): void;
+    /** Cancel any pending deferred flush timer. */
+    cancelPendingFlush(): void;
+    /** Wait for any in-progress flush to finish. */
+    waitForFlush(): Promise<void>;
+    /**
+     * Execute a flush (mutex-guarded, with reflush on conflict).
+     *
+     * If a flush is already in progress, marks needsReflush so a
+     * follow-up flush fires immediately after the current one completes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Throttled update entry point.
+     *
+     * @param throttleMs - Minimum interval between flushes (varies by
+     *   CardKit vs IM patch mode). Passed in by the caller so this
+     *   controller remains business-logic-free.
+     */
+    throttledUpdate(throttleMs: number): Promise<void>;
+    /** Overridable gate: subclasses / consumers can set via setCardMessageReady. */
+    private _cardMessageReady;
+    cardMessageReady(): boolean;
+    setCardMessageReady(ready: boolean): void;
+}