dsh-caduceus 0.1.1 → 0.4.1

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;

package/dist/transport/normalize.js

@@ -1,4 +1,25 @@
-const MENTION_PATTERN = /<at[^>]*>.*?<\/at>/g;
+/**
+ * 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 { stripLeadingMentions } from '../mentions.js';
+const AT_TAG_PATTERN = /<at[^>]*>(.*?)<\/at>/gs;
 /** Message types the v0.1 surface handles (attachments are v0.2). */
 const SUPPORTED_MESSAGE_TYPES = new Set(['text']);
 /**
@@ -7,7 +28,7 @@ const SUPPORTED_MESSAGE_TYPES = new Set(['text']);
  * @returns the normalized message, or `undefined` for unsupported/malformed
  *   payloads or empty text.
  */
-export function normalizeMessageEvent(raw) {
+export function normalizeMessageEvent(raw, botOpenId) {
     // Priority #1: only human messages may enter a session.
     const senderType = raw.sender?.sender_type;
     if (senderType !== 'user')
@@ -25,7 +46,44 @@ export function normalizeMessageEvent(raw) {
     catch {
         return undefined;
     }
-    text = text.replace(MENTION_PATTERN, ' ').replace(/\r\n?/g, '\n').trim();
+    // Preserve the display text inside <at> tags first: key -> @name replacement
+    // below needs the placeholder text to still be present.
+    text = text.replace(AT_TAG_PATTERN, (_match, inner) => ` @${inner.trim().replace(/^@/, '')} `);
+    text = text.replace(/\r\n?/g, '\n');
+    const rawMentions = message.mentions ?? [];
+    const entries = rawMentions
+        .map((mention) => ({
+        key: mention.key,
+        name: mention.name,
+        openId: mention.id?.open_id,
+    }))
+        .filter((entry) => entry.key !== undefined || entry.name !== undefined || entry.openId !== undefined);
+    if (entries.length === 0) {
+        // No mention metadata: keep the previous behaviour (strip placeholders).
+        text = text.trim();
+        text = stripLeadingMentions(text).trim();
+    }
+    else {
+        // 1) Remove the bot's own mention(s) entirely (agent need not see "@self").
+        for (const entry of entries) {
+            const own = botOpenId !== undefined && botOpenId.length > 0 && entry.openId === botOpenId;
+            if (!own)
+                continue;
+            if (entry.key !== undefined && entry.key.length > 0)
+                text = text.split(entry.key).join(' ');
+            if (entry.name !== undefined && entry.name.length > 0)
+                text = text.split(`@${entry.name}`).join(' ');
+        }
+        // 2) Replace remaining placeholder keys with @display-name (longest first,
+        // so @_user_10 is never clobbered by @_user_1).
+        const replaceable = entries
+            .filter((entry) => entry.name !== undefined && entry.name.length > 0 && entry.key !== undefined)
+            .sort((left, right) => (right.key?.length ?? 0) - (left.key?.length ?? 0));
+        for (const entry of replaceable) {
+            text = text.split(entry.key).join(`@${entry.name}`);
+        }
+        text = text.replace(/[ \t]{2,}/g, ' ').trim();
+    }
     if (text.length === 0)
         return undefined;
     const threadId = firstNonEmpty(message.thread_id, message.root_id);
@@ -52,3 +110,25 @@ function firstNonEmpty(...values) {
     }
     return undefined;
 }
+/** Normalize Feishu's card click into the transport's CardAction. */
+export function normalizeCardAction(raw) {
+    const operatorOpenId = raw.operator?.open_id ?? raw.open_id ?? '';
+    const messageId = raw.context?.open_message_id ?? raw.open_message_id ?? '';
+    const chatId = raw.context?.open_chat_id ?? raw.open_chat_id ?? '';
+    const value = raw.action?.value;
+    if (operatorOpenId.length === 0 || messageId.length === 0)
+        return undefined;
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const rawForm = raw.action?.form_value;
+    const formValue = typeof rawForm === 'object' && rawForm !== null
+        ? Object.fromEntries(Object.entries(rawForm).filter((entry) => typeof entry[1] === 'string'))
+        : undefined;
+    return {
+        operatorOpenId,
+        messageId,
+        chatId,
+        value,
+        ...(formValue === undefined || Object.keys(formValue).length === 0 ? {} : { formValue }),
+    };
+}

package/dist/transport/reliable.d.ts

@@ -1,6 +1,6 @@
 import { type LoggerLike } from '../logger.js';
 import type { FeishuApi } from './feishu-api.js';
-import type { FeishuCard, InboundMessage, ReplyOptions, ReplyPayload, SendOptions, SentMessage, Transport } from './types.js';
+import type { CardAction, FeishuCard, InboundMessage, ReplyOptions, ReplyPayload, SendOptions, SentMessage, Transport } from './types.js';
 export interface ReliableTransportOptions {
     readonly logger?: LoggerLike;
     /** Idempotency-key factory (injectable for deterministic tests). */
@@ -16,8 +16,10 @@ export declare class ReliableTransport implements Transport {
     start(): Promise<void>;
     stop(): Promise<void>;
     onMessage(handler: (message: InboundMessage) => void): void;
+    onCardAction(handler: (action: CardAction) => void): void;
     /** Forward the bot open id when the underlying API resolved one. */
     getBotOpenId(): string | undefined;
+    refreshBotOpenId(): Promise<string | undefined>;
     getBotName(): string | undefined;
     getConnectionStatus(): {
         readonly ready: boolean;
@@ -30,6 +32,8 @@ export declare class ReliableTransport implements Transport {
     };
     sendText(chatId: string, text: string, options?: SendOptions): Promise<SentMessage>;
     sendCard(chatId: string, card: FeishuCard, options?: SendOptions): Promise<SentMessage>;
+    addReaction(messageId: string, emojiType: string): Promise<string>;
+    removeReaction(messageId: string, reactionId: string): Promise<void>;
     updateCard(messageId: string, card: FeishuCard): Promise<void>;
     reply(chatId: string, messageId: string, payload: ReplyPayload, options?: ReplyOptions): Promise<SentMessage>;
 }

package/dist/transport/reliable.js

@@ -37,10 +37,16 @@ export class ReliableTransport {
     onMessage(handler) {
         this.api.onMessage(handler);
     }
+    onCardAction(handler) {
+        this.api.onCardAction?.(handler);
+    }
     /** Forward the bot open id when the underlying API resolved one. */
     getBotOpenId() {
         return this.api.getBotOpenId?.();
     }
+    refreshBotOpenId() {
+        return this.api.refreshBotOpenId?.() ?? Promise.resolve(this.api.getBotOpenId?.());
+    }
     getBotName() {
         return this.api.getBotName?.();
     }
@@ -94,6 +100,12 @@ export class ReliableTransport {
             uuid: options.uuid ?? this.uuidFactory(),
         }));
     }
+    addReaction(messageId, emojiType) {
+        return this.api.addReaction(messageId, emojiType);
+    }
+    removeReaction(messageId, reactionId) {
+        return this.api.removeReaction(messageId, reactionId);
+    }
     async updateCard(messageId, card) {
         assertUpdateMulti(card);
         await this.#recordVoid('卡片', () => this.api.patchCard(messageId, card));

package/dist/transport/types.d.ts

@@ -47,6 +47,15 @@ export interface InboundMessage {
     /** Unix epoch milliseconds from Feishu; `0` when the event omitted it. */
     readonly createdAt: number;
 }
+/** One interactive-card button click, normalized for the bridge. */
+export interface CardAction {
+    readonly operatorOpenId: string;
+    readonly messageId: string;
+    readonly chatId: string;
+    readonly value: Record<string, unknown>;
+    /** Feishu form fields submitted with the action (`action.form_value`). */
+    readonly formValue?: Readonly<Record<string, string>>;
+}
 /** A created message. */
 export interface SentMessage {
     readonly messageId: string;
@@ -110,11 +119,17 @@ export interface Transport {
     sendText(chatId: string, text: string, options?: SendOptions): Promise<SentMessage>;
     sendCard(chatId: string, card: FeishuCard, options?: SendOptions): Promise<SentMessage>;
     updateCard(messageId: string, card: FeishuCard): Promise<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>;
     /**
      * The bot's own open id when known (needed for the group @ gate). Optional:
      * fake transports may omit it, and the real one resolves it lazily.
      */
     getBotOpenId?(): string | undefined;
+    /** Retry bot identity resolution (group @ gate). */
+    refreshBotOpenId?(): Promise<string | undefined>;
     /** Cached bot display name (resolved at startup; no extra API call). */
     getBotName?(): string | undefined;
     /** Long-connection status/start time, when known. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-caduceus",
-  "version": "0.1.1",
+  "version": "0.4.1",
   "description": "Feishu/Lark surface plugin for DeepSeek Harness (dsh): one topic per session, SOUL persona sync, streaming process cards, /status and /doctor.",
   "type": "module",
   "main": "./dist/index.js",