@xmanrui/dsh-im 4.20.1 → 4.21.0

package/src/channels/shared/text-harness-bridge.mjs

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+
 import { createDeferredDeliveryCoordinator, deferredOutcomeText } from './deferred-delivery-coordinator.mjs';
 import { t } from './i18n.mjs';
 import { commandHelpLines } from './command-catalog.mjs';
@@ -154,6 +156,7 @@ export class TextHarnessBridge {
   #commandTasks = new Set();
   #approvals;
   #batches = new BatchInputManager();
+  #interactionCard;
 
   constructor({
     descriptor,
@@ -167,6 +170,7 @@ export class TextHarnessBridge {
     replyTimeoutMs = 600_000,
     signal,
     keepaliveIntervalMs = 4_000,
+    interactionCard = null,
   }) {
     if (!descriptor?.key || !descriptor?.label) throw new TypeError('A channel descriptor is required');
     if (!bot || typeof bot.sendText !== 'function') throw new TypeError('A bot client is required');
@@ -182,6 +186,7 @@ export class TextHarnessBridge {
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#signal = signal;
     this.#keepaliveIntervalMs = keepaliveIntervalMs;
+    this.#interactionCard = interactionCard ?? null;
     this.#deferred = createDeferredDeliveryCoordinator({ harness, state, signal, logger,
       deliver: (entry, outcome) => this.#deliverDeferredOutcome(entry, outcome),
     });
@@ -303,7 +308,12 @@ export class TextHarnessBridge {
           return this.#enqueueMessage({
             ...normalized,
             content: batch.prompt,
-            batchSubmission: { token: batch.token },
+            // The submission is exactly the collected text; a quote or an
+            // attachment on the command itself is not part of it.
+            replyTo: null,
+            images: [],
+            files: [],
+            batchSubmission: { token: batch.token, title: batch.title },
           }, messageId, senderId, key);
         }
         return this.#finishLocalMessage(normalized, messageId, batch.message);
@@ -727,6 +737,7 @@ export class TextHarnessBridge {
         key: conversationKey,
         text,
         content,
+        titleText: batchSubmission?.title,
         contextEnhanced,
         createOptions: this.#signal ? { signal: this.#signal } : undefined,
         existsOptions: this.#signal ? { signal: this.#signal } : undefined,
@@ -744,12 +755,18 @@ export class TextHarnessBridge {
                 : progress);
             }
           } : undefined,
-          onInteraction: (interaction) => this.#handleInteraction(interaction, {
-            key: conversationKey,
-            actor: senderId,
-            target,
-            requiresMention: message.kind === 'group' && message.requiresMention !== false,
-          }),
+          onInteraction: async (interaction) => {
+            if (stream?.keepalive === true && typeof stream.stopPreview === 'function') {
+              stopKeepalive();
+              await stream.stopPreview();
+            }
+            return this.#handleInteraction(interaction, {
+              key: conversationKey,
+              actor: senderId,
+              target,
+              requiresMention: message.kind === 'group' && message.requiresMention !== false,
+            });
+          },
           onInteractionResolved: (resolution) => this.#handleInteractionResolved(resolution),
           files: message.files,
         },
@@ -920,7 +937,22 @@ export class TextHarnessBridge {
     }
   }
 
