@xmanrui/dsh-im 4.38.1 → 4.38.2

package/src/channels/shared/harness-client.mjs

@@ -22,6 +22,7 @@ import { imSourceGuidance } from './im-source-guidance.mjs';
 import { outboundArtifactRegistry } from './semantic/artifact.mjs';
 import { t } from './i18n.mjs';
 import { watchHarnessMux } from './harness-mux.mjs';
+import { extractConnectionEvidence, messageDiagnosticError } from './connection-error.mjs';
 
 // Every channel plugin runs in the same Host process. Sharing ownership by
 // Host identity (or an explicitly configured HTTP origin) prevents clients
@@ -29,10 +30,28 @@ import { watchHarnessMux } from './harness-mux.mjs';
 // from claiming or cancelling each other's interactions.
 const interactionRegistries = new Map();
 const hostInteractionRegistries = new WeakMap();
+const modelCatalogCaches = new WeakMap();
+const MODEL_CATALOG_TTL_MS = 30_000;
 const MAX_ERROR_CLASSIFICATION_BYTES = 64;
 const IM_INPUT_ORIGIN_TTL_MS = 30 * 60 * 1000;
 const MAX_IM_INPUT_ORIGINS = 4096;
 
+function invalidateModelCatalog(entry) {
+  if (!entry) return;
+  entry.value = null;
+  entry.expiresAt = 0;
+  // Old readers may finish, but must not repopulate the cache after a fresh read.
+  entry.pending = null;
+}
+
+export function clearModelCatalogCache(apiProxy) {
+  const entry = modelCatalogCaches.get(apiProxy);
+  if (!entry) return;
+  modelCatalogCaches.delete(apiProxy);
+  invalidateModelCatalog(entry);
+  entry.controller.abort(new DOMException('Harness model catalog disposed', 'AbortError'));
+}
+
 function clientTimeZoneFields() {
   try {
     const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -1187,9 +1206,46 @@ export class HarnessClient {
   }
 
   async listModels(options = {}) {
+    options.signal?.throwIfAborted();
     await this.ensureRunning(options);
-    const value = await this.rpc('llm.models', {}, 30_000, options);
-    return validateModelCatalog(value, 'llm.models');
+    options.signal?.throwIfAborted();
+    if (!this.#apiProxy || options.fresh === true) {
+      try {
+        const value = await this.rpc('llm.models', {}, 30_000, options);
+        return validateModelCatalog(value, 'llm.models');
+      } finally {
+        if (this.#apiProxy) invalidateModelCatalog(modelCatalogCaches.get(this.#apiProxy));
+      }
+    }
+
+    let entry = modelCatalogCaches.get(this.#apiProxy);
+    if (!entry) {
+      entry = { value: null, expiresAt: 0, pending: null, controller: new AbortController() };
+      modelCatalogCaches.set(this.#apiProxy, entry);
+    }
+    if (entry.value && Date.now() < entry.expiresAt) return structuredClone(entry.value);
+    if (!entry.pending) {
+      // The Host owns this read; one caller cancelling must not cancel its peers.
+      const pending = this.rpc('llm.models', {}, 30_000, {
+        ...options, signal: entry.controller.signal,
+      }).then((value) => {
+        const catalog = structuredClone(validateModelCatalog(value, 'llm.models'));
+        if (modelCatalogCaches.get(this.#apiProxy) === entry && entry.pending === pending) {
+          entry.value = catalog;
+          entry.expiresAt = Date.now() + MODEL_CATALOG_TTL_MS;
+        }
+        return catalog;
+      }).finally(() => {
+        if (entry.pending === pending) entry.pending = null;
+      });
+      entry.pending = pending;
+    }
+    const pending = entry.pending;
+    const value = await callWithSignal(
+      () => pending,
+      options.signal ?? entry.controller.signal,
+    );
+    return structuredClone(value);
   }
 
   async getSessionModels(sessionId, options = {}) {
@@ -1224,13 +1280,18 @@ export class HarnessClient {
           : { reasoningEffort: selection.reasoningEffort }),
       }, 30_000, signal ? { ...options, signal } : options);
     };
-    const value = this.#sessionMaintenanceExecutor
-      ? await this.#sessionMaintenanceExecutor({ sessionId, operation })
-      : await operation();
-    if (!value || typeof value !== 'object' || !validModelSelection(value.selected)) {
-      throw new Error('Harness returned an invalid response for session.selectModel');
+    try {
+      const value = this.#sessionMaintenanceExecutor
+        ? await this.#sessionMaintenanceExecutor({ sessionId, operation })
+        : await operation();
+      if (!value || typeof value !== 'object' || !validModelSelection(value.selected)) {
+        throw new HarnessTransportError('harness-response-invalid', 'session.selectModel');
+      }
+      return value;
+    } catch (error) {
+      if (options.signal?.aborted) throw error;
+      throw messageDiagnosticError(error, { stage: 'session.prepare', sessionId });
     }
-    return value;
   }
 
   async isSessionRunning(sessionId, options = {}) {
@@ -1279,6 +1340,9 @@ export class HarnessClient {
     const agentPreset = requestedPreset !== undefined ? requestedPreset : this.#agentPreset;
     if (agentPreset != null) payload.agentPreset = agentPreset;
     const created = await this.rpc('session.create', payload, 30_000, rpcOptions);
+    if (typeof created?.sessionId !== 'string' || !created.sessionId) {
+      throw new HarnessTransportError('harness-response-invalid', 'session.create');
+    }
     return created.sessionId;
   }
 
@@ -1409,6 +1473,7 @@ export class HarnessClient {
     onSessionEvent,
     onOpen,
     ownership,
+    onDiagnostic,
   } = {}) {
     if (typeof sessionId !== 'string' || !sessionId) throw new TypeError('sessionId is required');
     if (!signal || typeof signal.addEventListener !== 'function') {
@@ -1426,8 +1491,17 @@ export class HarnessClient {
     if (onOpen !== undefined && typeof onOpen !== 'function') {
       throw new TypeError('onOpen must be a function');
     }
-
+    let attempts = 0;
+    let lastFailureReason;
+    const report = () => {
+      try {
+        Promise.resolve(onDiagnostic?.({ attempts, ...(lastFailureReason ? { lastFailureReason } : {}) }))
+          .catch(() => undefined);
+      } catch { /* Diagnostics cannot change stream/reconnect behavior. */ }
+    };
     while (!signal.aborted) {
+      attempts += 1;
+      report();
       try {
         await this.#watchInteractionStream(sessionId, {
           signal,
@@ -1439,6 +1513,8 @@ export class HarnessClient {
         });
       } catch (error) {
         if (signal.aborted) return;
+        lastFailureReason = extractConnectionEvidence(error).details.reason;
+        report();
         console.warn('[dsh-im] Harness interaction stream disconnected:', this.#logPrefix, error.message);
       }
       if (signal.aborted) return;
@@ -1711,6 +1787,16 @@ export class HarnessClient {
 
   async ask(sessionId, prompt, options = {}) {
     if (typeof options === 'number') options = { timeoutMs: options };
+    const diagnostic = { stage: 'prompt.prepare', submissionState: 'not-submitted', sessionId };
+    try {
+      return await this.#ask(sessionId, prompt, options, diagnostic);
+    } catch (error) {
+      if (options.signal?.aborted) throw error;
+      throw messageDiagnosticError(error, diagnostic);
+    }
+  }
+
+  async #ask(sessionId, prompt, options, diagnostic) {
     const timeoutMs = options.timeoutMs ?? 600_000;
     const signal = options.signal;
     const onUpdate = typeof options.onUpdate === 'function' ? options.onUpdate : null;
@@ -1740,6 +1826,7 @@ export class HarnessClient {
     );
     const baselineSeq = Math.max(-1, ...(before.events ?? []).map(({ event }) => event.seq ?? -1));
     const promptRpcId = `${this.#rpcIdPrefix}-${randomUUID()}`;
+    diagnostic.promptRpcId = promptRpcId;
     const releasePromptInputOrigin = registerImInputOrigin(this.#interactionRegistry, promptRpcId);
     const tracker = new HarnessReplyTracker({
       promptRpcId, afterSeq: baselineSeq, reasoning, finalAnswerOnly: options.finalAnswerOnly,
@@ -1869,6 +1956,9 @@ export class HarnessClient {
         });
       }
       if (interactionSignal) {
+        diagnostic.stage = 'interaction.open';
+        const startedAt = performance.now();
+        let streamDiagnostic = { attempts: 0 };
         let markOpen;
         const opened = new Promise((resolve) => { markOpen = resolve; });
         interactionTask = this.watchInteractions(sessionId, {
@@ -1880,16 +1970,25 @@ export class HarnessClient {
             : undefined,
           onOpen: markOpen,
           ownership,
+          onDiagnostic: (value) => { streamDiagnostic = value; },
         });
         void interactionTask.catch(() => undefined);
         await Promise.race([
           opened,
           sleep(30_000, interactionSignal).then(() => {
-            throw new Error('Harness interaction stream did not open within 30 seconds');
+            throw Object.assign(new HarnessInteractionError(
+              'harness-interaction-timeout',
+              'Harness interaction stream did not open within 30 seconds',
+            ), {
+              transport: this.#apiProxy ? 'host-api' : 'websocket',
+              durationMs: Math.round(performance.now() - startedAt),
+              timeoutMs: 30_000,
+              ...streamDiagnostic,
+            });
           }),
         ]);
       }
-
+      diagnostic.stage = 'prompt.prepare';
       const content = typeof prompt === 'string'
         ? [{ type: 'text', text: prompt }]
         : prompt;
@@ -1903,12 +2002,16 @@ export class HarnessClient {
       // message that merely looks like a guidance block is not configuration.
       imSourceGuidance.publish(sessionId, options.sourceGuidance);
       const timeZoneFields = clientTimeZoneFields();
-      const sendPrompt = (promptContent) => this.#sessionRpc('session.prompt', {
-        sessionId,
-        mode: 'queue',
-        content: promptContent,
-        ...timeZoneFields,
-      }, 30_000, { rpcId: promptRpcId, signal });
+      const sendPrompt = (promptContent) => {
+        diagnostic.stage = 'prompt.submit';
+        diagnostic.submissionState = 'unknown';
+        return this.#sessionRpc('session.prompt', {
+          sessionId,
+          mode: 'queue',
+          content: promptContent,
+          ...timeZoneFields,
+        }, 30_000, { rpcId: promptRpcId, signal });
+      };
       try {
         await sendPrompt(content);
       } catch (error) {
@@ -1948,6 +2051,8 @@ export class HarnessClient {
         await sendPrompt(fallbackPrompt);
       }
       promptAccepted = true;
+      diagnostic.submissionState = 'accepted';
+      diagnostic.stage = 'reply.wait';
 
       try {
         // Treat timeoutMs as a stall window rather than a hard runtime limit.
@@ -2032,6 +2137,8 @@ export class HarnessClient {
             continue;
           }
           const timeoutError = new HarnessTurnError('harness-reply-timeout');
+          timeoutError.durationMs = Date.now() - lastProgressAt;
+          timeoutError.timeoutMs = timeoutMs;
           // Data-only context for deferred delivery; timeout semantics unchanged.
           timeoutError.details = { sessionId, promptRpcId, baselineSeq, turn: tracker.turn, lastSeq: tracker.lastSeq };
           throw timeoutError;

package/src/channels/shared/harness-mux.mjs

@@ -97,12 +97,14 @@ function watchWebSocketMux({ baseUrl, createWebSocket, signal, onOpen, onEnvelop
       }
       invoke(onEnvelope, envelope, finish);
     };
-    const handleClose = () => finish(opened ? undefined : new Error(
+    const handleClose = () => finish(opened ? undefined : Object.assign(new Error(
       'Harness event mux WebSocket closed before opening',
-    ));
-    const handleError = () => finish(new Error(opened
+    ), { code: 'stream-closed-before-open' }));
+    const handleError = () => finish(Object.assign(new Error(opened
       ? 'Harness event mux WebSocket failed'
-      : 'Harness event mux WebSocket failed before opening'));
+      : 'Harness event mux WebSocket failed before opening'), {
+      code: opened ? 'stream-failed' : 'stream-failed-before-open',
+    }));
     const handleAbort = () => finish();
     socket.addEventListener('open', handleOpen);
     socket.addEventListener('message', handleMessage);

package/src/channels/shared/i18n-en/diagnostics.mjs

@@ -1,4 +1,28 @@
 export default Object.freeze({
+  '准备会话': 'Prepare session',
+  '准备消息': 'Prepare message',
+  '建立交互通道': 'Open interaction channel',
+  '提交消息': 'Submit message',
+  '等待处理结果': 'Wait for result',
+  '消息提交状态': 'Message submission status',
+  '未提交': 'Not submitted',
+  '已确认接收': 'Acceptance confirmed',
+  '提交结果未知': 'Submission outcome unknown',
+  '连接尝试次数': 'Connection attempts',
+  '最近一次连接失败': 'Last observed connection failure',
+  '打开前关闭': 'Closed before opening',
+  '打开前失败': 'Failed before opening',
+  '通道连接失败': 'Stream connection failed',
+  '与 DSH 的交互通道在 30 秒内未就绪，本条消息尚未提交执行。请稍后重试。':
+    'The DSH interaction channel was not ready within 30 seconds. This message has not been submitted for execution. Please try again later.',
+  '消息提交前的操作超时，本条消息尚未提交执行。请稍后重试。':
+    'An operation timed out before submission. This message has not been submitted for execution. Please try again later.',
+  '消息提交前的网络请求失败，本条消息尚未提交执行。请检查连接后重试。':
+    'A network request failed before submission. This message has not been submitted for execution. Check the connection and try again.',
+  '消息在提交前处理失败，尚未提交执行。请重试；若持续发生，请将参考号提供给管理员。':
+    'Message preparation failed before submission. It has not been submitted for execution. Try again; if this persists, share the reference with your administrator.',
+  '消息已尝试提交，但任务结果尚未确认。请先到 DSH 查看状态，不要立即重复提交；若持续发生，请将参考号提供给管理员。':
+    'Message submission was attempted, but the task outcome is unconfirmed. Check its status in DSH before resubmitting; if this persists, share the reference with your administrator.',
   "DSH 版本": "DSH version",
   "依赖版本": "Dependency versions",
   "代理已配置": "Proxy configured",

package/src/channels/shared/message-failure.mjs

@@ -1,4 +1,4 @@
-import { connectionHint, extractConnectionEvidence } from './connection-error.mjs';
+import { connectionHint, extractConnectionEvidence, messageDiagnosticError, runtimeDiagnosticDetails } from './connection-error.mjs';
 import { diagnosticFields } from './diagnostic-details.mjs';
 import { randomUUID } from 'node:crypto';
 
@@ -26,6 +26,8 @@ const PROVIDER_FAILURES = Object.freeze({
 });
 
 const FAILURE_MESSAGES = Object.freeze({
+  HARNESS_INTERACTION_TIMEOUT:
+    '与 DSH 的交互通道在 30 秒内未就绪，本条消息尚未提交执行。请稍后重试。',
   HARNESS_CONNECT:
     '无法连接处理服务，消息尚未提交。请确认 DeepSeek Harness 正在运行后重试。',
   HARNESS_TIMEOUT:
@@ -107,18 +109,23 @@ function providerFailureCode(error) {
   return PROVIDER_FAILURES[value.trim().toUpperCase()] ?? null;
 }
 
-function failureCode(error) {
+function failureCode(error, details) {
   const code = typeof error?.code === 'string' ? error.code : '';
   const providerCode = providerFailureCode(error);
   if (providerCode) return providerCode;
+  if (code === 'harness-interaction-timeout') return 'HARNESS_INTERACTION_TIMEOUT';
+
+  const uncertain = details.submissionState === undefined
+    ? ['session.prompt', 'session.history'].includes(error?.method)
+    : details.submissionState !== 'not-submitted';
 
   if (code === 'harness-connect-failed') {
-    return ['session.prompt', 'session.history'].includes(error?.method)
+    return uncertain
       ? 'HARNESS_RESULT_UNCERTAIN'
       : 'HARNESS_CONNECT';
   }
   if (code === 'harness-timeout') {
-    return ['session.prompt', 'session.history'].includes(error?.method)
+    return uncertain
       ? 'HARNESS_RESULT_UNCERTAIN'
       : 'HARNESS_TIMEOUT';
   }
@@ -205,25 +212,38 @@ export function classifyMessageFailure(error, {
   at = Date.now(),
 } = {}) {
   const safeReason = safeFailureReason(reason);
-  const classifiedCode = failureCode(error);
+  const details = extractConnectionEvidence(error).details;
+  const classifiedCode = failureCode(error, details);
   const businessCode = classifiedCode === 'INTERNAL_UNKNOWN'
     && safeReason
     && typeof userMessage === 'string'
     && userMessage.trim()
     ? 'INPUT_INVALID'
     : classifiedCode;
-  const details = extractConnectionEvidence(error).details;
   const code = businessCode === 'INTERNAL_UNKNOWN'
     ? transportFailureCode(error, details)
     : businessCode;
   if (code === 'REQUEST_TIMEOUT' || code === 'NETWORK_ERROR') details.hint = connectionHint(details);
+  if (details.stage || details.submissionState) Object.assign(details, runtimeDiagnosticDetails());
+  let message = FAILURE_MESSAGES[code];
+  if (['INTERNAL_UNKNOWN', 'REQUEST_TIMEOUT', 'NETWORK_ERROR'].includes(code)) {
+    if (details.submissionState === 'not-submitted') {
+      message = code === 'REQUEST_TIMEOUT'
+        ? '消息提交前的操作超时，本条消息尚未提交执行。请稍后重试。'
+        : code === 'NETWORK_ERROR'
+          ? '消息提交前的网络请求失败，本条消息尚未提交执行。请检查连接后重试。'
+          : '消息在提交前处理失败，尚未提交执行。请重试；若持续发生，请将参考号提供给管理员。';
+    } else if (details.submissionState) {
+      message = '消息已尝试提交，但任务结果尚未确认。请先到 DSH 查看状态，不要立即重复提交；若持续发生，请将参考号提供给管理员。';
+    }
+  }
   return Object.freeze({
-    ...(code === 'INTERNAL_UNKNOWN' || details.reason !== 'unknown' || details.httpStatus || details.providerCode || details.method ? { details } : {}),
+    ...(code === 'INTERNAL_UNKNOWN' || details.reason !== 'unknown' || details.httpStatus || details.providerCode || details.method || details.stage || details.submissionState ? { details } : {}),
     code,
     reason: safeReason ?? safeFailureReason(error?.code) ?? code,
     message: typeof userMessage === 'string' && userMessage.trim()
       ? userMessage.trim()
-      : t(FAILURE_MESSAGES[code]) + (code === 'SESSION_ARCHIVED' && error?.promptAccepted === true
+      : t(message) + (code === 'SESSION_ARCHIVED' && error?.promptAccepted === true
         ? `\n${t('本条消息可能仍在会话队列中，请先到 DSH 查看状态，避免重复提交。')}` : ''),
     referenceId: safeReferenceId(referenceId),
     at: Number.isFinite(at) ? at : Date.now(),
@@ -237,7 +257,7 @@ export function messageFailureText(failure) {
 export function messageFailureDiagnostic(error, failure) {
   const evidence = extractConnectionEvidence(error);
   return { code: failure.code, reason: failure.reason, referenceId: failure.referenceId,
-    details: evidence.details, errors: evidence.errors };
+    details: failure.details ?? evidence.details, errors: evidence.errors, ...evidence.correlation };
 }
 
 export function setLastMessageFailure(status, error, options) {
@@ -262,7 +282,7 @@ export function channelDeliveryFailure(error, { uncertain = true } = {}) {
         ? 'channel-delivery-uncertain'
         : 'channel-delivery-failed';
   if (Number.isInteger(status)) wrapped.status = status;
-  return wrapped;
+  return messageDiagnosticError(wrapped, { stage: 'message.send' });
 }
 
 export function publicMessageFailure(value) {

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

@@ -1,5 +1,6 @@
 import { withSessionBindingLock } from './session-binding-lock.mjs';
 import { initialSessionTitle } from './session-title.mjs';
+import { messageDiagnosticError } from './connection-error.mjs';
 
 export const WORKSPACE_SESSION_STALE = 'workspace-session-stale';
 
@@ -114,16 +115,19 @@ export async function askInWorkspaceSession({
     ?? (typeof askOptions === 'object' ? askOptions?.signal : undefined);
   const renameOptions = renameSignal ? { signal: renameSignal } : undefined;
   while (true) {
+    const diagnostic = { stage: 'session.prepare', submissionState: 'not-submitted' };
     try {
       const binding = await withSessionBindingLock(state, key, async () => {
         await awaitPendingConversationSwitch(harness, key);
         let sessionId = state.sessionFor(key);
+        diagnostic.sessionId = sessionId;
         let session = sessionId ? workspaceSession(harness, sessionId, key) : null;
         if (!session || !(await sessionExists(session, existsOptions))) {
           sessionId = await createSession(harness, {
             conversationKey: key,
             ...(createOptions ?? {}),
           });
+          diagnostic.sessionId = sessionId;
           if (await state.setSession(key, sessionId) === false) return null;
           // Binding committed: capture the conversation's effective-workspace
           // generation together with the session, so the prompt below is fenced
@@ -150,6 +154,8 @@ export async function askInWorkspaceSession({
         return { sessionId, session };
       });
       if (!binding) continue;
+      diagnostic.sessionId = binding.sessionId;
+      diagnostic.stage = 'prompt.prepare';
       const artifacts = [];
       const originalOnArtifact = typeof askOptions === 'object'
         && typeof askOptions?.onArtifact === 'function'
@@ -172,6 +178,9 @@ export async function askInWorkspaceSession({
         ? await prepareContent({ sessionId: binding.sessionId, content, text })
         : content ?? text;
       try {
+        // An alternate Harness adapter may not supply finer ask() diagnostics.
+        diagnostic.stage = 'operation';
+        diagnostic.submissionState = 'unknown';
         answer = await binding.session.ask(prompt, artifactOptions);
       } catch (error) {
         if (error?.code === 'harness-reply-timeout' && deferredDelivery) {
@@ -190,7 +199,7 @@ export async function askInWorkspaceSession({
         ...(artifacts.length > 0 ? { artifacts } : {}),
       };
     } catch (error) {
-      if (error?.code !== WORKSPACE_SESSION_STALE) throw error;
+      if (error?.code !== WORKSPACE_SESSION_STALE) throw messageDiagnosticError(error, diagnostic);
     }
   }
 }