dsh-caduceus 0.1.0 → 0.4.1

package/dist/interactive/question.js

@@ -0,0 +1,86 @@
+/**
+ * `user-questions/request` answerer: render one question card (buttons when a
+ * single question has 1..4 options) and resolve the first click. Free-text
+ * answers are not implemented in this version; text-only cards expire.
+ *
+ * @module dsh-caduceus/interactive/question
+ */
+import { questionCard, questionTerminalCard } from './cards.js';
+import { logPrefix } from './types.js';
+export function createQuestionAnswerer(host, contextFor) {
+    return async (request) => {
+        if (!host.config.questionCard) {
+            host.logger.warn('interactive: question skipped (questionCard disabled)');
+            throw new Error('interactive question cards are disabled');
+        }
+        const context = contextFor();
+        if (context === undefined) {
+            host.logger.warn('interactive: question skipped (no session context)');
+            throw new Error('no caduceus session context for user question');
+        }
+        let settle;
+        let fail;
+        const answer = new Promise((resolve, reject) => {
+            settle = resolve;
+            fail = reject;
+        });
+        const entry = host.pending.add({
+            kind: 'question',
+            scopeKey: context.scopeKey,
+            chatId: context.chatId,
+            ownerOpenId: context.ownerOpenId,
+            sessionId: context.sessionId,
+            createdAt: host.clock.now(),
+            resolve: (value) => settle(value),
+            reject: (error) => fail(error),
+            meta: { questions: request.questions },
+        });
+        host.logger.info(`interactive: question request id=${entry.id} questions=${request.questions.length} scope=${context.scopeKey}`);
+        const rendered = questionCard({
+            requestId: entry.id,
+            sessionId: context.sessionId,
+            questions: request.questions,
+        });
+        let timer;
+        const onAbort = () => {
+            if (host.pending.delete(entry.id) === undefined)
+                return;
+            void host
+                .updateCard(entry.cardMessageId ?? '', questionTerminalCard(request.questions[0]?.question ?? '问题', '已取消'))
+                .catch(() => undefined);
+            fail(new Error('user question cancelled'));
+        };
+        const cleanup = () => {
+            if (timer !== undefined)
+                host.clock.clearTimeout(timer);
+            request.signal?.removeEventListener('abort', onAbort);
+        };
+        entry.cleanup = cleanup;
+        host.logger.info(`interactive: question card sending chat=${logPrefix(context.chatId)}`);
+        try {
+            const sent = await host.sendCard(context.sessionId, rendered.card);
+            entry.cardMessageId = sent.messageId;
+            host.logger.info(`interactive: question card sent messageId=${logPrefix(entry.cardMessageId)} thread=${logPrefix(sent.threadId ?? '-', 8)}`);
+        }
+        catch (error) {
+            host.pending.delete(entry.id);
+            host.logger.error(`interactive: question card send failed: ${error instanceof Error ? error.message : String(error)}`);
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+        timer = host.clock.setTimeout(() => {
+            if (host.pending.delete(entry.id) === undefined)
+                return;
+            host.logger.info(`interactive: question timed out after ${host.config.timeoutMs}ms`);
+            void host
+                .updateCard(entry.cardMessageId ?? '', questionTerminalCard(request.questions[0]?.question ?? '问题', '已过期'))
+                .catch(() => undefined);
+            fail(new Error('user question timed out'));
+        }, host.config.timeoutMs);
+        if (request.signal?.aborted === true) {
+            onAbort();
+            return answer;
+        }
+        request.signal?.addEventListener('abort', onAbort, { once: true });
+        return answer;
+    };
+}

package/dist/interactive/runtime.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime that owns the pending registry, sends/patch cards, routes
+ * `card.action.trigger` clicks, and installs the two agent-scoped answerers.
+ *
+ * @module dsh-caduceus/interactive/runtime
+ */
+import type { LoggerLike } from '../logger.js';
+import { type Clock } from '../render/stream.js';
+import type { CardAction, InteractiveConfig, InteractiveContext } from './types.js';
+import { PendingRegistry } from './pending.js';
+import type { FeishuCard } from '../transport/types.js';
+export interface InteractiveRuntimeOptions {
+    readonly config: InteractiveConfig;
+    readonly logger?: LoggerLike;
+    readonly clock?: Clock;
+    sendCard(sessionId: string, card: FeishuCard): Promise<{
+        readonly messageId: string;
+        readonly threadId?: string;
+    }>;
+    updateCard(messageId: string, card: FeishuCard): Promise<void>;
+}
+export declare class InteractiveRuntime {
+    #private;
+    readonly config: InteractiveConfig;
+    readonly logger: LoggerLike;
+    readonly clock: Clock;
+    readonly pending: PendingRegistry;
+    constructor(options: InteractiveRuntimeOptions);
+    /**
+     * Register both waterfall answerers ONCE on the plugin root context, as dsh's
+     * own ACP bridge does. Ownership is decided per request from
+     * `request.agent.session.id`; requests for other agents are delegated by
+     * calling `next()`, never claimed.
+     */
+    registerRoot(rootCtx: unknown, resolve: {
+        ownsSession(sessionId: string): boolean;
+        contextFor(sessionId: string): InteractiveContext | undefined;
+    }): boolean;
+    /**
+     * Route one card click. Unknown ids are ignored; non-owners are ignored with
+     * a warning and do not resolve or patch anything.
+     */
+    handleCardAction(action: CardAction): Promise<void>;
+}

package/dist/interactive/runtime.js

@@ -0,0 +1,147 @@
+import { silentLogger } from '../logger.js';
+import { systemClock } from '../render/stream.js';
+import { describeScope, isEventScope, logPrefix } from './types.js';
+import { createApprovalAnswerer } from './approval.js';
+import { PendingRegistry } from './pending.js';
+import { createQuestionAnswerer } from './question.js';
+import { approvalTerminalCard, questionCard, questionTerminalCard } from './cards.js';
+export class InteractiveRuntime {
+    config;
+    logger;
+    clock;
+    pending = new PendingRegistry();
+    #sendCard;
+    #updateCard;
+    constructor(options) {
+        this.config = options.config;
+        this.logger = options.logger ?? silentLogger();
+        this.clock = options.clock ?? systemClock;
+        this.#sendCard = options.sendCard;
+        this.#updateCard = options.updateCard;
+    }
+    /**
+     * Register both waterfall answerers ONCE on the plugin root context, as dsh's
+     * own ACP bridge does. Ownership is decided per request from
+     * `request.agent.session.id`; requests for other agents are delegated by
+     * calling `next()`, never claimed.
+     */
+    registerRoot(rootCtx, resolve) {
+        if (!isEventScope(rootCtx)) {
+            this.logger.warn(`interactive: register skipped (not an event scope: ${describeScope(rootCtx)})`);
+            return false;
+        }
+        rootCtx.on('approval/request', async (request, next) => {
+            const sessionId = sessionIdOf(request);
+            if (sessionId === undefined || !resolve.ownsSession(sessionId)) {
+                this.logger.info(`interactive: approval request agent=${sessionId === undefined ? '?' : logPrefix(sessionId)} not ours, delegated`);
+                return next();
+            }
+            this.logger.info(`interactive: approval request agent=${logPrefix(sessionId)} claimed`);
+            const context = resolve.contextFor(sessionId);
+            return createApprovalAnswerer(this.#host(), () => context)(request, next);
+        });
+        rootCtx.on('user-questions/request', async (request, next) => {
+            const sessionId = sessionIdOf(request);
+            if (sessionId === undefined || !resolve.ownsSession(sessionId)) {
+                this.logger.info(`interactive: question request agent=${sessionId === undefined ? '?' : logPrefix(sessionId)} not ours, delegated`);
+                return next();
+            }
+            this.logger.info(`interactive: question request agent=${logPrefix(sessionId)} claimed`);
+            const context = resolve.contextFor(sessionId);
+            return createQuestionAnswerer(this.#host(), () => context)(request, next);
+        });
+        this.logger.info('interactive: answerers registered (root scope)');
+        return true;
+    }
+    /**
+     * Route one card click. Unknown ids are ignored; non-owners are ignored with
+     * a warning and do not resolve or patch anything.
+     */
+    async handleCardAction(action) {
+        const id = typeof action.value['id'] === 'string' ? action.value['id'] : undefined;
+        if (id === undefined) {
+            this.logger.info('card action ignored (unknown id)');
+            return;
+        }
+        this.logger.info(`card action id=${id} kind=${String(action.value['kind'] ?? '?')} operator=${logPrefix(action.operatorOpenId)}`);
+        const entry = this.pending.get(id);
+        if (entry === undefined) {
+            this.logger.info('card action ignored (unknown id)');
+            return;
+        }
+        if (action.operatorOpenId !== entry.ownerOpenId) {
+            this.logger.warn(`ignored card action from non-owner ${action.operatorOpenId} for ${entry.kind} ${id}`);
+            return;
+        }
+        if (entry.kind === 'question' && (action.formValue !== undefined || action.value['form'] === true)) {
+            const questions = entry.meta?.['questions'];
+            const question = questions?.[0]?.question ?? '问题';
+            const questionId = typeof action.value['questionId'] === 'string'
+                ? action.value['questionId']
+                : (questions?.[0]?.id ?? '');
+            const custom = (action.formValue?.['other'] ?? '').trim();
+            if (custom.length === 0) {
+                // Keep the pending entry and its timer: prompt again on the same card.
+                const rebuilt = questionCard({
+                    requestId: entry.id,
+                    sessionId: entry.sessionId,
+                    ...(questions === undefined ? { questions: [] } : { questions }),
+                    hint: '请填写后再提交',
+                });
+                await this.#patchTerminal(entry, rebuilt.card);
+                return;
+            }
+            this.pending.delete(id);
+            await this.#patchTerminal(entry, questionTerminalCard(question, `已填写：${custom.slice(0, 40)}`));
+            entry.resolve({ answers: [{ id: questionId, selected: [], custom }] });
+            return;
+        }
+        this.pending.delete(id);
+        if (entry.kind === 'approval') {
+            const choice = action.value['choice'] === 'allow' ? 'allow' : 'reject';
+            const outcome = choice === 'allow' ? 'allowed-once' : 'rejected';
+            await this.#patchTerminal(entry, approvalTerminalCard(String(entry.meta?.['toolName'] ?? 'tool'), outcome === 'allowed-once' ? '已允许' : '已拒绝'));
+            entry.resolve(outcome);
+            return;
+        }
+        const label = typeof action.value['label'] === 'string' ? action.value['label'] : '';
+        const questionId = typeof action.value['questionId'] === 'string' ? action.value['questionId'] : '';
+        const question = entry.meta?.['questions']?.[0]
+            ?.question ?? '问题';
+        await this.#patchTerminal(entry, questionTerminalCard(question, `已选择：${label}`));
+        entry.resolve({ answers: [{ id: questionId, selected: [label] }] });
+    }
+    async #patchTerminal(entry, card) {
+        if (entry.cardMessageId === undefined)
+            return;
+        try {
+            await this.#updateCard(entry.cardMessageId, card);
+        }
+        catch (error) {
+            this.logger.warn(`interactive card patch failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    #host() {
+        return {
+            config: this.config,
+            logger: this.logger,
+            clock: this.clock,
+            pending: this.pending,
+            sendCard: (sessionId, card) => this.#sendCard(sessionId, card),
+            updateCard: (messageId, card) => this.#updateCard(messageId, card),
+        };
+    }
+}
+/** Extract `request.agent.session.id` structurally (dsh waterfall payloads). */
+function sessionIdOf(request) {
+    if (typeof request !== 'object' || request === null)
+        return undefined;
+    const agent = request.agent;
+    if (typeof agent !== 'object' || agent === null)
+        return undefined;
+    const session = agent.session;
+    if (typeof session !== 'object' || session === null)
+        return undefined;
+    const id = session.id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}

package/dist/interactive/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared seams for caduceus interactive cards (approval + user questions).
+ *
+ * The dsh services and the Cordis waterfall are adapted structurally so unit
+ * tests never import dsh internals; the gateway wires the real transport and
+ * agent scope at the edge.
+ *
+ * @module dsh-caduceus/interactive/types
+ */
+import type { LoggerLike } from '../logger.js';
+import type { Clock } from '../render/stream.js';
+import type { CardAction, FeishuCard } from '../transport/types.js';
+export type { CardAction };
+import type { PendingRegistry } from './pending.js';
+export interface InteractiveConfig {
+    /** Send approval cards (default true). */
+    readonly approvalCard: boolean;
+    /** Send question cards (default true). */
+    readonly questionCard: boolean;
+    /** How long a card waits before it expires (ms, default 300000). */
+    readonly timeoutMs: number;
+}
+/** Where the card belongs and who may click it. */
+export interface InteractiveContext {
+    readonly scopeKey: string;
+    readonly chatId: string;
+    readonly ownerOpenId: string;
+    readonly sessionId: string;
+}
+/** A Cordis context (the plugin root or an agent scope); only `on` is needed. */
+export interface EventScopeLike {
+    on(name: string, listener: (...args: any[]) => any): unknown;
+}
+export declare function logPrefix(value: string, max?: number): string;
+/** Short, safe description of a value for the attach-skipped diagnostic. */
+export declare function describeScope(value: unknown): string;
+export declare function isEventScope(value: unknown): value is EventScopeLike;
+/** What the approval/question answerers need from the runtime. */
+export interface InteractiveHost {
+    readonly config: InteractiveConfig;
+    readonly logger: LoggerLike;
+    readonly clock: Clock;
+    readonly pending: PendingRegistry;
+    sendCard(sessionId: string, card: FeishuCard): Promise<{
+        readonly messageId: string;
+        readonly threadId?: string;
+    }>;
+    updateCard(messageId: string, card: FeishuCard): Promise<void>;
+}
+/** CardAction is defined by the transport seam. */

package/dist/interactive/types.js

@@ -0,0 +1,25 @@
+export function logPrefix(value, max = 12) {
+    return value.length <= max ? value : value.slice(0, max);
+}
+/** Short, safe description of a value for the attach-skipped diagnostic. */
+export function describeScope(value) {
+    if (value === null)
+        return 'null';
+    const type = typeof value;
+    if (type !== 'object')
+        return type;
+    let keys = [];
+    try {
+        keys = Object.keys(value).slice(0, 6);
+    }
+    catch {
+        return 'object (unreadable keys)';
+    }
+    return keys.length === 0 ? 'object keys=none' : `object keys=${keys.join(',')}`;
+}
+export function isEventScope(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.on === 'function');
+}
+/** CardAction is defined by the transport seam. */

package/dist/mentions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Leading Feishu mention stripping.
+ *
+ * Feishu renders @-mentions in message text either as `<at ...>...</at>` tags
+ * (already removed by the transport normalizer) or as placeholders such as
+ * `@_user_1` / `@_user_2`. Only mentions at the START of a message are removed:
+ * a `/command` typed after them must still be recognized, while ordinary text
+ * keeps its original form (mentions inside the body stay untouched).
+ *
+ * @module dsh-caduceus/mentions
+ */
+/** Strip only the leading mention prefix; body mentions are preserved. */
+export declare function stripLeadingMentions(text: string): string;
+/** True when the text begins with one or more mentions. */
+export declare function hasLeadingMentions(text: string): boolean;

package/dist/mentions.js

@@ -0,0 +1,21 @@
+/**
+ * Leading Feishu mention stripping.
+ *
+ * Feishu renders @-mentions in message text either as `<at ...>...</at>` tags
+ * (already removed by the transport normalizer) or as placeholders such as
+ * `@_user_1` / `@_user_2`. Only mentions at the START of a message are removed:
+ * a `/command` typed after them must still be recognized, while ordinary text
+ * keeps its original form (mentions inside the body stay untouched).
+ *
+ * @module dsh-caduceus/mentions
+ */
+/** One or more leading `@mention` tokens followed by optional whitespace. */
+const LEADING_MENTIONS = /^\s*(?:@\S+\s*)+/;
+/** Strip only the leading mention prefix; body mentions are preserved. */
+export function stripLeadingMentions(text) {
+    return text.replace(LEADING_MENTIONS, '');
+}
+/** True when the text begins with one or more mentions. */
+export function hasLeadingMentions(text) {
+    return LEADING_MENTIONS.test(text);
+}

package/dist/transport/feishu-api.d.ts

@@ -7,7 +7,7 @@
  *
  * @module dsh-caduceus/transport/feishu-api
  */
-import type { FeishuCard, InboundMessage } from './types.js';
+import type { CardAction, FeishuCard, InboundMessage } from './types.js';
 export interface CreateMessageInput {
     readonly chatId: string;
     readonly msgType: 'text' | 'interactive';
@@ -28,6 +28,12 @@ export interface FeishuApi {
     start(): Promise<void>;
     stop(): Promise<void>;
     onMessage(handler: (message: InboundMessage) => void): void;
+    /** Register the card.action.trigger callback. */
+    onCardAction?(handler: (action: CardAction) => void): void;
+    /** Add one emoji reaction; resolves the reaction id. */
+    addReaction(messageId: string, emojiType: string): Promise<string>;
+    /** Remove one reaction previously added by this bot. */
+    removeReaction(messageId: string, reactionId: string): Promise<void>;
     createMessage(input: CreateMessageInput): Promise<{
         messageId: string;
     }>;
@@ -37,6 +43,8 @@ export interface FeishuApi {
     patchCard(messageId: string, card: FeishuCard): Promise<void>;
     /** The bot's own open id, when resolved (group @ gate). */
     getBotOpenId?(): string | undefined;
+    /** Retry bot identity resolution (group @ gate). */
+    refreshBotOpenId?(): Promise<string | undefined>;
     /** Cached bot display name, resolved once at startup. */
     getBotName?(): string | undefined;
     /** Long-connection status and start time, when known. */

package/dist/transport/lark.d.ts

@@ -1,6 +1,6 @@
 import type { LoggerLike } from '../logger.js';
 import type { CreateMessageInput, FeishuApi, ReplyMessageInput } from './feishu-api.js';
-import type { FeishuCard, InboundMessage } from './types.js';
+import type { CardAction, FeishuCard, InboundMessage } from './types.js';
 export interface LarkFeishuApiOptions {
     readonly appId: string;
     readonly appSecret: string;
@@ -13,13 +13,17 @@ export declare class LarkFeishuApi implements FeishuApi {
     private readonly dispatcher;
     private readonly logger;
     private handler;
+    private cardActionHandler;
     private running;
     private botOpenId;
     private botName;
     private startedAt;
     constructor(options: LarkFeishuApiOptions);
     onMessage(handler: (message: InboundMessage) => void): void;
+    onCardAction(handler: (action: CardAction) => void): void;
     start(): Promise<void>;
+    /** Retry bot identity resolution (called again on the next group message). */
+    refreshBotOpenId(): Promise<string | undefined>;
     /** Resolve the bot's own open id once, best-effort (group @ gate). */
     private resolveBotOpenId;
     /** The bot's own open id, or `undefined` until resolved. */
@@ -36,6 +40,8 @@ export declare class LarkFeishuApi implements FeishuApi {
     replyMessage(input: ReplyMessageInput): Promise<{
         messageId: string;
     }>;
+    addReaction(messageId: string, emojiType: string): Promise<string>;
+    removeReaction(messageId: string, reactionId: string): Promise<void>;
     patchCard(messageId: string, card: FeishuCard): Promise<void>;
     private messageIdOf;
     private assertOk;

package/dist/transport/lark.js

@@ -10,7 +10,7 @@
  */
 import { Client, EventDispatcher, WSClient } from '@larksuiteoapi/node-sdk';
 import { silentLogger } from '../logger.js';
-import { normalizeMessageEvent } from './normalize.js';
+import { normalizeCardAction, normalizeMessageEvent, } from './normalize.js';
 import { formatGateLine } from '../gate.js';
 import { FeishuApiError } from './types.js';
 /** Long-connection Feishu implementation of {@link FeishuApi}. */
@@ -20,6 +20,7 @@ export class LarkFeishuApi {
     dispatcher;
     logger;
     handler;
+    cardActionHandler;
     running = false;
     botOpenId;
     botName;
@@ -29,6 +30,11 @@ export class LarkFeishuApi {
         this.client = new Client({ appId: options.appId, appSecret: options.appSecret });
         this.dispatcher = new EventDispatcher({});
         this.dispatcher.register({
+            'card.action.trigger': (data) => {
+                const action = normalizeCardAction(data);
+                if (action !== undefined)
+                    this.cardActionHandler?.(action);
+            },
             'im.message.receive_v1': (data) => {
                 const raw = data;
                 const senderType = raw.sender?.sender_type;
@@ -47,7 +53,7 @@ export class LarkFeishuApi {
                     }));
                     return;
                 }
-                const message = normalizeMessageEvent(raw);
+                const message = normalizeMessageEvent(raw, this.botOpenId);
                 if (message === undefined) {
                     this.logger.debug('ignoring unsupported Feishu message event');
                     return;
@@ -60,6 +66,9 @@ export class LarkFeishuApi {
     onMessage(handler) {
         this.handler = handler;
     }
+    onCardAction(handler) {
+        this.cardActionHandler = handler;
+    }
     async start() {
         if (this.running)
             return;
@@ -69,6 +78,11 @@ export class LarkFeishuApi {
         this.startedAt = Date.now();
         this.logger.info('feishu long connection started');
     }
+    /** Retry bot identity resolution (called again on the next group message). */
+    async refreshBotOpenId() {
+        await this.resolveBotOpenId();
+        return this.botOpenId;
+    }
     /** Resolve the bot's own open id once, best-effort (group @ gate). */
     async resolveBotOpenId() {
         try {
@@ -134,6 +148,24 @@ export class LarkFeishuApi {
         }));
         return { messageId: this.messageIdOf(response, 'im.v1.message.reply') };
     }
+    async addReaction(messageId, emojiType) {
+        const response = (await this.client.im.v1.messageReaction.create({
+            data: { reaction_type: { emoji_type: emojiType } },
+            path: { message_id: messageId },
+        }));
+        this.assertOk(response, 'im.v1.message.reaction.create');
+        const reactionId = response.data?.reaction_id;
+        if (reactionId === undefined || reactionId.length === 0) {
+            throw new FeishuApiError('feishu im.v1.message.reaction.create returned no reaction_id', -1);
+        }
+        return reactionId;
+    }
+    async removeReaction(messageId, reactionId) {
+        const response = (await this.client.im.v1.messageReaction.delete({
+            path: { message_id: messageId, reaction_id: reactionId },
+        }));
+        this.assertOk(response, 'im.v1.message.reaction.delete');
+    }
     async patchCard(messageId, card) {
         const response = (await this.client.im.v1.message.patch({
             data: { content: JSON.stringify(card) },

package/dist/transport/normalize.d.ts

@@ -1,24 +1,4 @@
-/**
- * Pure normalization of a Feishu `im.message.receive_v1` payload.
- *
- * The topic identity is the whole point of this module: the bridge keys
- * sessions by `(chatId, threadId)`, and the bot must answer in the same topic
- * (design doc A6). Feishu puts the topic id in `thread_id`; older/related
- * shapes only carry `root_id`, so the rule is:
- *
- *     threadId = message.thread_id ?? message.root_id
- *
- * Non-human senders (`sender.sender_type !== 'user'`) are dropped FIRST, before
- * any other judgement: a bot/app event (e.g. an app self-improvement notice)
- * must never become a session prompt or a fallback title. Feishu events from
- * humans carry `sender_type: 'user'`; a missing sender_type is treated as
- * non-human on purpose (fail closed).
- *
- * Mention open ids are preserved so the bridge can enforce the group @ gate.
- *
- * @module dsh-caduceus/transport/normalize
- */
-import type { InboundMessage } from './types.js';
+import type { CardAction, InboundMessage } from './types.js';
 /** Structural subset of the SDK's `RawMessageEvent` (no SDK import needed). */
 export interface RawMessageEventLike {
     readonly sender?: {
@@ -39,6 +19,7 @@ export interface RawMessageEventLike {
         readonly parent_id?: string;
         readonly mentions?: readonly {
             readonly key?: string;
+            readonly name?: string;
             readonly id?: {
                 readonly open_id?: string;
             };
@@ -51,4 +32,23 @@ export interface RawMessageEventLike {
  * @returns the normalized message, or `undefined` for unsupported/malformed
  *   payloads or empty text.
  */
-export declare function normalizeMessageEvent(raw: RawMessageEventLike): InboundMessage | undefined;
+export declare function normalizeMessageEvent(raw: RawMessageEventLike, botOpenId?: string): InboundMessage | undefined;
+/** Raw `card.action.trigger` payload fields used by the surface. */
+export interface RawCardActionLike {
+    readonly open_id?: string;
+    readonly operator?: {
+        readonly open_id?: string;
+    };
+    readonly open_message_id?: string;
+    readonly open_chat_id?: string;
+    readonly context?: {
+        readonly open_message_id?: string;
+        readonly open_chat_id?: string;
+    };
+    readonly action?: {
+        readonly value?: Record<string, unknown>;
+        readonly form_value?: Record<string, unknown>;
+    };
+}
+/** Normalize Feishu's card click into the transport's CardAction. */
+export declare function normalizeCardAction(raw: RawCardActionLike): CardAction | undefined;