@xmanrui/dsh-im 4.22.0 → 4.23.0

package/src/channels/dingtalk/connection-error.mjs

@@ -1,3 +1,4 @@
+import { connectionErrorChain, connectionStageError } from '../shared/connection-error.mjs';
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 
@@ -62,17 +63,7 @@ export function installedDingtalkConnectionDependencies() {
   return installedDependencyVersions;
 }
 
-function errorChain(error) {
-  const chain = [];
-  const seen = new Set();
-  let current = error;
-  while (current && typeof current === 'object' && chain.length < 4 && !seen.has(current)) {
-    seen.add(current);
-    chain.push(current);
-    current = current.cause;
-  }
-  return chain;
-}
+function errorChain(error) { return connectionErrorChain(error).chain; }
 
 function statusFrom(error) {
   if (Number.isInteger(error?.status)) return error.status;
@@ -153,7 +144,9 @@ export function dingtalkRuntimeStartError(code, cause) {
   );
   error.name = 'DingtalkRuntimeStartError';
   error.code = STAGE_CODES.has(code) ? code : 'dingtalk-runtime-prepare-failed';
-  return error;
+  return connectionStageError(error, ({ 'dingtalk-harness-connect-failed': 'harness.check',
+    'dingtalk-runtime-prepare-failed': 'runtime.prepare', 'dingtalk-stream-client-load-failed': 'sdk.load',
+    'dingtalk-stream-listener-failed': 'runtime.prepare', 'dingtalk-stream-connect-failed': 'connection.start' })[error.code]);
 }
 
 /** Creates browser-safe guidance plus a redacted Host-log diagnostic for one connection failure. */

package/src/channels/dingtalk/device-auth.mjs

@@ -68,6 +68,8 @@ export class DingtalkDeviceAuthError extends Error {
     this.name = 'DingtalkDeviceAuthError';
     this.code = code;
     this.action = action;
+    if (Number.isInteger(options.status)) this.status = options.status;
+    if (Number.isFinite(options.timeoutMs)) this.timeoutMs = options.timeoutMs;
   }
 }
 
@@ -199,7 +201,7 @@ export class DingtalkDeviceAuth {
           'timeout',
           `DingTalk ${action} request timed out`,
           action,
-          { cause: error },
+          { cause: error, timeoutMs: this.#timeoutMs },
         );
       }
       if (error?.name === 'AbortError') throw error;
@@ -215,6 +217,7 @@ export class DingtalkDeviceAuth {
         'http-error',
         `DingTalk ${action} request failed`,
         action,
+        { status: response?.status },
       );
     }
     let value;

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

