@xmanrui/dsh-im 2.4.0 → 2.6.0

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

@@ -49,10 +49,17 @@ import {
   createDeliveryReceipt,
   providerMessageIdsFor,
 } from '../shared/semantic/delivery.mjs';
+import {
+  channelDeliveryFailure,
+  clearLastMessageFailure,
+  messageFailureText,
+  setLastMessageFailure,
+} from '../shared/message-failure.mjs';
 import { t } from '../shared/i18n.mjs';
 
 const INTERACTION_RESOLVED_TEXT = () => t('这个问题已在其他客户端处理，无需再次回答。');
-const GENERIC_PROCESSING_ERROR = () => t('消息处理失败，请稍后重试。');
+const DEFAULT_TYPING_KEEPALIVE_MS = 5_000;
+const TYPING_RETRY_DELAY_MS = 60_000;
 
 const HELP_TEXT = () => [
   t('微信已连接 DeepSeek Harness。'),
@@ -130,16 +137,6 @@ function canClaimInteractionReply(message, pending) {
     && nonEmptyString(extractWeixinText(message));
 }
 
-function safeMessageError(error, userMessage = GENERIC_PROCESSING_ERROR()) {
-  const diagnostic = imagePromptDiagnostic(error);
-  return {
-    code: diagnostic?.code ?? 'message-processing-failed',
-    reason: diagnostic?.reason ?? 'UNKNOWN',
-    message: diagnostic?.userMessage ?? userMessage,
-    at: Date.now(),
-  };
-}
-
 function artifactFailureText(fileName, error) {
   const name = String(fileName ?? t('结果文件')).replace(/[\r\n]+/g, ' ').trim() || t('结果文件');
   switch (error?.code) {
@@ -186,6 +183,7 @@ export class WeixinHarnessBridge {
   #logger;
   #replyTimeoutMs;
   #maxMessageChars;
+  #typingKeepaliveMs;
   #signal;
   #queues = new Map();
   #pendingInteractions = new Map();
@@ -195,6 +193,14 @@ export class WeixinHarnessBridge {
   #commandTasks = new Set();
   #approvals;
   #batchInputs = new BatchInputManager();
+  #typingTicket = null;
+  #typingTarget = null;
+  #typingTimer = null;
+  #typingGeneration = 0;
+  #typingTail = Promise.resolve();
+  #typingClosed = false;
+  #typingRetryAt = 0;
+  #typingTicketStale = false;
 
   constructor({
     api,
@@ -207,11 +213,15 @@ export class WeixinHarnessBridge {
     logger = console,
     replyTimeoutMs = 600_000,
     maxMessageChars = DEFAULT_WEIXIN_MAX_MESSAGE_CHARS,
+    typingKeepaliveMs = DEFAULT_TYPING_KEEPALIVE_MS,
     signal,
   }) {
     if (!api || typeof api.sendText !== 'function') throw new TypeError('Weixin API is required');
     if (!baseUrl || !token || !ownerUserId) throw new TypeError('Weixin account credentials are required');
     if (!harness || !state) throw new TypeError('Harness client and state store are required');
+    if (!Number.isFinite(typingKeepaliveMs) || typingKeepaliveMs <= 0) {
+      throw new TypeError('typingKeepaliveMs must be a positive number');
+    }
     this.#api = api;
     this.#baseUrl = baseUrl;
     this.#token = token;
@@ -222,6 +232,7 @@ export class WeixinHarnessBridge {
     this.#logger = logger;
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#maxMessageChars = maxMessageChars;
+    this.#typingKeepaliveMs = typingKeepaliveMs;
     this.#signal = signal;
     this.#approvals = new HarnessApprovalQueue({ label: 'weixin', logger });
   }
@@ -268,6 +279,7 @@ export class WeixinHarnessBridge {
         return this.#finishBatchResult(
           message,
           messageId,
+          key,
           sender,
           contextToken,
           runId,
@@ -294,9 +306,12 @@ export class WeixinHarnessBridge {
       ).catch((error) => {
         if (error?.code === 'turn-stopped' || this.#signal?.aborted) return;
         this.#status.lastError = error?.message ?? String(error);
-        this.#status.lastMessageError = safeMessageError(error);
-        this.#logger.error?.('[dsh-weixin] failed to process a command:', error);
-        return this.#send(sender, GENERIC_PROCESSING_ERROR(), contextToken, runId)
+        const failure = setLastMessageFailure(this.#status, error);
+        this.#logger.error?.(
+          `[dsh-weixin] failed to process a command [${failure.referenceId}]:`,
+          error,
+        );
+        return this.#sendOutOfBand(key, sender, messageFailureText(failure), contextToken, runId)
           .catch(() => undefined);
       }).finally(() => {
         this.#acceptedMessageIds.delete(messageId);
@@ -386,7 +401,7 @@ export class WeixinHarnessBridge {
     return current;
   }
 
-  #finishBatchResult(message, messageId, sender, contextToken, runId, result) {
+  #finishBatchResult(message, messageId, key, sender, contextToken, runId, result) {
     let task;
     task = Promise.resolve().then(async () => {
       if (this.#state.hasSeen(messageId)) return;
@@ -394,16 +409,18 @@ export class WeixinHarnessBridge {
       this.#status.messagesReceived += 1;
       this.#status.lastMessageAt = new Date().toISOString();
       if (result.message) {
-        await this.#send(sender, result.message, contextToken, runId);
+        await this.#sendOutOfBand(key, sender, result.message, contextToken, runId);
       }
       this.#status.lastError = null;
-      this.#status.lastMessageError = null;
     }).catch(async (error) => {
       if (this.#signal?.aborted) return;
       this.#status.lastError = error?.message ?? String(error);
-      this.#status.lastMessageError = safeMessageError(error);
-      this.#logger.error?.('[dsh-weixin] failed to process a batch input message:', error);
-      await this.#send(sender, GENERIC_PROCESSING_ERROR(), contextToken, runId)
+      const failure = setLastMessageFailure(this.#status, error);
+      this.#logger.error?.(
+        `[dsh-weixin] failed to process a batch input message [${failure.referenceId}]:`,
+        error,
+      );
+      await this.#sendOutOfBand(key, sender, messageFailureText(failure), contextToken, runId)
         .catch(() => undefined);
     }).finally(() => {
       this.#acceptedMessageIds.delete(messageId);
@@ -421,9 +438,15 @@ export class WeixinHarnessBridge {
       )),
       ...this.#approvalTasks,
       ...this.#commandTasks,
+      this.#typingTail,
     ]);
   }
 
+  async close() {
+    this.#typingClosed = true;
+    await this.#stopTyping({ signal: AbortSignal.timeout(5_000) });
+  }
+
   async #processFastCommand(
     message,
     messageId,
@@ -454,10 +477,14 @@ export class WeixinHarnessBridge {
       ]);
     }
     for (const reply of result?.messages ?? [result?.message]) {
-      if (reply) await this.#send(sender, reply, contextToken, runId);
+      if (!reply) continue;
+      if (result?.stopped) {
+        await this.#send(sender, reply, contextToken, runId);
+      } else {
+        await this.#sendOutOfBand(key, sender, reply, contextToken, runId);
+      }
     }
     this.#status.lastError = null;
-    this.#status.lastMessageError = null;
   }
 
   async #process(message, key, {
@@ -483,6 +510,7 @@ export class WeixinHarnessBridge {
     const contextToken = typeof message.context_token === 'string' ? message.context_token : undefined;
     const runId = typeof message.run_id === 'string' ? message.run_id : undefined;
     let batchSettled = batchSubmission === null;
+    let promptRecorded = false;
     try {
       const promptMessage = preparedMessage ?? weixinInboundMessage(message, this.#api);
       const text = promptMessage.content;
@@ -537,12 +565,15 @@ export class WeixinHarnessBridge {
         return;
       }
 
-      const content = hasImages
-        ? await promptContentForMessage(promptMessage, { signal: this.#signal })
-        : undefined;
       let answer;
       let artifacts = [];
+      await this.#startTyping(sender, contextToken);
       try {
+        const content = hasImages
+          ? await promptContentForMessage(promptMessage, { signal: this.#signal })
+          : undefined;
+        await this.#state.markSeen(messageId);
+        promptRecorded = true;
         ({ answer, artifacts = [] } = await askInWorkspaceSession({
           harness: this.#harness,
           state: this.#state,
@@ -554,13 +585,17 @@ export class WeixinHarnessBridge {
             timeoutMs: this.#replyTimeoutMs,
             signal: this.#signal,
             control: { owner: this, key },
+            onUpdate: () => this.#resumeTyping(key, sender, contextToken),
             onInteraction: (interaction) => this.#handleInteraction(interaction, {
               key,
               actor: sender,
               contextToken,
               runId,
             }),
-            onInteractionResolved: (resolution) => this.#handleInteractionResolved(resolution),
+            onInteractionResolved: async (resolution) => {
+              await this.#handleInteractionResolved(resolution);
+              await this.#resumeTyping(key, sender, contextToken);
+            },
             files: promptMessage.files,
           },
         }));
@@ -570,6 +605,7 @@ export class WeixinHarnessBridge {
         }
       } finally {
         await Promise.allSettled([
+          this.#stopTyping(),
           this.#cancelPendingInteraction(key),
           this.#approvals.closeRoute(key),
         ]);
@@ -586,7 +622,7 @@ export class WeixinHarnessBridge {
           providerMessageIds: await this.#send(sender, answerText, contextToken, runId),
         });
       } catch (error) {
-        textDeliveryError = error;
+        textDeliveryError = channelDeliveryFailure(error);
       }
       const delivery = await this.#deliverArtifacts(
         sender,
@@ -597,11 +633,16 @@ export class WeixinHarnessBridge {
         textReceipt,
       );
       if (textDeliveryError && !delivery.userVisible) throw textDeliveryError;
-      await this.#state.markSeen(messageId);
+      if (textDeliveryError && delivery.artifactSendErrors === 0) {
+        setLastMessageFailure(this.#status, textDeliveryError);
+      }
+      if (!promptRecorded) await this.#state.markSeen(messageId);
       this.#status.messagesReplied += 1;
       this.#status.lastReplyAt = new Date().toISOString();
       this.#status.lastError = null;
-      this.#status.lastMessageError = null;
+      if (!textDeliveryError && delivery.artifactSendErrors === 0) {
+        clearLastMessageFailure(this.#status);
+      }
       return delivery.receipt;
     } catch (error) {
       let batchFailureMessage = null;
@@ -614,24 +655,32 @@ export class WeixinHarnessBridge {
         batchSettled = true;
       }
       if (error?.code === 'turn-stopped') {
-        await this.#state.markSeen(messageId);
+        if (!promptRecorded) await this.#state.markSeen(messageId);
         return;
       }
       if (this.#signal?.aborted) return;
       this.#status.lastError = error?.message ?? String(error);
       const userMessage = inboundFileUserMessage(error)
-        ?? imagePromptUserMessage(error)
-        ?? GENERIC_PROCESSING_ERROR();
-      this.#status.lastMessageError = safeMessageError(error, userMessage);
-      this.#logger.error?.('[dsh-weixin] failed to process an inbound message:', error);
+        ?? imagePromptUserMessage(error);
+      const imageDiagnostic = imagePromptDiagnostic(error);
+      const failure = setLastMessageFailure(this.#status, error, {
+        userMessage,
+        reason: imageDiagnostic?.reason,
+      });
+      this.#logger.error?.(
+        `[dsh-weixin] failed to process an inbound message [${failure.referenceId}]:`,
+        error,
+      );
       try {
         await this.#send(
           sender,
-          batchFailureMessage ? `${userMessage}\n\n${batchFailureMessage}` : userMessage,
+          batchFailureMessage
+            ? `${messageFailureText(failure)}\n\n${batchFailureMessage}`
+            : messageFailureText(failure),
           contextToken,
           runId,
         );
-        await this.#state.markSeen(messageId);
+        if (!promptRecorded) await this.#state.markSeen(messageId);
       } catch (sendError) {
         this.#logger.error?.('[dsh-weixin] failed to send the safe error reply:', sendError);
       }
@@ -741,7 +790,6 @@ export class WeixinHarnessBridge {
       });
       this.#clearPendingInteraction(key, pending.interactionId);
       this.#status.lastError = null;
-      this.#status.lastMessageError = null;
     } catch (error) {
       if (this.#signal?.aborted) return;
       if (error?.code === 'interaction-not-pending') {
@@ -935,20 +983,24 @@ export class WeixinHarnessBridge {
   async #handleInteractionFailure(message, messageId, error) {
     if (this.#signal?.aborted) return;
     this.#status.lastError = error?.message ?? String(error);
-    this.#status.lastMessageError = safeMessageError(error);
-    this.#logger.error?.('[dsh-weixin] failed to process an interaction reply:', error);
+    const failure = setLastMessageFailure(this.#status, error);
+    this.#logger.error?.(
+      `[dsh-weixin] failed to process an interaction reply [${failure.referenceId}]:`,
+      error,
+    );
     if (!this.#state.hasSeen(messageId)) {
       await this.#state.markSeen(messageId).catch(() => undefined);
     }
     await this.#send(
       nonEmptyString(message?.from_user_id),
-      GENERIC_PROCESSING_ERROR(),
+      messageFailureText(failure),
       nonEmptyString(message?.context_token) ?? undefined,
       nonEmptyString(message?.run_id) ?? undefined,
     ).catch(() => undefined);
   }
 
   async #send(toUserId, text, contextToken, runId) {
+    await this.#stopTyping();
     const providerMessageIds = [];
     for (const chunk of splitWeixinText(text, this.#maxMessageChars)) {
       const result = await this.#api.sendText({
@@ -965,6 +1017,164 @@ export class WeixinHarnessBridge {
     return providerMessageIds;
   }
 
+  async #sendOutOfBand(key, toUserId, text, contextToken, runId) {
+    try {
+      return await this.#send(toUserId, text, contextToken, runId);
+    } finally {
+      if (this.#queues.has(key)) {
+        await this.#resumeTyping(key, toUserId, contextToken);
+      }
+    }
+  }
+
+  #queueTyping(operation) {
+    const task = this.#typingTail
+      .catch(() => undefined)
+      .then(operation);
+    this.#typingTail = task.catch(() => undefined);
+    return task;
+  }
+
+  async #startTyping(toUserId, contextToken) {
+    const target = nonEmptyString(toUserId);
+    if (!target
+      || this.#typingClosed
+      || this.#signal?.aborted
+      || Date.now() < this.#typingRetryAt
+      || typeof this.#api.getConfig !== 'function'
+      || typeof this.#api.sendTyping !== 'function') return false;
+    if (this.#typingTarget === target) return true;
+
+    const generation = ++this.#typingGeneration;
+    try {
+      return await this.#queueTyping(async () => {
+        if (generation !== this.#typingGeneration || this.#typingClosed) return false;
+        let ticket = this.#typingTicket;
+        if (!ticket) {
+          const config = await this.#api.getConfig({
+            baseUrl: this.#baseUrl,
+            token: this.#token,
+            toUserId: target,
+            contextToken,
+            signal: this.#signal,
+          });
+          ticket = nonEmptyString(config?.typingTicket);
+          if (!ticket) {
+            this.#typingRetryAt = Date.now() + TYPING_RETRY_DELAY_MS;
+            return false;
+          }
+          if (generation !== this.#typingGeneration || this.#typingClosed) return false;
+          this.#typingTicket = ticket;
+          this.#typingRetryAt = 0;
+        }
+
+        this.#typingTarget = target;
+        await this.#api.sendTyping({
+          baseUrl: this.#baseUrl,
+          token: this.#token,
+          toUserId: target,
+          typingTicket: ticket,
+          status: 1,
+          signal: this.#signal,
+        });
+        if (generation !== this.#typingGeneration || this.#typingClosed) return false;
+        this.#typingTicketStale = false;
+        this.#typingRetryAt = 0;
+        this.#scheduleTyping(generation);
+        return true;
+      });
+    } catch (error) {
+      if (generation === this.#typingGeneration) {
+        this.#clearTypingTimer();
+        this.#typingTicketStale = Boolean(this.#typingTarget && this.#typingTicket);
+        this.#typingRetryAt = Date.now() + TYPING_RETRY_DELAY_MS;
+      }
+      if (!this.#signal?.aborted && !this.#typingClosed) {
+        this.#logger.warn?.('[dsh-weixin] typing indicator failed:', error);
+      }
+      return false;
+    }
+  }
+
+  async #stopTyping({ signal = AbortSignal.timeout(5_000) } = {}) {
+    ++this.#typingGeneration;
+    this.#clearTypingTimer();
+    const target = this.#typingTarget;
+    const ticket = this.#typingTicket;
+    const stale = this.#typingTicketStale;
+    this.#typingTarget = null;
+    if (typeof this.#api.sendTyping !== 'function') return false;
+    try {
+      return await this.#queueTyping(async () => {
+        if (!target || !ticket) return false;
+        try {
+          await this.#api.sendTyping({
+            baseUrl: this.#baseUrl,
+            token: this.#token,
+            toUserId: target,
+            typingTicket: ticket,
+            status: 2,
+            signal,
+          });
+        } finally {
+          if (stale && this.#typingTicket === ticket) this.#typingTicket = null;
+          this.#typingTicketStale = false;
+        }
+        return true;
+      });
+    } catch (error) {
+      if (!signal?.aborted) {
+        this.#logger.warn?.('[dsh-weixin] typing cancellation failed:', error);
+      }
+      return false;
+    }
+  }
+
+  #scheduleTyping(generation) {
+    this.#clearTypingTimer();
+    if (generation !== this.#typingGeneration || !this.#typingTarget || this.#typingClosed) return;
+    const timer = setTimeout(() => {
+      if (this.#typingTimer === timer) this.#typingTimer = null;
+      void this.#queueTyping(async () => {
+        if (generation !== this.#typingGeneration || !this.#typingTarget || this.#typingClosed) {
+          return false;
+        }
+        await this.#api.sendTyping({
+          baseUrl: this.#baseUrl,
+          token: this.#token,
+          toUserId: this.#typingTarget,
+          typingTicket: this.#typingTicket,
+          status: 1,
+          signal: this.#signal,
+        });
+        return true;
+      }).then((sent) => {
+        if (sent) this.#scheduleTyping(generation);
+      }).catch((error) => {
+        if (generation !== this.#typingGeneration) return;
+        this.#typingTicketStale = Boolean(this.#typingTarget && this.#typingTicket);
+        this.#typingRetryAt = Date.now() + TYPING_RETRY_DELAY_MS;
+        if (!this.#signal?.aborted && !this.#typingClosed) {
+          this.#logger.warn?.('[dsh-weixin] typing keepalive failed:', error);
+        }
+      });
+    }, this.#typingKeepaliveMs);
+    timer.unref?.();
+    this.#typingTimer = timer;
+  }
+
+  #clearTypingTimer() {
+    if (this.#typingTimer) clearTimeout(this.#typingTimer);
+    this.#typingTimer = null;
+  }
+
+  #resumeTyping(key, toUserId, contextToken) {
+    if (this.#pendingInteractions.has(key) || this.#approvals.hasPending(key)) {
+      return Promise.resolve(false);
+    }
+    return this.#startTyping(toUserId, contextToken);
+  }
+
   async #deliverArtifacts(toUserId, replyTo, artifacts, contextToken, runId, baseReceipt) {
     const sendArtifact = (method, file) => this.#api[method]({
       baseUrl: this.#baseUrl,
@@ -988,9 +1198,13 @@ export class WeixinHarnessBridge {
       sendFile: typeof this.#api.sendFile === 'function'
         ? (file) => sendArtifact('sendFile', file)
         : undefined,
-      sendFailureNotice: (artifact, error) => this.#send(
+      onFailure: (artifact, error) => setLastMessageFailure(this.#status, error, {
+        userMessage: artifactFailureText(artifact?.fileName, error),
+        reason: error?.code,
+      }),
+      sendFailureNotice: (_artifact, _error, failure) => this.#send(
         toUserId,
-        artifactFailureText(artifact?.fileName, error),
+        messageFailureText(failure),
         contextToken,
         runId,
       ),
@@ -1000,6 +1214,10 @@ export class WeixinHarnessBridge {
       + delivery.artifactsSent;
     this.#status.artifactSendErrors = (this.#status.artifactSendErrors ?? 0)
       + delivery.artifactSendErrors;
-    return { receipt: delivery.receipt, userVisible: delivery.userVisible };
+    return {
+      receipt: delivery.receipt,
+      userVisible: delivery.userVisible,
+      artifactSendErrors: delivery.artifactSendErrors,
+    };
   }
 }

package/src/channels/weixin/weixin-controller.mjs

@@ -10,6 +10,7 @@ import {
   connectionTestMessage,
   connectionTestTargetUnavailable,
 } from '../shared/connection-test.mjs';
+import { publicMessageFailure } from '../shared/message-failure.mjs';
 import { t } from '../shared/i18n.mjs';
 
 const ACTIVE_ATTEMPT_STATES = new Set([
@@ -74,20 +75,6 @@ function safeAccountError(code, message) {
   return Object.freeze({ code, message });
 }
 
-function publicMessageError(value) {
-  if (!value || typeof value !== 'object'
-    || typeof value.code !== 'string' || !value.code
-    || typeof value.reason !== 'string' || !value.reason
-    || typeof value.message !== 'string' || !value.message
-    || !Number.isFinite(value.at)) return null;
-  return {
-    code: value.code.slice(0, 64),
-    reason: value.reason.slice(0, 128),
-    message: value.message.slice(0, 500),
-    at: value.at,
-  };
-}
-
 function activationStageError(code, cause) {
   const error = new Error(`Weixin activation failed during ${code}`, { cause });
   error.name = 'WeixinActivationStageError';
@@ -377,7 +364,7 @@ export class WeixinController {
           messagesReceived: runtimeStatus?.messagesReceived ?? 0,
           messagesReplied: runtimeStatus?.messagesReplied ?? 0,
         },
-        lastMessageError: publicMessageError(runtimeStatus?.lastMessageError),
+        lastMessageError: publicMessageFailure(runtimeStatus?.lastMessageError),
         error: error ? structuredClone(error) : null,
       };
     });

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

@@ -285,6 +285,7 @@ export class WeixinRuntime {
     this.#abortController?.abort();
     this.#abortController = null;
     this.#monitor = null;
+    await bridge?.close?.();
     await monitor?.catch(() => undefined);
     await bridge?.waitForIdle();
     this.#bridge = null;

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

@@ -6,6 +6,7 @@ export const WHATSAPP_DESCRIPTOR = Object.freeze({
   label: 'WhatsApp',
   // Translated lazily: t() must run after setImHostLanguage, not at import time.
   get connectionLabel() { return t(' Web 关联设备'); },
+  reactions: Object.freeze({ processing: '👀', success: '✅', error: '❌' }),
 });
 
 export class WhatsappHarnessBridge extends TextHarnessBridge {

package/src/channels/whatsapp/whatsapp-controller.mjs

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 
 import { connectionTestMessage } from '../shared/connection-test.mjs';
 import { t } from '../shared/i18n.mjs';
+import { publicMessageFailure } from '../shared/message-failure.mjs';
 import {
   deriveWhatsappBotId,
   maskWhatsappAccount,
@@ -285,6 +286,7 @@ export class WhatsappController {
           messagesReceived: runtimeStatus?.messagesReceived ?? 0,
           messagesReplied: runtimeStatus?.messagesReplied ?? 0,
         },
+        lastMessageError: publicMessageFailure(runtimeStatus?.lastMessageError),
         accessPolicy: normalizeWhatsappAccessPolicy(config),
         error: structuredClone(this.#errors.get(config.botId) ?? null),
       };

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

@@ -246,6 +246,7 @@ export function normalizeWhatsappMessage(message, accountJid, {
     addressed: !group || fromMe || mentioned || replyToSelf,
     selfChat,
     replyTarget: { jid: remoteJid, quoted: message, selfChat },
+    reactionTarget: { jid: remoteJid, key: message.key },
   };
 }
 
@@ -411,6 +412,41 @@ export class WhatsappBotClient {
     }, 'image');
   }
 
+  async addReaction(target, emoji, { signal } = {}) {
+    if (typeof emoji !== 'string' || !emoji.trim()) {
+      throw new TypeError('A WhatsApp reaction emoji is required');
+    }
+    const reactionKey = emoji.trim();
+    await this.#sendReaction(target, reactionKey, signal);
+    return reactionKey;
+  }
+
+  removeReaction(target, _reactionKey, { signal } = {}) {
+    return this.#sendReaction(target, '', signal);
+  }
+
+  async #sendReaction(target, text, signal) {
+    if (typeof target?.jid !== 'string' || !target.jid || !target.key?.id) {
+      throw new TypeError('A WhatsApp reaction target is required');
+    }
+    const operationSignal = signal ?? this.#signal;
+    operationSignal?.throwIfAborted();
+    const messageId = randomBytes(10).toString('hex').toUpperCase();
+    if (typeof this.#outboundIds.reserve === 'function') {
+      this.#outboundIds.reserve(messageId);
+    } else {
+      this.#outboundIds.remember(messageId);
+    }
+    const pending = this.#socket.sendMessage(
+      target.jid,
+      { react: { text, key: target.key } },
+      { messageId },
+    );
+    const result = await waitWithSignal(pending, operationSignal);
+    this.#outboundIds.remember(result?.key?.id);
+    return result;
+  }
+
   async #sendArtifact(target, file, content, presentation) {
     this.#signal?.throwIfAborted();
     await this.#stopTyping(target.jid);