-  async #processInteractionReply(message, messageId, senderId, key, expected) {
+  /**
+   * Advance the pending interaction with one answer.
+   *
+   * `resolveAnswer` lets a caller that already knows the exact answer supply it
+   * directly. A button press uses this: replaying its label as reply text would
+   * re-parse a numeric label such as "2" as the second option, submitting a
+   * different option than the one pressed.
+   */
+  async #processInteractionReply(
+    message,
+    messageId,
+    senderId,
+    key,
+    expected,
+    { resolveAnswer } = {},
+  ) {
     if (this.#signal?.aborted) {
       message.statusReaction?.clear();
       return;
@@ -1007,7 +1039,15 @@ export class TextHarnessBridge {
 
     const question = pending.questions[pending.index];
     if (!question) return;
-    pending.answers.push(harnessAnswerForQuestion(question, text));
+    const answer = typeof resolveAnswer === 'function'
+      ? resolveAnswer(question)
+      : harnessAnswerForQuestion(question, text);
+    if (!answer) return;
+    // Retire this question's keyboard before moving on: the answer is already in,
+    // and a card left behind in the chat stays pressable after the batch advances.
+    await this.#retireInteractionCard(pending.target, pending.cardMessageId);
+    pending.cardMessageId = null;
+    pending.answers.push(answer);
     pending.index += 1;
     if (pending.index < pending.questions.length) {
       if (pending.claimedReplyMessageId === messageId) {
@@ -1084,6 +1124,114 @@ export class TextHarnessBridge {
     }
   }
 
+  /** Acknowledge a press so the client stops its spinner; never fails the answer. */
+  async #answerInteractionCallback(callback, text) {
+    if (typeof this.#bot.answerInteractionCallback !== 'function') return;
+    try {
+      await this.#bot.answerInteractionCallback(callback.callbackQueryId, text);
+    } catch (error) {
+      this.#logger.warn?.(
+        `[dsh-im:${this.#descriptor.key}] could not acknowledge a button press:`,
+        error?.message ?? error,
+      );
+    }
+  }
+
+  /** Drop a handled card's keyboard so the same press cannot be submitted twice. */
+  async #retireInteractionCard(target, providerMessageId) {
+    if (!providerMessageId || typeof this.#bot.updateInteractionCard !== 'function') return;
+    try {
+      await this.#bot.updateInteractionCard(target, providerMessageId, {
+        markup: { inline_keyboard: [] },
+      });
+    } catch (error) {
+      this.#logger.warn?.(
+        `[dsh-im:${this.#descriptor.key}] could not retire an interaction card:`,
+        error?.message ?? error,
+      );
+    }
+  }
+
+  /**
+   * Accept an inline-keyboard press. The press is replayed as the option label the
+   * text flow already understands, so a button and a typed reply share one
+   * submission path and cannot drift apart.
+   */
+  async acceptCallback(callback) {
+    if (this.#signal?.aborted) return;
+    const conversationId = cleanText(callback?.conversationId);
+    const senderId = cleanText(callback?.senderId);
+    const messageId = cleanText(callback?.messageId);
+    if (!conversationId || !senderId || !messageId || callback?.senderIsBot === true) return;
+    const kind = callback.kind === 'group' ? 'group' : 'direct';
+    const key = `${kind}:${conversationId}`;
+    const pending = this.#pendingInteractions.get(key);
+    const notice = (text) => this.#answerInteractionCallback(callback, text);
+    if (!pending) return notice(t('该问题已处理，无需再次选择。'));
+    if (pending.actor !== senderId) {
+      return notice(t('只有发起当前任务的用户可以处理这条问题。'));
+    }
+    // A press can arrive while an earlier one is still being submitted: the
+    // acknowledgement round-trip is a real window, and a user who sees no feedback
+    // presses again. Claim synchronously, before the first await, so the second
+    // press cannot advance the same question twice.
+    if (pending.submitting || pending.callbackClaimed) {
+      return notice(t('正在提交你的选择，请稍候。'));
+    }
+
+    const question = pending.questions[pending.index];
+    const parsed = this.#interactionCard?.parse?.(callback.data) ?? null;
+    const option = parsed && Array.isArray(question?.options)
+      ? question.options[parsed.optionIndex]
+      : undefined;
+    if (!question || !parsed
+      || !pending.cardNonce || parsed.nonce !== pending.cardNonce
+      || parsed.questionIndex !== pending.index
+      || !option || typeof option.label !== 'string') {
+      return notice(t('这个选项已失效，请使用最新一条问题。'));
+    }
+    // Multi-select needs a keyboard that accumulates choices and a submit action;
+    // until that exists the request keeps the text answer it has always accepted.
+    if (question.multiSelect === true) {
+      return notice(t('多选问题请直接回复文字。'));
+    }
+
+    pending.callbackClaimed = true;
+    // A press can beat the card's own send promise — Telegram delivers the update
+    // as soon as its API accepted the keyboard. Wait for delivery so the card id
+    // exists and the shared submission path can retire its keyboard.
+    await pending.presentationTask?.catch(() => undefined);
+    await notice(t('已选择：{label}', { label: option.label }));
+    await this.#processInteractionReply(
+      {
+        kind,
+        conversationId,
+        messageId,
+        senderId,
+        addressed: true,
+        content: option.label,
+        replyTarget: callback.replyTarget ?? pending.target,
+        statusReaction: null,
+      },
+      messageId,
+      senderId,
+      key,
+      pending,
+      // The press already identifies its option by index, so answer with that
+      // exact label. Replaying the label as reply text would re-parse a numeric
+      // label such as "2" as the second option and submit a different one.
+      { resolveAnswer: (current) => ({ id: current.id, selected: [option.label] }) },
+    ).catch((error) => {
+      this.#logger.error?.(
+        `[dsh-im:${this.#descriptor.key}] failed to submit a card answer:`,
+        error,
+      );
+    }).finally(() => {
+      // A failed submission rolls the question back, so let the user press again.
+      if (this.#pendingInteractions.get(key) === pending) pending.callbackClaimed = false;
+    });
+  }
+
   async #handleInteraction(interaction, {
     key,
     actor,