@@ -65,6 +65,7 @@ import {
 import { recoverAssistantTextByTimestamp } from '../shared/session-reply-recovery.mjs';
 import { DINGTALK_RECENT_OUTBOUND_MATCH_TOLERANCE_MS } from './state-store.mjs';
 import {
+  messageFailureDiagnostic,
   channelDeliveryFailure,
   clearLastMessageFailure,
   messageFailureText,
@@ -740,7 +741,7 @@ export class DingtalkHarnessBridge {
         const failure = setLastMessageFailure(this.#status, error);
         this.#logger.error?.(
           `[dsh-dingtalk] failed to process a command [${failure.referenceId}]`,
-          safeErrorDiagnostic(error),
+          messageFailureDiagnostic(error, failure),
         );
         return this.#send(sessionWebhook, messageFailureText(failure), this.#atUsersFor(message)).catch(() => undefined);
       }).finally(() => {
@@ -1207,7 +1208,7 @@ export class DingtalkHarnessBridge {
       const failure = setLastMessageFailure(this.#status, error);
       this.#logger.error?.(
         `[dsh-dingtalk] failed to process a batch input message [${failure.referenceId}]`,
-        safeErrorDiagnostic(error),
+        messageFailureDiagnostic(error, failure),
       );
       await this.#send(sessionWebhook, messageFailureText(failure)).catch(() => undefined);
     }).finally(() => {
@@ -1338,7 +1339,7 @@ export class DingtalkHarnessBridge {
         signal: this.#signal,
       });
       let content = hasInboundImages(modelMessage) || hasReply
-        ? await promptContentForInboundMessage(modelMessage, { signal: this.#signal })
+        ? await promptContentForInboundMessage(modelMessage, { signal: this.#signal, deferImages: true })
         : undefined;
       const snapshot = this.#acceptedMessageIds.get(messageId);
       let contextEnhanced = false;
@@ -1395,6 +1396,7 @@ export class DingtalkHarnessBridge {
           }),
           onInteractionResolved: (resolution) => this.#handleInteractionResolved(resolution),
           files: modelMessage.files,
+          images: modelMessage.images,
         },
       });
       if (batchSubmission) {
@@ -1486,7 +1488,7 @@ export class DingtalkHarnessBridge {
       });
       this.#logger.error?.(
         `[dsh-dingtalk] failed to process an inbound message [${failure.referenceId}]`,
-        safeErrorDiagnostic(error),
+        messageFailureDiagnostic(error, failure),
       );
       try {
         const errorText = messageFailureText(failure);

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

@@ -1,3 +1,4 @@
+import { extractConnectionEvidence, atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { randomUUID } from 'node:crypto';
 
 import {
@@ -135,6 +136,7 @@ export class DingtalkController {
   #createRuntime;
   #deleteState;
   #logger;
+  #diagnostics;
   #clock;
   #runtimes = new Map();
   #errors = new Map();
@@ -193,10 +195,17 @@ export class DingtalkController {
     this.#createRuntime = createRuntime;
     this.#deleteState = deleteState;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'dingtalk', prefix: 'DT-CONN', logger });
     this.#clock = clock;
   }
 
   /** Starts all configured DingTalk runtimes whose secrets are available. */
+  get diagnostics() { return this.#diagnostics; }
+  #failure(error, code, message) {
+    const stage = code.startsWith('poll-') ? 'qr.poll' : code === 'activation-failed' ? 'activation' : 'qr.begin';
+    return this.#diagnostics.report(error, { reuse: true, stage, publicError: { code, message } }).publicError;
+  }
+
   async initialize() {
     if (this.#closed) return this.status();
     for (const config of this.#configStore.list()) {
@@ -209,16 +218,17 @@ export class DingtalkController {
       await this.#withBotTransition(config.botId, async () => {
         const latest = this.#configStore.get(config.botId);
         if (!latest || this.#closed) return;
-        const clientSecret = await this.#resolveSecret(latest.secretRef);
-        if (!clientSecret) {
-          this.#errors.set(
-            latest.botId,
-            safeError('missing-secret', t('钉钉机器人凭据缺失，请移除后重新扫码。')),
-          );
-          this.#touch();
-          return;
-        }
+        let clientSecret;
         try {
+          clientSecret = await this.#resolveSecret(latest.secretRef);
+          if (!clientSecret) {
+            this.#errors.set(
+              latest.botId,
+              safeError('missing-secret', t('钉钉机器人凭据缺失，请移除后重新扫码。')),
+            );
+            this.#touch();
+            return;
+          }
           await this.#startRuntime(latest, clientSecret);
           this.#errors.delete(latest.botId);
         } catch (error) {
@@ -282,7 +292,7 @@ export class DingtalkController {
         record.error = safeError('cancelled', t('扫码接入已取消。'));
       } else {
         record.state = 'failed';
-        record.error = safeError('qr-start-failed', t('无法生成钉钉二维码，请稍后重试。'));
+        record.error = this.#failure(error, 'qr-start-failed', t('无法生成钉钉二维码，请稍后重试。'));
       }
       if (this.#activeAttemptId === record.id) this.#activeAttemptId = null;
       this.#touch();
@@ -307,7 +317,7 @@ export class DingtalkController {
     await this.#withBotTransition(identity.botId, async () => {
       if (this.#closed) throw abortError();
       const previousConfig = this.#configStore.getByClientId(normalizedClientId);
-      const previousSecret = await this.#credentials.resolve(identity.secretRef).catch(() => undefined);
+      const previousSecret = await atConnectionStage('credential.read', () => this.#credentials.resolve(identity.secretRef), 'credential-store');
       if (this.#closed) throw abortError();
       const config = {
         botId: identity.botId,
@@ -315,9 +325,9 @@ export class DingtalkController {
         secretRef: identity.secretRef,
         approvedSenders: previousConfig?.approvedSenders ?? [],
       };
-      await this.#credentials.set(identity.secretRef, normalizedSecret);
+      await atConnectionStage('credential.save', () => this.#credentials.set(identity.secretRef, normalizedSecret), 'credential-store');
       try {
-        await this.#configStore.save(config);
+        await atConnectionStage('account.save', () => this.#configStore.save(config), 'account-config');
       } catch (error) {
         await this.#restoreCredential(identity.secretRef, previousSecret);
         throw error;
@@ -434,30 +444,37 @@ export class DingtalkController {
 
   /** Removes one bot, its secret, runtime, and local conversation state. */
   async deleteBot(botId) {
+    const warnings = [];
     const config = this.#configStore.get(botId);
     if (!config) throw new Error('Unknown DingTalk bot');
     await this.#withBotTransition(botId, async () => {
-      const previousSecret = await this.#credentials.resolve(config.secretRef).catch(() => undefined);
+      const previousSecret = await atConnectionStage('credential.read', () => this.#credentials.resolve(config.secretRef), 'credential-store');
       await this.#stopRuntime(botId);
       try {
-        await this.#credentials.unset(config.secretRef);
-        await this.#configStore.remove(botId);
+        await atConnectionStage('credential.remove', () => this.#credentials.unset(config.secretRef), 'credential-store');
+        await atConnectionStage('account.remove', () => this.#configStore.remove(botId), 'account-config');
       } catch (error) {
-        if (cleanString(previousSecret?.value)) {
-          await this.#credentials.set(config.secretRef, previousSecret.value).catch(() => undefined);
-          await this.#startRuntime(config, previousSecret.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 (cleanString(previousSecret?.value)) {
+            await atConnectionStage('credential.save', () => this.#credentials.set(config.secretRef, previousSecret.value), 'credential-store').catch(() => undefined);
+            await this.#startRuntime(config, previousSecret.value).catch(() => undefined);
+          }
+          throw new Error('Unable to remove the DingTalk bot safely.', { cause: error });
         }
-        throw new Error('Unable to remove the DingTalk bot safely.', { cause: error });
       }
       try {
         await this.#deleteState({ botId, config });
-      } catch {
-        this.#logger.warn?.(`[dsh-dingtalk] bot ${botId} state cleanup failed`);
+      } catch (error) {
+        warnings.push(this.#diagnostics.report(error, { reuse: true, operation: 'bot.delete', stage: 'state.cleanup', warning: true,
+          publicError: { code: 'cleanup-failed', message: '账号已移除，但本地状态清理失败。' } }).publicError);
       }
       this.#errors.delete(botId);
       this.#touch();
     });
-    return this.status();
+    return { ...this.status(), ...(warnings.length ? { warnings } : {}) };
   }
 
   /** Approves one opaque pending-sender request for a bot. */
@@ -517,7 +534,7 @@ export class DingtalkController {
         currentStatus = { state: 'error' };
       }
       const connected = isRuntimeConnected(runtime, currentStatus);
-      const accountError = this.#errors.get(config.botId);
+      const accountError = currentStatus.error ?? this.#errors.get(config.botId);
       const state = connected ? 'connected' : accountError ? 'error' : 'offline';
       const approvedIds = new Set(config.approvedSenders.map((sender) => sender.staffId));
       const pending = internalPendingSenders(currentStatus)
@@ -626,7 +643,7 @@ export class DingtalkController {
         if (this.#activeAttemptId === record.id) this.#activeAttemptId = null;
       } else if (record.state === 'connecting') {
         record.state = 'failed';
-        record.error = safeError(
+        record.error = this.#failure(error,
           'activation-failed',
           t('钉钉已授权，但无法安全保存接入配置。'),
         );
@@ -634,7 +651,7 @@ export class DingtalkController {
         this.#logger.error?.('[dsh-dingtalk] bot activation failed');
       } else {
         record.state = 'pending';
-        record.error = safeError('poll-failed', t('钉钉授权查询暂时失败，正在重试。'));
+        record.error = this.#failure(error, 'poll-failed', t('钉钉授权查询暂时失败，正在重试。'));
       }
     } finally {
       this.#touch();
@@ -645,7 +662,7 @@ export class DingtalkController {
   async #activateBot(record, { clientId, clientSecret }) {
     const identity = deriveDingtalkBotIdentity(clientId);
     const previousConfig = this.#configStore.getByClientId(clientId);
-    const previousSecret = await this.#credentials.resolve(identity.secretRef).catch(() => undefined);
+    const previousSecret = await atConnectionStage('credential.read', () => this.#credentials.resolve(identity.secretRef), 'credential-store');
     const config = {
       botId: identity.botId,
       clientId,
@@ -655,12 +672,12 @@ export class DingtalkController {
     return this.#withBotTransition(identity.botId, async () => {
       const rollback = async () => {
         await this.#stopRuntime(identity.botId);
-        if (previousConfig) await this.#configStore.save(previousConfig).catch(() => undefined);
+        if (previousConfig) await atConnectionStage('account.save', () => this.#configStore.save(previousConfig), 'account-config').catch(() => undefined);
         else if (this.#configStore.get(identity.botId)) {
-          const removed = await this.#configStore.remove(identity.botId).catch(() => null);
+          const removed = await atConnectionStage('account.remove', () => this.#configStore.remove(identity.botId), 'account-config').catch(() => null);
           if (removed) {
             await this.#deleteState({ botId: identity.botId, config }).catch((cleanupError) => {
-              this.#logger.warn?.('[dsh-dingtalk] failed to clean up cancelled bot state:', cleanupError);
+              this.#logger.warn?.('[dsh-dingtalk] failed to clean up cancelled bot state:', extractConnectionEvidence(cleanupError).details);
             });
           }
         }
@@ -669,10 +686,10 @@ export class DingtalkController {
           await this.#startRuntime(previousConfig, previousSecret.value).catch(() => undefined);
         }
       };
-      await this.#credentials.set(identity.secretRef, clientSecret);
+      await atConnectionStage('credential.save', () => this.#credentials.set(identity.secretRef, clientSecret), 'credential-store');
       try {
         this.#assertAttemptActive(record);
-        await this.#configStore.save(config);
+        await atConnectionStage('account.save', () => this.#configStore.save(config), 'account-config');
         this.#assertAttemptActive(record);
       } catch (error) {
         await rollback();
@@ -703,12 +720,12 @@ export class DingtalkController {
     return this.#withBotTransition(previousConfig.botId, async () => {
       const clientSecret = await this.#resolveSecret(previousConfig.secretRef);
       if (!clientSecret) throw new Error('The DingTalk client secret is missing');
-      await this.#configStore.save(nextConfig);
+      await atConnectionStage('account.save', () => this.#configStore.save(nextConfig), 'account-config');
       try {
         await this.#startRuntime(nextConfig, clientSecret);
         this.#errors.delete(previousConfig.botId);
       } catch (error) {
-        await this.#configStore.save(previousConfig).catch(() => undefined);
+        await atConnectionStage('account.save', () => this.#configStore.save(previousConfig), 'account-config').catch(() => undefined);
         await this.#startRuntime(previousConfig, clientSecret).catch(() => undefined);
         const publicError = this.#rememberConnectionFailure({
           config: previousConfig,
@@ -730,11 +747,11 @@ export class DingtalkController {
     if (this.#closed) throw abortError();
     let runtime;
     try {
-      runtime = await this.#createRuntime({
+      runtime = await atConnectionStage('runtime.prepare', () => this.#createRuntime({
         botId: config.botId,
         config: structuredClone(config),
         clientSecret,
-      });
+      }));
     } catch (error) {
       throw dingtalkRuntimeStartError('dingtalk-runtime-prepare-failed', error);
     }
@@ -774,12 +791,10 @@ export class DingtalkController {
       clientId: config.clientId,
       clientSecret,
     });
-    this.#errors.set(config.botId, failure.publicError);
-    this.#logger.error?.(
-      `[dsh-dingtalk] ${context} [${failure.publicError.referenceId}]`,
-      failure.diagnostic,
-    );
-    return failure.publicError;
+    const reported = this.#diagnostics.report(error, { reuse: true, botId: config.botId, stage: 'connection.start', publicError: { ...failure.publicError, details: { dependencies: failure.diagnostic.dependencies, proxyConfigured: failure.diagnostic.proxy.configured } } }).publicError;
+    const visible = { ...failure.publicError, details: reported.details };
+    this.#errors.set(config.botId, visible);
+    return visible;
   }
 
   async #stopRuntime(botId) {
@@ -791,14 +806,14 @@ export class DingtalkController {
   }
 
   async #resolveSecret(secretRef) {
-    const result = await this.#credentials.resolve(secretRef).catch(() => undefined);
+    const result = await atConnectionStage('credential.read', () => this.#credentials.resolve(secretRef), 'credential-store');
     return cleanString(result?.value);
   }
 
   async #restoreCredential(secretRef, previous) {
     try {
-      if (cleanString(previous?.value)) await this.#credentials.set(secretRef, previous.value);
-      else await this.#credentials.unset(secretRef);
+      if (cleanString(previous?.value)) await atConnectionStage('credential.save', () => this.#credentials.set(secretRef, previous.value), 'credential-store');
+      else await atConnectionStage('credential.remove', () => this.#credentials.unset(secretRef), 'credential-store');
     } catch {
       this.#logger.error?.(`[dsh-dingtalk] failed to restore credential ${secretRef}`);
     }

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

@@ -1,3 +1,4 @@
+import { atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { createDingtalkApi } from './dingtalk-api.mjs';
 import {
   createDingtalkBridgeStatus,
@@ -87,7 +88,7 @@ async function connectStream(client, timeoutMs, pollIntervalMs, signal) {
         void connectTask.then(() => client.disconnect()).catch(() => undefined);
       }
       if (signal.aborted) throw signal.reason;
-      throw new Error(`DingTalk Stream handshake timed out after ${timeoutMs}ms`);
+      throw Object.assign(new Error(`DingTalk Stream handshake timed out after ${timeoutMs}ms`), { code: 'ETIMEDOUT', timeoutMs, cause: error });
     }
     throw error;
   }
@@ -134,6 +135,7 @@ export class DingtalkRuntime {
   #contextEnhancement;
   #accessPolicy;
   #logger;
+  #diagnostics;
   #replyTimeoutMs;
   #maxMessageChars;
   #connectTimeoutMs;
@@ -176,6 +178,7 @@ export class DingtalkRuntime {
     this.#contextEnhancement = contextEnhancement;
     this.#accessPolicy = accessPolicy;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'dingtalk', logger, prefix: 'DT-CONN' });
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#maxMessageChars = maxMessageChars;
     this.#connectTimeoutMs = connectTimeoutMs;
@@ -228,7 +231,7 @@ export class DingtalkRuntime {
     let startStage = 'dingtalk-harness-connect-failed';
 
     try {
-      await this.#harness.ensureRunning({ signal });
+      await atConnectionStage('harness.check', () => this.#harness.ensureRunning({ signal }));
       this.#status.harnessReachable = true;
       startStage = 'dingtalk-runtime-prepare-failed';
       if (typeof this.#state.removePendingSenderByStaffId === 'function') {
@@ -348,12 +351,22 @@ export class DingtalkRuntime {
       this.#status.lastConnectedAt = Date.now();
       this.#status.lastCheckedAt = Date.now();
       this.#status.lastError = null;
+      this.#status.error = null;
+      this.#diagnostics.clear();
       this.#connectionMonitor = setInterval(() => {
         const connected = streamIsOpen(client);
         this.#status.ready = connected;
         this.#status.dingtalkStreamState = connected ? 'connected' : 'reconnecting';
         this.#status.lastCheckedAt = Date.now();
-        if (connected) this.#status.lastError = null;
+        if (connected) {
+          this.#status.lastError = null;
+          this.#status.error = null;
+          this.#diagnostics.clear();
+        } else {
+          this.#status.error = this.#diagnostics.report(null, { operation: 'connection.monitor', automatic: true, botId: this.#config.botId,
+            publicError: { code: 'stream-connect-failed', message: t('钉钉连接未就绪，请稍后重试。') } }).publicError;
+          this.#status.lastError = this.#status.error.message;
+        }
       }, 1_000);
       this.#connectionMonitor.unref?.();
       return this.status;
@@ -362,7 +375,7 @@ export class DingtalkRuntime {
       const failure = aborted ? error : dingtalkRuntimeStartError(startStage, error);
       this.#status.ready = false;
       this.#status.dingtalkStreamState = aborted ? 'idle' : 'failed';
-      this.#status.lastError = aborted ? null : (failure?.message ?? String(failure));
+      this.#status.lastError = aborted ? null : t('钉钉连接未就绪，请稍后重试。');
       await this.stop({ preserveError: !aborted });
       throw failure;
     }
@@ -370,6 +383,7 @@ export class DingtalkRuntime {
 
   async stop({ preserveError = false } = {}) {
     const lastError = preserveError ? this.#status.lastError : null;
+    const publicError = preserveError ? this.#status.error : null;
     const abortController = this.#abortController;
     this.#abortController = null;
     abortController?.abort(new DOMException('DingTalk runtime stopped', 'AbortError'));
@@ -393,6 +407,8 @@ export class DingtalkRuntime {
     this.#bridge = null;
     this.#status.dingtalkStreamState = preserveError ? 'failed' : 'idle';
     this.#status.lastError = lastError;
+    this.#status.error = publicError;
+    if (!preserveError) this.#diagnostics.clear();
     return this.status;
   }
 

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

@@ -295,16 +295,16 @@ export class DiscordApi {
       });
     } catch (error) {
       if (error?.name === 'AbortError' || error?.name === 'TimeoutError') throw error;
-      throw new Error(`Discord ${method} transport failed`);
+      throw new Error(`Discord ${method} transport failed`, { cause: error });
     }
 
     let parsed = null;
     if (expectBody || response.status === 429 || !response.ok) {
       try {
         parsed = await response.json();
-      } catch {
+      } catch (cause) {
         if (expectBody) {
-          const error = new Error(`Discord ${method} returned invalid JSON`);
+          const error = new Error(`Discord ${method} returned invalid JSON`, { cause });
           error.status = response?.status;
           throw error;
         }

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

@@ -1,3 +1,4 @@
+import { extractConnectionEvidence, createConnectionDiagnostics, atConnectionStage } from '../shared/connection-error.mjs';
 import { createEditableMessageStream, splitMessageText } from '../shared/editable-message-stream.mjs';
 import { fetchFileStream } from '../shared/file-download.mjs';
 import { fetchImageBuffer } from '../shared/image-prompt.mjs';
@@ -534,6 +535,7 @@ export class DiscordRuntime {
   #contextEnhancement;
   #accessPolicy;
   #logger;
+  #diagnostics;
   #replyTimeoutMs;
   #connectTimeoutMs;
   #createApi;
@@ -582,7 +584,7 @@ export class DiscordRuntime {
     this.#state = state;
     this.#contextEnhancement = contextEnhancement;
     this.#accessPolicy = accessPolicy;
-    this.#logger = logger;
+    this.#logger = logger; this.#diagnostics = createConnectionDiagnostics({ channel: 'discord', logger });
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#connectTimeoutMs = connectTimeoutMs;
     this.#createApi = createApi;
@@ -639,8 +641,8 @@ export class DiscordRuntime {
     this.#routing.clear();
     this.#status.startedAt = new Date().toISOString();
     this.#status.connectionState = 'connecting';
-    this.#status.lastError = null;
-    await this.#harness.ensureRunning();
+    this.#status.lastError = null; this.#status.error = null; this.#diagnostics.clear();
+    await atConnectionStage('harness.check', () => this.#harness.ensureRunning());
     this.#status.harnessReachable = true;
     const controller = new AbortController();
     this.#abortController = controller;
@@ -672,7 +674,7 @@ export class DiscordRuntime {
         await Promise.race([
           this.#openSocket(false),
           new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error('Discord Gateway did not become ready in time')), this.#connectTimeoutMs);
+            timer = setTimeout(() => reject(Object.assign(new Error('Discord Gateway did not become ready in time'), { code: 'ETIMEDOUT', timeoutMs: this.#connectTimeoutMs })), this.#connectTimeoutMs);
           }),
         ]);
       } finally {
@@ -682,7 +684,8 @@ export class DiscordRuntime {
     } catch (error) {
       this.#status.ready = false;
       this.#status.connectionState = 'failed';
-      this.#status.lastError = error?.message ?? String(error);
+      this.#status.error = this.#diagnostics.report(error, { operation: 'connection.restore', reuse: true, botId: this.#config?.botId, automatic: true }).publicError;
+      this.#status.lastError = this.#status.error.message;
       await this.stop();
       throw error;
     }
@@ -705,7 +708,7 @@ export class DiscordRuntime {
         this.#status.connectionState = 'connected';
         this.#status.lastCheckedAt = now;
         this.#status.lastConnectedAt = now;
-        this.#status.lastError = null;
+        this.#status.lastError = null; this.#status.error = null; this.#diagnostics.clear();
         resolve();
       };
       addSocketListener(socket, 'message', (event) => {
@@ -790,7 +793,7 @@ export class DiscordRuntime {
               if (generation !== this.#generation || this.#stopped) return;
               this.#logger.error?.(
                 `[dsh-im:discord] bot ${this.#config.botId} message handling failed:`,
-                error,
+                extractConnectionEvidence(error).details,
               );
             });
           }
@@ -807,7 +810,8 @@ export class DiscordRuntime {
         const error = gatewayCloseError(Number(event.code) || 0);
         this.#status.ready = false;
         this.#status.connectionState = 'connecting';
-        this.#status.lastError = error.message;
+        this.#status.error = this.#diagnostics.report(error, { operation: 'connection.monitor', botId: this.#config?.botId, automatic: true }).publicError;
+        this.#status.lastError = this.#status.error.message;
         if (!settled) {
           settled = true;
           reject(error);
@@ -818,9 +822,11 @@ export class DiscordRuntime {
         }
         this.#scheduleReconnect();
       });
-      addSocketListener(socket, 'error', () => {
+      addSocketListener(socket, 'error', (event) => {
+        const error = event?.error ?? new Error('WebSocket error');
         if (generation !== this.#generation || this.#stopped) return;
-        this.#status.lastError = 'Discord Gateway WebSocket error';
+        this.#status.error = this.#diagnostics.report(error, { operation: 'connection.monitor', botId: this.#config?.botId, automatic: true }).publicError;
+        this.#status.lastError = this.#status.error.message;
       });
     });
   }
@@ -931,7 +937,7 @@ export class DiscordRuntime {
       this.#reconnectTimer = null;
       void this.#openSocket(Boolean(this.#sessionId)).catch((error) => {
         if (this.#stopped) return;
-        this.#logger.warn?.('[dsh-im:discord] Gateway reconnect failed:', error);
+        this.#logger.warn?.('[dsh-im:discord] Gateway reconnect failed:', extractConnectionEvidence(error).details);
         this.#scheduleReconnect();
       });
     }, delay);
@@ -955,7 +961,7 @@ export class DiscordRuntime {
     try {
       if (socket && socket.readyState < 2) socket.close(1000, 'Plugin stopped');
     } catch (error) {
-      this.#logger.warn?.(`[dsh-im:discord] bot ${this.#config.botId} failed to close Gateway:`, error);
+      this.#logger.warn?.(`[dsh-im:discord] bot ${this.#config.botId} failed to close Gateway:`, extractConnectionEvidence(error).details);
     }
     await Promise.race([
       bridge?.waitForIdle() ?? Promise.resolve(),