@xmanrui/dsh-im 4.22.0 → 4.23.0

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

@@ -64,6 +64,7 @@ import {
   providerMessageIdsFor,
 } from './semantic/delivery.mjs';
 import {
+  messageFailureDiagnostic,
   channelDeliveryFailure,
   clearLastMessageFailure,
   messageFailureText,
@@ -74,6 +75,15 @@ import { beginStatusReaction } from './status-reaction.mjs';
 const INTERACTION_RESOLVED_TEXT = '这个问题已在其他客户端处理，无需再次回答。';
 const FILE_ONLY_COMPLETION_TEXT = '任务已完成。';
 
+/**
+ * How many times one inbound message may be re-delivered after a failed turn.
+ *
+ * A failure releases the message's `markSeen` so the next poll retries it, which
+ * would otherwise loop forever on a mail that always fails. After this many
+ * attempts the mark stays and the message is treated as handled.
+ */
+const MAX_DELIVERY_ATTEMPTS = 3;
+
 function cleanText(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -83,7 +93,7 @@ function canClaimInteractionReply(message, pending, senderId) {
     && (message.kind !== 'group' || message.addressed === true)
     && !hasInboundImages(message)
     && !hasInboundFiles(message)
-    && Boolean(cleanText(message.content));
+    && Boolean(controlTextOf(message));
 }
 
 function artifactFailureText(fileName, error, descriptor) {
@@ -138,6 +148,18 @@ export function createTextBridgeStatus() {
   };
 }
 
+/**
+ * The text a channel's control commands and approval decisions are parsed from.
+ *
+ * A channel may decorate `content` for the model — the email channel prepends
+ * the mail headers so a subject line reaches the model — while `controlText`
+ * keeps the undecorated body. Without this a decorated message made `/help`
+ * and "批准" unrecognisable.
+ */
+function controlTextOf(message) {
+  return cleanText(message?.controlText ?? message?.content);
+}
+
 export class TextHarnessBridge {
   #descriptor;
   #bot;
@@ -161,6 +183,10 @@ export class TextHarnessBridge {
   #approvals;
   #batches = new BatchInputManager();
   #interactionCard;
+  // Delivery attempts per message id. A failed turn releases its `markSeen` so
+  // the next poll can retry, and this counter is what keeps that from becoming
+  // an infinite loop on a mail that always fails.
+  #deliveryAttempts = new Map();
 
   constructor({
     descriptor,
@@ -229,7 +255,11 @@ export class TextHarnessBridge {
       const decision = accessDecision ?? evaluateInboundAccess(this.#accessPolicy, {
         conversationType: kind,
         senderIds: [senderId, cleanText(normalized.senderAlternateId)].filter(Boolean),
-        text: normalized.content,
+        // The same control text the command runner below parses. A channel may
+        // decorate `content` for the model (email prepends the mail headers), and
+        // a decorated body never looks like a command — so reading `content` here
+        // recognized no command at all and skipped the command-permission gate.
+        text: controlTextOf(normalized),
         hasImages,
         hasFiles,
       });
@@ -282,7 +312,7 @@ export class TextHarnessBridge {
 
     const key = `${normalized.kind}:${normalized.conversationId}`;
     const pending = this.#pendingInteractions.get(key);
-    const text = cleanText(normalized.content);
+    const text = controlTextOf(normalized);
     const batchCommand = isBatchInputCommand(text);
     if (batchCommand && normalized.kind === 'group' && normalized.addressed === true) {
       return this.#finishLocalMessage(
@@ -362,7 +392,12 @@ export class TextHarnessBridge {
       key,
       actor: senderId,
       messageId,
-      text: hasInboundImages(normalized) || hasInboundFiles(normalized) ? '' : normalized.content,
+      // Approval decisions are parsed from the control text, exactly like the
+      // commands above: a decorated `content` hid "批准" behind the mail headers,
+      // so a plain-body approval never claimed its pending request.
+      text: hasInboundImages(normalized) || hasInboundFiles(normalized)
+        ? ''
+        : controlTextOf(normalized),
       addressed: normalized.kind !== 'group' || normalized.addressed === true,
       hasPendingQuestion: Boolean(pending),
       questionCompletion: pending?.submitting || pending?.claimedReplyMessageId
@@ -441,7 +476,7 @@ export class TextHarnessBridge {
       const failure = setLastMessageFailure(this.#status, error);
       this.#logger.error?.(
         `[dsh-im:${this.#descriptor.key}] failed to process a batch input message [${failure.referenceId}]:`,
-        error,
+        messageFailureDiagnostic(error, failure),
       );
     }).finally(() => {
       this.#acceptedMessageIds.delete(messageId);
@@ -500,7 +535,7 @@ export class TextHarnessBridge {
     const target = message.replyTarget;
     try {
       const result = await runner(
-        cleanText(message.content),
+        controlTextOf(message),
         this.#harness,
         this.#state,
         key,
@@ -550,7 +585,7 @@ export class TextHarnessBridge {
       const failure = setLastMessageFailure(this.#status, error);
       this.#logger.error?.(
         `[dsh-im:${this.#descriptor.key}] failed to process a command [${failure.referenceId}]:`,
-        error,
+        messageFailureDiagnostic(error, failure),
       );
       await this.#bot.sendText(target, messageFailureText(failure)).catch(() => undefined);
     }
@@ -615,7 +650,7 @@ export class TextHarnessBridge {
     }
 
     const target = message.replyTarget;
-    const text = cleanText(message.content);
+    const text = controlTextOf(message);
     const batchSubmission = message.batchSubmission;
     let stream = null;
     let semanticStream = false;
@@ -710,7 +745,7 @@ export class TextHarnessBridge {
         }
       }
       let content = hasImages || hasReply
-        ? await promptContentForInboundMessage(message, { signal: this.#signal })
+        ? await promptContentForInboundMessage(message, { signal: this.#signal, deferImages: true })
         : undefined;
       const snapshot = this.#acceptedMessageIds.get(messageId);
       let contextEnhanced = false;
@@ -790,6 +825,7 @@ export class TextHarnessBridge {
           },
           onInteractionResolved: (resolution) => this.#handleInteractionResolved(resolution),
           files: message.files,
+          images: message.images,
         },
       });
       stopKeepalive();
@@ -877,6 +913,8 @@ export class TextHarnessBridge {
           clearLastMessageFailure(this.#status);
         }
       }
+      // The turn produced an answer, so its retry budget is spent and reset.
+      this.#deliveryAttempts.delete(messageId);
       return delivery.receipt;
     } catch (error) {
       stopKeepalive();
@@ -934,7 +972,7 @@ export class TextHarnessBridge {
         : messageFailureText(failure);
       this.#logger.error?.(
         `[dsh-im:${this.#descriptor.key}] failed to process a message [${failure.referenceId}]:`,
-        error,
+        messageFailureDiagnostic(error, failure),
       );
       if (await presentStreamFailure(failureText)) {
         return error.deliveryReceipt;
@@ -948,6 +986,10 @@ export class TextHarnessBridge {
           sendError,
         );
       }
+      // The turn produced no answer, so this id is "attempted", not "handled".
+      // Releasing the mark lets the next poll retry it; `alreadyRecorded` means
+      // an outer caller owns the mark, so it is left alone there.
+      if (!alreadyRecorded) await this.#releaseFailedDelivery(messageId);
       return error.deliveryReceipt;
     } finally {
       stopKeepalive();
@@ -958,6 +1000,43 @@ export class TextHarnessBridge {
     }
   }
 
+  /**
+   * Release the `markSeen` of a turn that failed without delivering anything,
+   * so the next poll can pick the message up again.
+   *
+   * Bounded: a message is retried at most `MAX_DELIVERY_ATTEMPTS` times, after
+   * which the mark stays and the id becomes a tombstone. That keeps a mail that
+   * always fails from being re-executed forever, while a transient Harness
+   * outage no longer drops it permanently.
+   *
+   * Returns true when the message was released and will be retried.
+   */
+  async #releaseFailedDelivery(messageId) {
+    const attempts = (this.#deliveryAttempts.get(messageId) ?? 0) + 1;
+    if (attempts >= MAX_DELIVERY_ATTEMPTS) {
+      // Give up: keep the mark so the id is never replayed, and stop tracking
+      // it. The sender has already been told the turn failed.
+      this.#deliveryAttempts.delete(messageId);
+      this.#logger.warn?.(
+        `[dsh-im:${this.#descriptor.key}] giving up on a message after `
+        + `${attempts} failed delivery attempts; it will not be retried.`,
+      );
+      return false;
+    }
+    this.#deliveryAttempts.set(messageId, attempts);
+    if (typeof this.#state?.unmarkSeen !== 'function') return false;
+    try {
+      await this.#state.unmarkSeen(messageId);
+      return true;
+    } catch (error) {
+      this.#logger.warn?.(
+        `[dsh-im:${this.#descriptor.key}] unable to release a failed message for retry:`,
+        error,
+      );
+      return false;
+    }
+  }
+
   /**
    * Advance the pending interaction with one answer.
    *
@@ -1000,7 +1079,7 @@ export class TextHarnessBridge {
     }
 
     const target = message.replyTarget;
-    const text = cleanText(message.content);
+    const text = controlTextOf(message);
     if (!text || hasInboundImages(message) || hasInboundFiles(message)) {
       try {
         await this.#bot.sendText(target, t('请用文字回答当前问题。'));

package/src/channels/shared/token-bot-controller.mjs

@@ -1,3 +1,4 @@
+import { extractConnectionEvidence, atConnectionStage, createConnectionDiagnostics } from './connection-error.mjs';
 import { connectionTestMessage } from './connection-test.mjs';
 import { t } from './i18n.mjs';
 import { publicMessageFailure } from './message-failure.mjs';
@@ -20,6 +21,7 @@ export class TokenBotController {
   #createRuntime;
   #deleteState;
   #logger;
+  #diagnostics;
   #runtimes = new Map();
   #errors = new Map();
   #transitions = new Map();
@@ -61,6 +63,14 @@ export class TokenBotController {
     this.#createRuntime = createRuntime;
     this.#deleteState = deleteState;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: descriptor.key, logger });
+  }
+
+  get diagnostics() { return this.#diagnostics; }
+
+  #failure(error, code, message) {
+    const stage = code.startsWith('qr-') ? 'qr.begin' : code === 'activation-failed' ? 'activation' : 'connection.start';
+    return this.#diagnostics.report(error, { reuse: true, stage, publicError: { code, message } }).publicError;
   }
 
   async initialize() {
@@ -68,30 +78,27 @@ export class TokenBotController {
     for (const config of this.#configStore.list()) {
       await this.#withBotTransition(config.botId, async () => {
         if (this.#closed || this.#runtimes.get(config.botId)?.status?.ready) return;
-        const token = await this.#resolveToken(config.tokenRef);
-        if (!token) {
-          this.#errors.set(config.botId, safeError(
-            'missing-token',
-            t('{label}机器人凭据缺失，请移除后重新接入。', {
-              label: this.#descriptor.label,
-            }),
-          ));
-          return;
-        }
         try {
+          const token = await this.#resolveToken(config.tokenRef);
+          if (!token) {
+            this.#errors.set(config.botId, safeError(
+              'missing-token',
+              t('{label}机器人凭据缺失，请移除后重新接入。', {
+                label: this.#descriptor.label,
+              }),
+            ));
+            return;
+          }
           await this.#startRuntime(config, token);
           this.#errors.delete(config.botId);
         } catch (error) {
-          this.#errors.set(config.botId, safeError(
+          this.#errors.set(config.botId, this.#failure(error,
             'connection-failed',
             t('{label}连接未就绪，插件会自动重试。', {
               label: this.#descriptor.label,
             }),
           ));
-          this.#logger.warn?.(
-            `[dsh-im:${this.#descriptor.key}] bot ${config.botId} failed to initialize:`,
-            error,
-          );
+
         } finally {
           this.#touch();
         }
@@ -112,7 +119,7 @@ export class TokenBotController {
     await this.#withBotTransition(identity.botId, async () => {
       if (this.#closed) throw new Error(`${this.#descriptor.label} controller is closed`);
       const previousConfig = this.#configStore.getByPlatformId(platformId);
-      const previousToken = await this.#credentials.resolve(identity.tokenRef).catch(() => undefined);
+      const previousToken = await atConnectionStage('credential.read', () => this.#credentials.resolve(identity.tokenRef), 'credential-store');
       const config = {
         botId: identity.botId,
         platformId,
@@ -122,9 +129,9 @@ export class TokenBotController {
         createdAt: previousConfig?.createdAt ?? new Date().toISOString(),
         connectedAt: new Date().toISOString(),
       };
-      await this.#credentials.set(identity.tokenRef, normalizedToken);
+      await atConnectionStage('credential.save', () => this.#credentials.set(identity.tokenRef, normalizedToken), 'credential-store');
       try {
-        await this.#configStore.save(config);
+        await atConnectionStage('account.save', () => this.#configStore.save(config), 'account-config');
       } catch (error) {
         await this.#restoreCredential(identity.tokenRef, previousToken);
         throw error;
@@ -133,16 +140,13 @@ export class TokenBotController {
         await this.#startRuntime(config, normalizedToken);
         this.#errors.delete(identity.botId);
       } catch (error) {
-        this.#errors.set(identity.botId, safeError(
+        this.#errors.set(identity.botId, this.#failure(error,
           'connection-failed',
           t('{label}机器人已接入，消息连接暂未就绪。', {
             label: this.#descriptor.label,
           }),
         ));
-        this.#logger.warn?.(
-          `[dsh-im:${this.#descriptor.key}] bot ${identity.botId} credential connection failed:`,
-          error,
-        );
+
       }
       this.#touch();
     });
@@ -159,7 +163,7 @@ export class TokenBotController {
         await this.#startRuntime(config, token);
         this.#errors.delete(botId);
       } catch (error) {
-        this.#errors.set(botId, safeError(
+        this.#errors.set(botId, this.#failure(error,
           'connection-failed',
           t('{label}连接仍未就绪，请稍后重试。', {
             label: this.#descriptor.label,
@@ -184,12 +188,12 @@ export class TokenBotController {
       if (!token) throw new Error(`${this.#descriptor.label} bot token is missing`);
       if (this.#closed) throw new Error(`${this.#descriptor.label} controller is closed`);
       const nextConfig = update(config);
-      const savedConfig = await this.#configStore.save(nextConfig);
+      const savedConfig = await atConnectionStage('account.save', () => this.#configStore.save(nextConfig), 'account-config');
       try {
         await this.#startRuntime(savedConfig, token);
         this.#errors.delete(botId);
       } catch (error) {
-        this.#errors.set(botId, safeError(
+        this.#errors.set(botId, this.#failure(error,
           'connection-failed',
           t('{label}连接仍未就绪，请稍后重试。', {
             label: this.#descriptor.label,
@@ -244,31 +248,32 @@ export class TokenBotController {
   }
 
   async deleteBot(botId) {
+    const warnings = [];
     const config = this.#configStore.get(botId);
     if (!config) throw new Error(`Unknown ${this.#descriptor.label} bot`);
     await this.#withBotTransition(botId, async () => {
-      const previous = await this.#credentials.resolve(config.tokenRef).catch(() => undefined);
+      const previous = await atConnectionStage('credential.read', () => this.#credentials.resolve(config.tokenRef), 'credential-store');
       await this.#stopRuntime(botId);
       try {
-        await this.#credentials.unset(config.tokenRef);
-        await this.#configStore.remove(botId);
+        await atConnectionStage('credential.remove', () => this.#credentials.unset(config.tokenRef), 'credential-store');
+        await atConnectionStage('account.remove', () => this.#configStore.remove(botId), 'account-config');
       } catch (error) {
-        if (previous?.value) {
-          await this.#credentials.set(config.tokenRef, previous.value).catch(() => undefined);
-          await this.#startRuntime(config, previous.value).catch(() => undefined);
+        if (!this.#configStore.get(botId)) {
+          warnings.push(this.#diagnostics.report(error, { operation: 'bot.delete', stage: 'workspace.cleanup', warning: true,
+            publicError: { code: 'workspace-cleanup-failed', message: '账号已移除，但本地状态清理失败。' } }).publicError);
+        } else {
+          if (previous?.value) {
+            await atConnectionStage('credential.save', () => this.#credentials.set(config.tokenRef, previous.value), 'credential-store').catch(() => undefined);
+            await this.#startRuntime(config, previous.value).catch(() => undefined);
+          }
+          throw new Error(`Unable to remove the ${this.#descriptor.label} bot safely.`, { cause: error });
         }
-        throw new Error(`Unable to remove the ${this.#descriptor.label} bot safely.`, { cause: error });
       }
-      await this.#deleteState({ botId, config }).catch((error) => {
-        this.#logger.warn?.(
-          `[dsh-im:${this.#descriptor.key}] bot ${botId} state cleanup failed:`,
-          error,
-        );
-      });
+      await this.#deleteState({ botId, config }).catch(error => { warnings.push(this.#diagnostics.report(error, { reuse: true, operation: 'bot.delete', stage: 'state.cleanup', resource: 'account-state', warning: true, publicError: { code: 'cleanup-failed', message: '账号已移除，但本地状态清理失败。' } }).publicError); });
       this.#errors.delete(botId);
       this.#touch();
     });
-    return this.status();
+    return { ...this.status(), ...(warnings.length ? { warnings } : {}) };
   }
 
   status() {
@@ -309,7 +314,7 @@ export class TokenBotController {
           messagesReplied: runtimeStatus?.messagesReplied ?? 0,
         },
         lastMessageError: publicMessageFailure(runtimeStatus?.lastMessageError),
-        error: structuredClone(this.#errors.get(config.botId) ?? null),
+        error: structuredClone(runtimeStatus?.error ?? this.#errors.get(config.botId) ?? null),
       };
     });
     const connectedCount = bots.filter((bot) => bot.connected).length;
@@ -342,7 +347,7 @@ export class TokenBotController {
       } catch (error) {
         this.#logger.warn?.(
           `[dsh-im:${this.#descriptor.key}] bot ${botId} command menu refresh failed:`,
-          error,
+          extractConnectionEvidence(error).details,
         );
         return false;
       }
@@ -361,7 +366,7 @@ export class TokenBotController {
     if (this.#closed) throw new Error(`${this.#descriptor.label} controller is closed`);
     await this.#stopRuntime(config.botId);
     if (this.#closed) throw new Error(`${this.#descriptor.label} controller is closed`);
-    const runtime = await this.#createRuntime({ botId: config.botId, config, token });
+    const runtime = await atConnectionStage('runtime.prepare', () => this.#createRuntime({ botId: config.botId, config, token }));
     if (!runtime || typeof runtime.start !== 'function' || typeof runtime.stop !== 'function') {
       throw new TypeError(`createRuntime returned an invalid ${this.#descriptor.label} runtime`);
     }
@@ -381,19 +386,19 @@ export class TokenBotController {
     await runtime?.stop().catch((error) => {
       this.#logger.warn?.(
         `[dsh-im:${this.#descriptor.key}] bot ${botId} failed to stop cleanly:`,
-        error,
+        extractConnectionEvidence(error).details,
       );
     });
   }
 
   async #resolveToken(ref) {
-    const result = await this.#credentials.resolve(ref).catch(() => undefined);
+    const result = await atConnectionStage('credential.read', () => this.#credentials.resolve(ref), 'credential-store');
     return cleanString(result?.value);
   }
 
   async #restoreCredential(ref, previous) {
-    if (previous?.value) await this.#credentials.set(ref, previous.value).catch(() => undefined);
-    else await this.#credentials.unset(ref).catch(() => undefined);
+    if (previous?.value) await atConnectionStage('credential.save', () => this.#credentials.set(ref, previous.value), 'credential-store').catch(() => undefined);
+    else await atConnectionStage('credential.remove', () => this.#credentials.unset(ref), 'credential-store').catch(() => undefined);
   }
 
   #withBotTransition(botId, operation) {

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

@@ -522,7 +522,7 @@ export class SlackApi {
       });
     } catch (error) {
       if (error?.name === 'AbortError' || error?.name === 'TimeoutError') throw error;
-      throw new Error(`Slack ${method} transport failed`);
+      throw new Error(`Slack ${method} transport failed`, { cause: error });
     }
 
     if (tokenKind === 'bot') {
@@ -533,8 +533,8 @@ export class SlackApi {
     let payload;
     try {
       payload = await response.json();
-    } catch {
-      throw new Error(`Slack ${method} returned invalid JSON`);
+    } catch (cause) {
+      throw Object.assign(new Error(`Slack ${method} returned invalid JSON`, { cause }), { status: response?.status });
     }
     if (response.status === 429 && retry) {
       const seconds = Number(response.headers.get('retry-after')) || 1;