@@ -1166,6 +1314,11 @@ export class TextHarnessBridge {
       submitting: false,
       needsPresentation: true,
       presentationTask: null,
+      cardMessageId: null,
+      // Identity of the keyboard currently on screen, and the guard that keeps two
+      // presses of the same card from advancing one question twice.
+      cardNonce: null,
+      callbackClaimed: false,
     };
     this.#pendingInteractions.set(key, pending);
     this.#interactionKeys.set(interactionId, key);
@@ -1184,11 +1337,59 @@ export class TextHarnessBridge {
     this.#clearPendingInteraction(key, interactionId);
   }
 
+  /** Build card content for the current question, or null to keep the text flow. */
+  #interactionCardFor(pending, question) {
+    if (!this.#interactionCard || typeof this.#interactionCard.render !== 'function') return null;
+    if (typeof this.#bot.sendInteractionCard !== 'function') return null;
+    if (pending.submitting) return null;
+    let card = null;
+    try {
+      card = this.#interactionCard.render(question, {
+        questionIndex: pending.index,
+        total: pending.questions.length,
+        requiresMention: pending.requiresMention,
+        nonce: pending.cardNonce,
+      });
+    } catch (error) {
+      this.#logger.warn?.(
+        `[dsh-im:${this.#descriptor.key}] interaction card renderer failed:`,
+        error,
+      );
+      return null;
+    }
+    if (!card || typeof card.text !== 'string' || !card.text || !card.markup) return null;
+    return card;
+  }
+
   #presentInteraction(pending) {
     if (pending.presentationTask) return pending.presentationTask;
     const question = pending.questions[pending.index];
     if (!question) return Promise.resolve();
     const task = (async () => {
+      // A fresh nonce per presentation: a later question restarts its indexes at
+      // zero, so without one an old card's keyboard would answer the new question.
+      pending.cardNonce = randomUUID().slice(0, 8);
+      const card = this.#interactionCardFor(pending, question);
+      if (card) {
+        try {
+          const sent = await this.#bot.sendInteractionCard(pending.target, {
+            text: card.text,
+            markup: card.markup,
+          });
+          pending.cardMessageId = sent?.providerMessageIds?.at(-1) ?? null;
+          pending.needsPresentation = false;
+          return;
+        } catch (error) {
+          // A platform that refuses the keyboard must not lose the question:
+          // fall through to the plain-text flow this channel already had.
+          pending.cardMessageId = null;
+          this.#logger.warn?.(
+            `[dsh-im:${this.#descriptor.key}] could not deliver an interaction card; `
+              + 'falling back to plain text:',
+            error?.message ?? error,
+          );
+        }
+      }
       await this.#bot.sendText(
         pending.target,
         harnessQuestionText(

package/src/channels/shared/token-config-store.mjs

@@ -8,8 +8,24 @@ function cleanString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
-function escapePattern(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function isHexString(value, uppercase) {
+  if (typeof value !== 'string' || value.length !== 24) return false;
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    const digit = code >= 48 && code <= 57;
+    const letter = uppercase
+      ? code >= 65 && code <= 70
+      : code >= 97 && code <= 102;
+    if (!digit && !letter) return false;
+  }
+  return true;
+}
+
+function matchesTokenIdentity(value, prefix, uppercaseHex) {
+  if (typeof value !== 'string') return false;
+  const marker = `${prefix}_`;
+  if (!value.startsWith(marker)) return false;
+  return isHexString(value.slice(marker.length), uppercaseHex);
 }
 
 export function deriveTokenBotIdentity(platformId, { botPrefix, tokenRefPrefix }) {
@@ -34,8 +50,6 @@ export class TokenBotConfigStore {
   #botPrefix;
   #tokenRefPrefix;
   #normalizeBotExtension;
-  #botIdPattern;
-  #tokenRefPattern;
   #value = EMPTY_DOCUMENT;
   #writeQueue = Promise.resolve();
 
@@ -53,8 +67,6 @@ export class TokenBotConfigStore {
     this.#botPrefix = botPrefix;
     this.#tokenRefPrefix = tokenRefPrefix;
     this.#normalizeBotExtension = normalizeBotExtension;
-    this.#botIdPattern = new RegExp(`^${escapePattern(botPrefix)}_[a-f0-9]{24}$`);
-    this.#tokenRefPattern = new RegExp(`^${escapePattern(tokenRefPrefix)}_[A-F0-9]{24}$`);
   }
 
   async load() {
@@ -102,7 +114,9 @@ export class TokenBotConfigStore {
   }
 
   async remove(botId) {
-    if (!this.#botIdPattern.test(botId)) throw new TypeError(`Invalid ${this.#channel} bot id`);
+    if (!matchesTokenIdentity(botId, this.#botPrefix, false)) {
+      throw new TypeError(`Invalid ${this.#channel} bot id`);
+    }
     return this.#mutate((bots) => {
       const index = bots.findIndex((bot) => bot.botId === botId);
       if (index === -1) return null;
@@ -131,7 +145,8 @@ export class TokenBotConfigStore {
     const tokenRef = cleanString(value.tokenRef);
     const name = cleanString(value.name);
     if (!platformId || !botId || !tokenRef || !name
-      || !this.#botIdPattern.test(botId) || !this.#tokenRefPattern.test(tokenRef)) return null;
+      || !matchesTokenIdentity(botId, this.#botPrefix, false)
+      || !matchesTokenIdentity(tokenRef, this.#tokenRefPrefix, true)) return null;
     const derived = deriveTokenBotIdentity(platformId, {
       botPrefix: this.#botPrefix,
       tokenRefPrefix: this.#tokenRefPrefix,

package/src/channels/shared/workspace-session.mjs

@@ -77,6 +77,11 @@ async function createSession(harness, options) {
  * Resolve, persist, and ask through a session that belongs to the bot's
  * current workspace. A concurrent workspace switch invalidates the scoped
  * session and retries before any prompt is sent to the stale session.
+ *
+ * `titleText` names the conversation title when the prompt itself is not the
+ * user's own words -- a batch submission composes dsh-im's framing sentence and
+ * message labels into one prompt, and only the collected text may name the
+ * conversation.
  */
 export async function askInWorkspaceSession({
   harness,
@@ -84,6 +89,7 @@ export async function askInWorkspaceSession({
   key,
   text,
   content,
+  titleText,
   contextEnhanced = false,
   createOptions,
   existsOptions,
@@ -92,7 +98,7 @@ export async function askInWorkspaceSession({
 }) {
   const initialTitle = contextEnhanced
     ? initialSessionTitle({
-        text,
+        text: titleText ?? text,
         content,
         files: typeof askOptions === 'object' ? askOptions?.files : undefined,
       })

package/src/channels/slack/slack-runtime.mjs

@@ -40,7 +40,9 @@ function decodeSlackText(value) {
 
 function stripBotMention(value, botUserId) {
   return decodeSlackText(value)
-    .replace(new RegExp(`<@${botUserId}>`, 'gi'), '')
+    .split(`<@${botUserId}>`).join('')
+    .split(`<@${String(botUserId).toLowerCase()}>`).join('')
+    .split(`<@${String(botUserId).toUpperCase()}>`).join('')
     .trim();
 }
 

package/src/channels/telegram/telegram-api.mjs

@@ -55,6 +55,42 @@ function inputRichMessage(value) {
   return value;
 }
 
+/** Telegram rejects callback_data longer than 64 bytes. */
+const CALLBACK_DATA_MAX_BYTES = 64;
+
+/** Validate an inline keyboard so no oversized or malformed payload is dispatched.
+ * An empty `inline_keyboard` is accepted: that is how Telegram removes a keyboard.
+ */
+function inputReplyMarkup(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('A Telegram reply markup is required');
+  }
+  const rows = value.inline_keyboard;
+  if (!Array.isArray(rows)) {
+    throw new TypeError('Telegram reply markup requires inline_keyboard rows');
+  }
+  return {
+    inline_keyboard: rows.map((row) => {
+      if (!Array.isArray(row) || row.length === 0) {
+        throw new TypeError('Telegram inline keyboard rows must be non-empty arrays');
+      }
+      return row.map((button) => {
+        const text = cleanString(button?.text);
+        const data = cleanString(button?.callback_data);
+        if (!text || !data) {
+          throw new TypeError('Telegram inline keyboard buttons require text and callback_data');
+        }
+        if (Buffer.byteLength(data, 'utf8') > CALLBACK_DATA_MAX_BYTES) {
+          throw new TypeError(
+            `Telegram callback_data must be at most ${CALLBACK_DATA_MAX_BYTES} bytes`,
+          );
+        }
+        return { text, callback_data: data };
+      });
+    }),
+  };
+}
+
 function telegramArtifactProviderError(cause, mediaLabel = 'document') {
   const providerCode = Number(cause?.providerCode);
   const status = Number(cause?.status);
@@ -146,7 +182,7 @@ export class TelegramApi {
     const payload = {
       timeout,
       limit: 100,
-      allowed_updates: ['message'],
+      allowed_updates: ['message', 'callback_query'],
       ...(Number.isSafeInteger(offset) ? { offset } : {}),
     };
     return this.#call('getUpdates', payload, {
@@ -203,7 +239,7 @@ export class TelegramApi {
     return url;
   }
 
-  async sendMessage({ chatId, text, replyToMessageId, messageThreadId, signal }) {
+  async sendMessage({ chatId, text, replyToMessageId, messageThreadId, replyMarkup, signal }) {
     return this.#call('sendMessage', {
       chat_id: chatId,
       text,
@@ -212,6 +248,30 @@ export class TelegramApi {
         reply_parameters: { message_id: replyToMessageId, allow_sending_without_reply: true },
       } : {}),
       ...(messageThreadId ? { message_thread_id: messageThreadId } : {}),
+      ...(replyMarkup === undefined ? {} : { reply_markup: inputReplyMarkup(replyMarkup) }),
+    }, { signal });
+  }
+
+  /** Acknowledge a button press so the client stops showing its progress spinner. */
+  async answerCallbackQuery({ callbackQueryId, text, signal }) {
+    const queryId = cleanString(callbackQueryId);
+    if (!queryId) throw new TypeError('Telegram callback query id is required');
+    const notice = cleanString(text);
+    return this.#call('answerCallbackQuery', {
+      callback_query_id: queryId,
+      ...(notice ? { text: notice } : {}),
+    }, { signal });
+  }
+
+  /** Replace only the keyboard of an existing message, keeping its text intact. */
+  async editMessageReplyMarkup({ chatId, messageId, replyMarkup, signal }) {
+    if (!Number.isSafeInteger(messageId)) {
+      throw new TypeError('Telegram message id must be a safe integer');
+    }
+    return this.#call('editMessageReplyMarkup', {
+      chat_id: chatId,
+      message_id: messageId,
+      ...(replyMarkup === undefined ? {} : { reply_markup: inputReplyMarkup(replyMarkup) }),
     }, { signal });
   }
 

package/src/channels/telegram/telegram-bridge.mjs

@@ -1,3 +1,4 @@
+import { harnessQuestionText } from '../shared/harness-question.mjs';
 import { TextHarnessBridge, createTextBridgeStatus } from '../shared/text-harness-bridge.mjs';
 
 export const TELEGRAM_DESCRIPTOR = Object.freeze({
@@ -7,9 +8,73 @@ export const TELEGRAM_DESCRIPTOR = Object.freeze({
   reactions: Object.freeze({ processing: '👀', success: '👍', error: '👎' }),
 });
 
+/** One keyboard row per option; beyond this the list stops being scannable. */
+const MAX_CARD_OPTIONS = 8;
+
+/**
+ * Encode a press. Carries the presentation nonce so a keyboard left over from an
+ * earlier question cannot answer a later one — a new request restarts its indexes
+ * at zero, so the index alone would collide. Still far under Telegram's 64-byte
+ * callback_data budget, so no server-side id table is needed.
+ */
+function cardCallbackData(nonce, questionIndex, optionIndex) {
+  return `q|${nonce}|${questionIndex}|${optionIndex}`;
+}
+
+/** Parse a press produced by {@link cardCallbackData}; null for foreign payloads. */
+export function parseTelegramCardCallback(data) {
+  const match = typeof data === 'string'
+    ? /^q\|([A-Za-z0-9_-]{1,16})\|(\d{1,4})\|(\d{1,4})$/u.exec(data)
+    : null;
+  if (!match) return null;
+  return {
+    nonce: match[1],
+    questionIndex: Number(match[2]),
+    optionIndex: Number(match[3]),
+  };
+}
+
+/**
+ * Inline-keyboard presentation for single-choice questions.
+ *
+ * Returns null — leaving the plain-text flow in charge — when a keyboard cannot
+ * express every answer the request allows: no options, an unusable button label,
+ * more options than fit, or multi-select (which needs an accumulating keyboard
+ * plus a submit action this channel does not have yet).
+ */
+export const TELEGRAM_INTERACTION_CARD = Object.freeze({
+  render(question, { questionIndex = 0, total = 1, requiresMention = false, nonce } = {}) {
+    // Without an identity the press could not be attributed to this presentation.
+    if (typeof nonce !== 'string' || !nonce) return null;
+    const options = Array.isArray(question?.options) ? question.options : [];
+    if (options.length === 0 || options.length > MAX_CARD_OPTIONS) return null;
+    if (question.multiSelect === true) return null;
+    if (options.some((option) => typeof option?.label !== 'string' || !option.label.trim())) {
+      return null;
+    }
+    return {
+      text: harnessQuestionText(question, questionIndex, total, {
+        requiresMention,
+        hasButtons: true,
+      }),
+      markup: {
+        inline_keyboard: options.map((option, optionIndex) => [{
+          text: option.label,
+          callback_data: cardCallbackData(nonce, questionIndex, optionIndex),
+        }]),
+      },
+    };
+  },
+  parse: parseTelegramCardCallback,
+});
+
 export class TelegramHarnessBridge extends TextHarnessBridge {
   constructor(options) {
-    super({ descriptor: TELEGRAM_DESCRIPTOR, ...options });
+    super({
+      descriptor: TELEGRAM_DESCRIPTOR,
+      interactionCard: TELEGRAM_INTERACTION_CARD,
+      ...options,
+    });
   }
 }
 

package/src/channels/telegram/telegram-rich-message.mjs

@@ -64,10 +64,12 @@ function assertCompleteFences(markdown) {
 }
 
 function escapedMarkdown(value) {
-  return value
-    .replaceAll('&', '&')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;');
+  return Array.from(value, (character) => {
+    if (character === '&') return '&amp;';
+    if (character === '<') return '&lt;';
+    if (character === '>') return '&gt;';
+    return character;
+  }).join('');
 }
 
 function plainRichChunks(source, limit) {