@xmanrui/dsh-im 4.36.0 → 4.37.0

package/src/channels/shared/bot-workspace-store.mjs

@@ -1,4 +1,5 @@
 import { t } from './i18n.mjs';
+import { normalizeBusyMessageMode, validateBusyMessageMode } from './message-mode.mjs';
 import { atConnectionStage, connectionStageError, extractConnectionEvidence } from './connection-error.mjs';
 import { validateBotAlias, withBotAlias } from './bot-alias.mjs';
 import { defaultImWorkspace, ensureImWorkspaceDirectory, sameWorkspacePath } from './default-workspace.mjs';
@@ -307,6 +308,13 @@ function normalizeDocument(value) {
       } catch { /* A damaged display name must not disable the bot. */ }
     }
   }
+  const busyMessageModes = Object.create(null);
+  if (value.busyMessageModes && typeof value.busyMessageModes === 'object'
+    && !Array.isArray(value.busyMessageModes)) {
+    for (const [id, mode] of Object.entries(value.busyMessageModes)) {
+      if (Object.hasOwn(workspaces, id) && mode === 'steer') busyMessageModes[id] = mode;
+    }
+  }
   const accessPolicies = normalizeAccessPolicies(value.accessPolicies, workspaces);
   const version = Math.max(
     value.version,
@@ -324,6 +332,7 @@ function normalizeDocument(value) {
     deliveryTargets,
     accessPolicies,
     aliases,
+    busyMessageModes,
   };
 }
 
@@ -337,8 +346,10 @@ function storedDocument({
   deliveryTargets,
   accessPolicies,
   aliases,
+  busyMessageModes,
 }) {
   const document = { version, workspaces };
+  if (Object.keys(busyMessageModes).length > 0) document.busyMessageModes = busyMessageModes;
   if (Object.keys(aliases).length > 0) document.aliases = aliases;
   if (Object.keys(conversationWorkspaces).length > 0) {
     document.conversationWorkspaces = conversationWorkspaces;
@@ -400,6 +411,7 @@ export class BotWorkspaceStore {
   #agentPresets = {};
   #models = {};
   #aliases = Object.create(null);
+  #busyMessageModes = Object.create(null);
   #contextEnhancement = {};
   #deliveryTargets = Object.create(null);
   #accessPolicies = Object.create(null);
@@ -431,6 +443,7 @@ export class BotWorkspaceStore {
       this.#agentPresets = normalized.agentPresets;
       this.#models = normalized.models;
       this.#aliases = normalized.aliases;
+      this.#busyMessageModes = normalized.busyMessageModes;
       this.#contextEnhancement = normalized.contextEnhancement;
       this.#deliveryTargets = normalized.deliveryTargets;
       this.#accessPolicies = normalized.accessPolicies;
@@ -442,6 +455,7 @@ export class BotWorkspaceStore {
       this.#agentPresets = {};
       this.#models = {};
       this.#aliases = Object.create(null);
+      this.#busyMessageModes = Object.create(null);
       this.#contextEnhancement = {};
       this.#deliveryTargets = Object.create(null);
       this.#accessPolicies = Object.create(null);
@@ -519,6 +533,11 @@ export class BotWorkspaceStore {
     return this.has(id) && Object.hasOwn(this.#aliases, id) ? this.#aliases[id] : '';
   }
 
+  busyMessageModeFor(botId) {
+    const id = botIdOf(botId);
+    return normalizeBusyMessageMode(this.has(id) ? this.#busyMessageModes[id] : undefined);
+  }
+
   contextEnhancementFor(botId) {
     const id = botIdOf(botId);
     return this.has(id) && Object.hasOwn(this.#contextEnhancement, id)
@@ -890,6 +909,27 @@ export class BotWorkspaceStore {
     });
   }
 
+  async setBusyMessageMode(botId, value, { incarnation } = {}) {
+    const id = botIdOf(botId);
+    const expectedIncarnation = incarnation === undefined ? this.incarnationFor(id) : incarnation;
+    const mode = validateBusyMessageMode(value);
+    return this.#enqueue(id, async () => {
+      if (!this.has(id) || expectedIncarnation !== this.incarnationFor(id)) {
+        const error = new Error('找不到要修改的机器人。');
+        error.code = 'workspace-bot-not-found';
+        throw error;
+      }
+      const next = { ...this.#busyMessageModes };
+      if (mode === 'steer') next[id] = mode;
+      else delete next[id];
+      // Publish only after the same atomic write used by the other bot settings.
+      await this.#persist(this.#contextEnhancement, this.#deliveryTargets,
+        this.#version, this.#accessPolicies, this.#aliases, this.#conversationWorkspaces, next);
+      this.#busyMessageModes = next;
+      return mode;
+    });
+  }
+
   async setContextEnhancement(botId, value, { incarnation } = {}) {
     const id = botIdOf(botId);
     const expectedIncarnation = incarnation === undefined ? this.incarnationFor(id) : incarnation;
@@ -1253,6 +1293,7 @@ export class BotWorkspaceStore {
       ...Object.keys(this.#agentPresets),
       ...Object.keys(this.#models),
       ...Object.keys(this.#aliases),
+      ...Object.keys(this.#busyMessageModes),
       ...Object.keys(this.#contextEnhancement),
       ...Object.keys(this.#deliveryTargets),
       ...Object.keys(this.#accessPolicies),
@@ -1276,6 +1317,7 @@ export class BotWorkspaceStore {
           agentPreset: this.agentPresetFor(bot.botId),
           model: this.modelFor(bot.botId),
           contextEnhancement: this.contextEnhancementFor(bot.botId),
+          busyMessageMode: this.busyMessageModeFor(bot.botId),
           accessPolicy: this.accessPolicyFor(bot.botId),
         }
         : bot),
@@ -1314,17 +1356,19 @@ export class BotWorkspaceStore {
     const hadPreset = Object.hasOwn(this.#agentPresets, id);
     const hadModel = Object.hasOwn(this.#models, id);
     const hadAlias = Object.hasOwn(this.#aliases, id);
+    const hadMessageMode = Object.hasOwn(this.#busyMessageModes, id);
     const hadContextEnhancement = Object.hasOwn(this.#contextEnhancement, id);
     const hadDeliveryTargets = Object.hasOwn(this.#deliveryTargets, id);
     const hadAccessPolicy = Object.hasOwn(this.#accessPolicies, id);
     const hadConversationWorkspaces = Object.hasOwn(this.#conversationWorkspaces, id);
     const needsCleanup = hadWorkspace || hadPreset || hadModel || hadAlias || hadContextEnhancement
-      || hadDeliveryTargets || hadAccessPolicy || hadConversationWorkspaces
+      || hadDeliveryTargets || hadAccessPolicy || hadConversationWorkspaces || hadMessageMode
       || this.#dirtyRemovals.has(id);
     delete this.#workspaces[id];
     delete this.#agentPresets[id];
     delete this.#models[id];
     delete this.#aliases[id];
+    delete this.#busyMessageModes[id];
     delete this.#contextEnhancement[id];
     delete this.#deliveryTargets[id];
     delete this.#accessPolicies[id];
@@ -1365,6 +1409,7 @@ export class BotWorkspaceStore {
     accessPolicies = this.#accessPolicies,
     aliases = this.#aliases,
     conversationWorkspaces = this.#conversationWorkspaces,
+    busyMessageModes = this.#busyMessageModes,
   ) {
     await writeStoredDocument(this.#path, storedDocument({
       version,
@@ -1376,6 +1421,7 @@ export class BotWorkspaceStore {
       deliveryTargets,
       accessPolicies,
       aliases,
+      busyMessageModes,
     }));
     this.#dirtyRemovals.clear();
   }
@@ -1385,6 +1431,7 @@ export class BotWorkspaceStore {
       || Object.keys(this.#agentPresets).length > 0
       || Object.keys(this.#models).length > 0
       || Object.keys(this.#aliases).length > 0
+      || Object.keys(this.#busyMessageModes).length > 0
       || Object.keys(this.#contextEnhancement).length > 0
       || Object.keys(this.#deliveryTargets).length > 0
       || Object.keys(this.#accessPolicies).length > 0
@@ -1689,6 +1736,9 @@ export function createBotWorkspaceScope(
           }
         };
       }
+      if (property === 'currentBusyMessageMode') {
+        return () => isCurrentScope() ? workspaces.busyMessageModeFor(botId) : 'queue';
+      }
       if (property === 'currentWorkspace') {
         return () => {
           if (!isCurrentScope()) {
@@ -2252,6 +2302,23 @@ export function createWorkspaceAwareController(controller, {
       return result;
     });
   };
+  const updateBusyMessageMode = (botId, value, projectStatus) => {
+    const incarnation = workspaces.incarnationFor(botId);
+    const busyMessageMode = validateBusyMessageMode(value);
+    return withBotTransition(botId, async () => {
+      const snapshot = await decorate(await controller.status());
+      if (!snapshot?.bots?.some((bot) => bot?.botId === botId)) {
+        const error = new Error('找不到要修改的机器人。');
+        error.code = 'workspace-bot-not-found';
+        throw error;
+      }
+      const updated = { ...snapshot, bots: snapshot.bots.map((bot) => bot.botId === botId
+        ? { ...bot, busyMessageMode } : bot) };
+      const result = projectStatus ? await projectStatus(updated) : updated;
+      await workspaces.setBusyMessageMode(botId, busyMessageMode, { incarnation });
+      return result;
+    });
+  };
   const updateContextEnhancement = (botId, value, projectStatus) => {
     const incarnation = workspaces.incarnationFor(botId);
     const config = validateContextEnhancementConfig(value);
@@ -2369,6 +2436,7 @@ export function createWorkspaceAwareController(controller, {
       if (property === 'updateAgentPreset') return updateAgentPreset;
       if (property === 'updateModel') return updateModel;
       if (property === 'updateAlias') return updateAlias;
+      if (property === 'updateBusyMessageMode') return updateBusyMessageMode;
       if (property === 'updateContextEnhancement') return updateContextEnhancement;
       if (property === 'updateAccessPolicy') return updateAccessPolicy;
       const value = Reflect.get(target, property, target);

package/src/channels/shared/busy-message-dispatcher.mjs

@@ -0,0 +1,94 @@
+import { steerMessage } from './control-command.mjs';
+import { isSharedLocalCommand } from './command-permission.mjs';
+import { evaluateInboundAccess } from './inbound-access.mjs';
+import { normalizeBusyMessageMode } from './message-mode.mjs';
+import { t } from './i18n.mjs';
+import {
+  messageFailureDiagnostic, messageFailureText, setLastMessageFailure,
+} from './message-failure.mjs';
+
+export function canAutomaticallySteer(policy, conversationType, senderIds) {
+  // Legacy bridges have already checked their owner/allowlist at acceptance.
+  return !policy || evaluateInboundAccess(policy, {
+    conversationType, senderIds, text: '/steer', isCommand: true,
+  }).allowed;
+}
+
+/** Serialize only routing/submission, leaving the existing task queues intact. */
+export class BusyMessageDispatcher {
+  #tails = new Map();
+  #tasks = new Set();
+
+  dispatch({
+    key, messageId, text, commandText = text, eligible, harness, state, status,
+    control, signal, enhancement, pendingInteraction, acceptedMessageIds,
+    mode = harness.currentBusyMessageMode?.(), onFailure,
+    enqueue, isQueued, send, logger = console, onSteered, onError,
+  }) {
+    // Read once, before any await: a settings change cannot reinterpret this input.
+    const steer = normalizeBusyMessageMode(mode) === 'steer'
+      && (typeof eligible === 'function' ? eligible() : eligible) && Boolean(text?.trim()) && !isSharedLocalCommand(commandText);
+    const report = async (error) => {
+      onFailure?.(error);
+      if (signal?.aborted || error?.code === 'turn-stopped') return;
+      if (onError) return onError(error);
+      status.lastError = error?.message ?? String(error);
+      const failure = setLastMessageFailure(status, error);
+      logger.error?.('[dsh-im] failed to route a message:', messageFailureDiagnostic(error, failure));
+      await Promise.resolve().then(() => send(messageFailureText(failure))).catch(() => undefined);
+    };
+    const queue = (alreadyRecorded = false) => {
+      const waiting = isQueued();
+      // Reserve FIFO position before sending the optional receipt.
+      const completion = enqueue({ alreadyRecorded });
+      const receipt = waiting
+        ? Promise.resolve().then(() => send(t('已排队，等待前序消息处理。'))).catch((error) => {
+            logger.warn?.('[dsh-im] failed to send queue receipt:', error);
+          })
+        : Promise.resolve();
+      return { completion: Promise.all([completion, receipt]).then(([result]) => result) };
+    };
+    const route = async () => {
+      signal?.throwIfAborted();
+      if (!steer || pendingInteraction()) return queue();
+      if (state.hasSeen(messageId)) return {};
+      await state.markSeen(messageId);
+      status.messagesReceived = (status.messagesReceived ?? 0) + 1;
+      status.lastMessageAt = new Date().toISOString();
+      signal?.throwIfAborted();
+      const submitted = await steerMessage(text, harness, state, key, {
+        signal, control, enhancement, pendingInteraction: pendingInteraction(),
+      });
+      if (!submitted) return queue(true);
+      // Submission is final even if its receipt fails.
+      await send(t('已提交补充指令，Agent 会在下一步读取。'));
+      await onSteered?.();
+      status.lastError = null;
+      return {};
+    };
+
+    const previous = this.#tails.get(key);
+    // Preserve synchronous queue reservation for the default/attachment path.
+    const routed = !previous && !steer
+      ? Promise.resolve(queue())
+      : (previous ?? Promise.resolve()).catch(() => undefined).then(route);
+    const tail = routed.then(() => undefined, () => undefined);
+    this.#tails.set(key, tail);
+    void tail.then(() => {
+      if (this.#tails.get(key) === tail) this.#tails.delete(key);
+    });
+    const task = routed.catch(async (error) => {
+      await report(error);
+      return {};
+    }).then(({ completion }) => completion).finally(() => {
+      acceptedMessageIds.delete(messageId);
+      this.#tasks.delete(task);
+    });
+    this.#tasks.add(task);
+    return task;
+  }
+
+  async whenIdle() {
+    await Promise.allSettled([...this.#tasks]);
+  }
+}

package/src/channels/shared/clear-command.mjs

@@ -0,0 +1,85 @@
+import { t } from './i18n.mjs';
+import { WORKSPACE_SESSION_STALE } from './workspace-session.mjs';
+
+const CLEAR_COMMAND = /^\/clear(?=$|\s)([\s\S]*)$/iu;
+const CLEAR_USAGE = '用法：/clear（不带参数且不可附带图片或文件）';
+
+function commandResult(message) {
+  return { handled: true, message, messages: [message] };
+}
+
+function clearErrorMessage(error) {
+  const code = error?.code ?? error?.failure?.code;
+  if (code === 'session-not-found') {
+    return t('当前聊天绑定的会话已不存在，未清空上下文；请先发送新消息开启会话。');
+  }
+  if (code === 'agent-busy' || code === 'pending-interaction') {
+    return t('当前会话正在生成回复或等待交互，请先完成交互或发送 /stop，再执行 /clear。');
+  }
+  if (code === 'cancelled' || error?.name === 'AbortError') {
+    return t('上下文清理已取消，当前会话未修改。');
+  }
+  if (code === WORKSPACE_SESSION_STALE || code === 'workspace-bot-not-found') {
+    return t('工作区或机器人状态已发生变化，未清空当前会话，请重试。');
+  }
+  if (code === 'commands-unavailable') {
+    return t('当前 Host 不支持 /clear，当前会话未修改。');
+  }
+  return t('清空当前会话上下文失败，当前会话未修改，请稍后重试。');
+}
+
+/**
+ * Execute Host's argument-free /clear command without changing the dsh-im
+ * Session binding. Hosts that do not register /clear return undefined and
+ * are reported explicitly; the command never falls back to /new.
+ */
+export async function runClearCommand(text, harness, state, conversationKey, options = {}) {
+  if (!isClearCommand(text)) return null;
+  const match = CLEAR_COMMAND.exec(text.trim());
+  if (match[1].trim() || options.hasImages || options.hasFiles) {
+    return commandResult(t(CLEAR_USAGE));
+  }
+  if (options.pendingInteraction || options.busy) {
+    return commandResult(t('当前会话正在生成回复或等待交互，请先完成交互或发送 /stop，再执行 /clear。'));
+  }
+  if (typeof state?.sessionFor !== 'function') {
+    return commandResult(t('当前机器人没有可用的会话状态，未清空当前会话。'));
+  }
+  const sessionId = state.sessionFor(conversationKey);
+  if (typeof sessionId !== 'string' || !sessionId) {
+    return commandResult(t('当前聊天还没有可清空的会话，请先发送一条消息。'));
+  }
+  try {
+    let execution;
+    if (typeof harness?.workspaceSession === 'function') {
+      const session = harness.workspaceSession(sessionId, conversationKey);
+      if (typeof session?.executeCommand !== 'function') {
+        return commandResult(t('当前 Host 不支持 /clear，当前会话未修改。'));
+      }
+      execution = await session.executeCommand('/clear', options);
+    } else {
+      if (typeof harness?.executeCommand !== 'function') {
+        return commandResult(t('当前 Host 不支持 /clear，当前会话未修改。'));
+      }
+      execution = await harness.executeCommand(sessionId, '/clear', options);
+    }
+    if (execution === undefined) {
+      return commandResult(t('当前 Host 不支持 /clear，当前会话未修改。'));
+    }
+    const result = execution?.result;
+    if (!result || !['success', 'error'].includes(result.kind)
+      || (result.text !== undefined && typeof result.text !== 'string')) {
+      return commandResult(t('清空当前会话上下文失败，当前会话未修改，请稍后重试。'));
+    }
+    if (result.kind === 'error') {
+      return commandResult(clearErrorMessage({ ...result, failure: result.failure ?? result }));
+    }
+    return commandResult(t('当前会话上下文已清空；Session 绑定和历史记录仍保留。'));
+  } catch (error) {
+    return commandResult(clearErrorMessage(error));
+  }
+}
+
+export function isClearCommand(text) {
+  return typeof text === 'string' && CLEAR_COMMAND.test(text.trim());
+}

package/src/channels/shared/command-catalog.mjs

@@ -29,6 +29,9 @@ export const SHARED_COMMAND_CATALOG = Object.freeze([
   defineCatalogCommand('compact', '压缩当前会话的较早上下文', [
     '/compact  压缩当前会话的较早上下文',
   ]),
+  defineCatalogCommand('clear', '清空当前会话上下文并保留会话绑定', [
+    '/clear  清空当前会话上下文（保留 Session 绑定和历史记录）',
+  ]),
   defineCatalogCommand('history', '查看最近历史消息（仅私聊）', [
     '/history [数量]  查看最近历史消息（默认 3 条，最多 5 条）',
   ], { privateOnly: true }),

package/src/channels/shared/command-permission.mjs

@@ -1,5 +1,6 @@
 import { isBatchInputCommand } from './batch-input.mjs';
 import { isCompactCommand } from './compact-command.mjs';
+import { isClearCommand } from './clear-command.mjs';
 import { isControlCommand } from './control-command.mjs';
 import { isHistoryCommand } from './history-command.mjs';
 import { isModelCommand } from './model-command.mjs';
@@ -20,6 +21,7 @@ export function isSharedLocalCommand(text, {
   const command = text.trim();
   if (!command) return false;
   if (isBatchInputCommand(command) || isHistoryCommand(command)) return true;
+  if (isClearCommand(command)) return true;
   if (!hasFiles && (
     isControlCommand(command)
     || isModelCommand(command)

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

@@ -62,6 +62,7 @@ export function extractConnectionEvidence(error) {
       ...(reasons.length > 1 ? { reasons } : {}),
       httpStatus: errors.find(e => e.httpStatus !== undefined)?.httpStatus,
       providerCode: errors.find(e => e.providerCode !== undefined)?.providerCode,
+      method: first('method'), transport: first('transport'),
       durationMs: first('durationMs'), timeoutMs: first('timeoutMs'), host: first('host'), truncated,
     }),
   };

package/src/channels/shared/control-command.mjs

@@ -36,6 +36,23 @@ export function isControlCommand(text) {
   return typeof text === 'string' && CONTROL_COMMAND.test(text.trim());
 }
 
+// Shared by explicit /steer and ordinary messages configured to steer. A false
+// result guarantees no submission; exceptions must never trigger a second ask.
+export async function steerMessage(text, harness, state, key, {
+  signal, control, enhancement, pendingInteraction = false,
+} = {}) {
+  if (pendingInteraction) return false;
+  const session = boundSession(harness, state, key);
+  if (!session) return false;
+  if (typeof session.steerActiveTurn !== 'function') {
+    throw new TypeError('Harness session does not support steering active turns');
+  }
+  const steering = enhancement
+    ? enhanceContextContent(text, enhancement.snapshot, enhancement.source)
+    : text;
+  return session.steerActiveTurn(steering, control, requestOptions(signal));
+}
+
 export async function runControlCommand(text, harness, state, key, {
   signal,
   hasImages = false,
@@ -92,19 +109,11 @@ export async function runControlCommand(text, harness, state, key, {
   if (!session) {
     return commandResult(t('当前聊天没有绑定会话，无法补充指令。请先绑定会话。'));
   }
-  if (typeof session.steerActiveTurn !== 'function') {
-    throw new TypeError('Harness session does not support steering active turns');
-  }
   // A mid-turn correction carries the same provenance as the message that
   // opened the turn, so a group member who steers is identified too.
-  const steering = enhancement
-    ? enhanceContextContent(instruction, enhancement.snapshot, enhancement.source)
-    : instruction;
-  const steered = await session.steerActiveTurn(
-    steering,
-    control,
-    requestOptions(signal),
-  );
+  const steered = await steerMessage(instruction, harness, state, key, {
+    signal, control, enhancement,
+  });
   return steered
     ? commandResult(t('已提交补充指令，Agent 会在下一步读取。'))
     : commandResult(t('任务已结束，没有正在运行的任务，无法补充指令。请直接发送消息开始新任务。'));

package/src/channels/shared/diagnostic-details.mjs

@@ -20,6 +20,12 @@ const REASONS = new Set([
   'unknown', 'multiple-causes', 'timeout', 'http-error', 'provider-rejected', 'invalid-response', 'ERR_PROXY_CONNECTION_FAILED', 'ERR_TLS_HANDSHAKE_TIMEOUT', 'ERR_SSL_TLSV1_ALERT_INTERNAL_ERROR', 'ERR_NETWORK_ACCESS_DENIED', 'AUTHENTICATIONFAILED', 'EAUTH', 'invalid-json', 'invalid-config', 'read-only',
 ]);
 const RESOURCES = new Set(['credential-store', 'account-config', 'account-state', 'workspace-config', 'workspace-directory']);
+const RPC_METHODS = new Set([
+  'host.describe', 'workspace.list', 'workspace.create', 'session.list', 'session.create',
+  'session.history', 'session.prompt', 'session.rename', 'session.cancel', 'session.models',
+  'session.permissions', 'session.selectModel', 'llm.models',
+]);
+const TRANSPORTS = new Set(['host-api', 'http']);
 const CONFIG_FILES = new Set(['config.json', 'workspaces.json']);
 export const CONFIG_ISSUE_LABELS = Object.freeze({
   'expected-object': '应为 JSON 对象。',
@@ -44,7 +50,7 @@ const CONFIG_FIELD = /^(?:\$|version|accounts(?:\[\d{1,10}\](?:\.(?:accountId|ow
 export function normalizeDiagnosticDetails(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
   const result = {};
-  for (const [field, allowed] of [['operation', OPERATIONS], ['stage', STAGES], ['reason', REASONS], ['resource', RESOURCES]]) {
+  for (const [field, allowed] of [['operation', OPERATIONS], ['stage', STAGES], ['reason', REASONS], ['resource', RESOURCES], ['method', RPC_METHODS], ['transport', TRANSPORTS]]) {
     if (allowed.has(value[field])) result[field] = value[field];
   }
   if (DIAGNOSTIC_CHANNELS.includes(value.channel)) result.channel = value.channel;

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

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
 import { isAbsolute } from 'node:path';
+import { performance } from 'node:perf_hooks';
 
 import { adoptRegisteredWorkspaceSession } from './harness-session-binding.mjs';
 import { sameWorkspacePath } from './default-workspace.mjs';
@@ -1013,6 +1014,12 @@ export class HarnessClient {
   }
 
   async rpc(method, payload = {}, timeoutMs = 30_000, options = {}) {
+    const startedAt = performance.now();
+    const withDiagnostics = error => Object.assign(error, {
+      durationMs: Math.round(performance.now() - startedAt),
+      timeoutMs,
+      transport: this.#apiProxy ? 'host-api' : 'http',
+    });
     const rpcId = options.rpcId ?? `${this.#rpcIdPrefix}-${randomUUID()}`;
     const timeoutSignal = AbortSignal.timeout(timeoutMs);
     const signal = options.signal
@@ -1051,24 +1058,24 @@ export class HarnessClient {
       // Preserve an explicit caller cancellation; it is control flow, not a
       // Harness availability diagnosis.
       if (options.signal?.aborted) throw error;
-      if (error instanceof HarnessTransportError) throw error;
-      throw new HarnessTransportError(
+      if (error instanceof HarnessTransportError) throw withDiagnostics(error);
+      throw withDiagnostics(new HarnessTransportError(
         timeoutSignal.aborted ? 'harness-timeout' : 'harness-connect-failed',
         method,
         { cause: error },
-      );
+      ));
     }
     if (body?.type !== 'server-response' || body?.rpcId !== rpcId) {
-      throw new HarnessTransportError('harness-response-invalid', method, {
+      throw withDiagnostics(new HarnessTransportError('harness-response-invalid', method, {
         cause: new Error(`Harness returned an invalid response for ${method}`),
-      });
+      }));
     }
     if (!body.result || typeof body.result !== 'object' || typeof body.result.ok !== 'boolean') {
-      throw new HarnessTransportError('harness-response-invalid', method, {
+      throw withDiagnostics(new HarnessTransportError('harness-response-invalid', method, {
         cause: new Error(`Harness returned an invalid result for ${method}`),
-      });
+      }));
     }
-    if (!body.result?.ok) throw new HarnessRpcError(method, body.result?.error);
+    if (!body.result?.ok) throw withDiagnostics(new HarnessRpcError(method, body.result?.error));
     return body.result.value;
   }
 

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

@@ -47,6 +47,9 @@ export default Object.freeze({
   "暂未识别具体原因，请复制诊断信息，并查看相同参考号的 DSH 日志。": "The underlying cause is unknown. Copy the diagnostics and find the matching reference in the DSH logs.",
   "多个原因": "Multiple causes",
   "服务域名": "Service host",
+  "RPC 方法": "RPC method",
+  "调用方式": "Transport",
+  "宿主 API（进程内）": "Host API (in-process)",
   "请求耗时（毫秒）": "Request duration (ms)",
   "超时阈值（毫秒）": "Timeout (ms)",
   "Node 版本": "Node version",

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

@@ -259,10 +259,10 @@ export default {
     '/presetlist or /presets  List available Agent Presets',
   '🎮 任务控制': '🎮 Task controls',
   '/steer 指令  给 Agent 补充指令': '/steer INSTRUCTION  Steer the Agent',
-  '**📋 卡片功能**\n\n1. 会话下拉 — 切换当前绑定会话\n2. 工作区下拉 — 切换工作区\n3. 🤖 预设下拉 — 切换 Agent 预设\n4. 🧠 模型下拉 — 切换模型\n5. 🆕 新会话 — 开启全新会话\n6. 📋 会话/关注 — 查看/绑定会话，管理关注\n7. ⏹ 停止 — 停止当前任务\n8. 📐 压缩 — 压缩当前会话上下文\n9. 补充指令 — 给 Agent 发送指令\n10. 🗄 归档切换 — 显示/隐藏归档会话\n11. 📊 状态 — 查看系统连接状态\n12. 📖 帮助 — 查看本帮助':
-    '**📋 Card features**\n\n1. Session dropdown — switch the bound session\n2. Workspace dropdown — switch workspace\n3. 🤖 Preset dropdown — switch Agent Preset\n4. 🧠 Model dropdown — switch model\n5. 🆕 New session — start fresh\n6. 📋 Sessions/watches — view or bind sessions and manage watches\n7. ⏹ Stop — stop the current task\n8. 📐 Compact — compact the current session context\n9. Steer task — send an instruction to the Agent\n10. 🗄 Archived toggle — show or hide archived sessions\n11. 📊 Status — view connection status\n12. 📖 Help — view this help',
-  '**⌨️ 文本命令**\n\n`/m` — 打开菜单卡片\n`/new` — 开启全新会话\n`/session ID` — 绑定已有会话\n`/sessionlist [工作区]` 或 `/sessions [工作区]` — 列出会话\n`/sessionlist --limit N` 或 `/sessions --limit N` — 仅列出当前工作区前 N 个会话\n`/workspace 工作区序号或绝对路径` — 切换工作区\n`/workspacelist` — 列出工作区\n`/status` — 查看连接状态\n`/compact` — 压缩上下文\n`/stop` — 停止当前任务\n`/steer 指令` — 补充指令\n`/watch ID` — 关注会话\n`/watchlist` — 关注列表\n`/unwatch ID` — 取消关注\n`/archived on/off` — 归档显隐\n`/presetlist` 或 `/presets` — 列出预设\n`/preset [序号/ID]` — 切换预设\n`/preset --default` — 跟随默认\n`/models` — 列出模型\n`/reasoninglist` 或 `/reasonings` — 按序号列出当前模型可用推理等级\n`/reasoning [序号、等级ID或 --default]` — 查看或切换当前推理等级\n`/model [序号或完整模型ID] [推理等级ID]` — 查看或切换当前会话模型\n`/batch` — 开启批量输入（仅私聊，最多 10 条文字）\n`/send` — 提交当前批次\n`/cancel` — 取消当前批次\n`/repair` — 补全飞书权限与卡片回调':
-    '**⌨️ Text commands**\n\n`/m` — open the menu card\n`/new` — start a new session\n`/session ID` — bind an existing session\n`/sessionlist [workspace]` or `/sessions [workspace]` — list sessions\n`/sessionlist --limit N` or `/sessions --limit N` — list only the first N sessions in the current workspace\n`/workspace <workspace index or absolute path>` — switch workspace\n`/workspacelist` — list workspaces\n`/status` — view connection status\n`/compact` — compact context\n`/stop` — stop the current task\n`/steer INSTRUCTION` — steer the task\n`/watch ID` — watch a session\n`/watchlist` — list watched sessions\n`/unwatch ID` — stop watching\n`/archived on/off` — show or hide archived sessions\n`/presetlist` or `/presets` — list presets\n`/preset [index/ID]` — switch preset\n`/preset --default` — follow default\n`/models` — list models\n`/reasoninglist` or `/reasonings` — list reasoning efforts for the current model\n`/reasoning [index, effort ID, or --default]` — show or switch reasoning effort\n`/model [index or full model ID] [reasoning effort ID]` — show or switch the current Session model\n`/batch` — start batch input (direct messages only, up to 10 text messages)\n`/send` — submit the current batch\n`/cancel` — cancel the current batch\n`/repair` — complete Feishu permissions and the card callback',
+  '**📋 卡片功能**\n\n1. 会话下拉 — 切换当前绑定会话\n2. 工作区下拉 — 切换工作区\n3. 🤖 预设下拉 — 切换 Agent 预设\n4. 🧠 模型下拉 — 切换模型\n5. 🆕 新会话 — 开启全新会话\n6. 📋 会话/关注 — 查看/绑定会话，管理关注\n7. ⏹ 停止 — 停止当前任务\n8. 📐 压缩 — 压缩当前会话上下文\n9. 🧹 清空上下文 — 清空上下文并保留绑定和历史记录\n10. 补充指令 — 给 Agent 发送指令\n11. 🗄 归档切换 — 显示/隐藏归档会话\n12. 📊 状态 — 查看系统连接状态\n13. 📖 帮助 — 查看本帮助':
+    '**📋 Card features**\n\n1. Session dropdown — switch the bound session\n2. Workspace dropdown — switch workspace\n3. 🤖 Preset dropdown — switch Agent Preset\n4. 🧠 Model dropdown — switch model\n5. 🆕 New session — start fresh\n6. 📋 Sessions/watches — view or bind sessions and manage watches\n7. ⏹ Stop — stop the current task\n8. 📐 Compact — compact the current session context\n9. 🧹 Clear context — clear context while keeping the binding and history\n10. Steer task — send an instruction to the Agent\n11. 🗄 Archived toggle — show or hide archived sessions\n12. 📊 Status — view connection status\n13. 📖 Help — view this help',
+  '**⌨️ 文本命令**\n\n`/m` — 打开菜单卡片\n`/new` — 开启全新会话\n`/session ID` — 绑定已有会话\n`/sessionlist [工作区]` 或 `/sessions [工作区]` — 列出会话\n`/sessionlist --limit N` 或 `/sessions --limit N` — 仅列出当前工作区前 N 个会话\n`/workspace 工作区序号或绝对路径` — 切换工作区\n`/workspacelist` — 列出工作区\n`/status` — 查看连接状态\n`/compact` — 压缩上下文\n`/clear` — 清空上下文并保留 Session 绑定和历史记录\n`/stop` — 停止当前任务\n`/steer 指令` — 补充指令\n`/watch ID` — 关注会话\n`/watchlist` — 关注列表\n`/unwatch ID` — 取消关注\n`/archived on/off` — 归档显隐\n`/presetlist` 或 `/presets` — 列出预设\n`/preset [序号/ID]` — 切换预设\n`/preset --default` — 跟随默认\n`/models` — 列出模型\n`/reasoninglist` 或 `/reasonings` — 按序号列出当前模型可用推理等级\n`/reasoning [序号、等级ID或 --default]` — 查看或切换当前推理等级\n`/model [序号或完整模型ID] [推理等级ID]` — 查看或切换当前会话模型\n`/batch` — 开启批量输入（仅私聊，最多 10 条文字）\n`/send` — 提交当前批次\n`/cancel` — 取消当前批次\n`/repair` — 补全飞书权限与卡片回调':
+    '**⌨️ Text commands**\n\n`/m` — open the menu card\n`/new` — start a new session\n`/session ID` — bind an existing session\n`/sessionlist [workspace]` or `/sessions [workspace]` — list sessions\n`/sessionlist --limit N` or `/sessions --limit N` — list only the first N sessions in the current workspace\n`/workspace <workspace index or absolute path>` — switch workspace\n`/workspacelist` — list workspaces\n`/status` — view connection status\n`/compact` — compact context\n`/clear` — clear context while keeping the Session binding and history\n`/stop` — stop the current task\n`/steer INSTRUCTION` — steer the task\n`/watch ID` — watch a session\n`/watchlist` — list watched sessions\n`/unwatch ID` — stop watching\n`/archived on/off` — show or hide archived sessions\n`/presetlist` or `/presets` — list presets\n`/preset [index/ID]` — switch preset\n`/preset --default` — follow default\n`/models` — list models\n`/reasoninglist` or `/reasonings` — list reasoning efforts for the current model\n`/reasoning [index, effort ID, or --default]` — show or switch reasoning effort\n`/model [index or full model ID] [reasoning effort ID]` — show or switch the current Session model\n`/batch` — start batch input (direct messages only, up to 10 text messages)\n`/send` — submit the current batch\n`/cancel` — cancel the current batch\n`/repair` — complete Feishu permissions and the card callback',
   '**💡 数字兜底**\n回复数字快速操作：\n**1**工作区列表 · **2**新会话 · **3**会话/关注\n**4**状态 · **5**补全权限 · **6**帮助':
     '**💡 Number fallback**\nReply with a number for a quick action:\n**1** Workspace list · **2** New session · **3** Sessions/watches\n**4** Status · **5** Complete permissions · **6** Help',
   '从下方下拉选择补充指令；最后一项可自定义输入。':
@@ -319,6 +319,8 @@ export default {
   '/watch ID 或序号  关注会话（完成后推送）':
     '/watch ID or index  Watch a session (push when done)',
   '/compact  压缩上下文': '/compact  Compact the context',
+  '🧹 清空上下文': '🧹 Clear context',
+  '清空当前会话上下文并保留绑定和历史记录': 'Clear the current session context while keeping the binding and history',
   '/workspace 绝对路径  切换工作区': '/workspace <absolute path>  Switch workspace',
   '/presetlist  列出可用 Agent Preset': '/presetlist  List available Agent Presets',
   '任务完成会自动推送，回复数字或点按钮取消关注：':

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

@@ -29,7 +29,8 @@ export default {
   '发送 /m 打开助手中心，点击按钮或回复当前列表的数字选择。': 'Send /m to open the assistant menu. Click a button or reply with a number from the current list.',
   '设置：会话、工作区、模式／预设、模型。': 'Settings: session, workspace, mode / preset, model.',
   '会话：新会话、会话列表、归档显示切换。': 'Sessions: new session, session list, show or hide archived sessions.',
-  '任务：停止、压缩、快捷或自定义补充指令。': 'Tasks: stop, compact, quick or custom steering instructions.',
+  '任务：停止、压缩、清空上下文、快捷或自定义补充指令。':
+    'Tasks: stop, compact, clear context, quick or custom steering instructions.',
   '信息：状态、帮助。': 'Information: status, help.',
   '菜单有效期为 15 分钟；发送普通消息会退出数字选择。': 'Menus expire after 15 minutes. Sending an ordinary message exits number selection.',
   '回答问题、审批和批量输入时，数字优先用于当前交互。': 'During questions, approvals and batch input, numbers belong to that interaction.',

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

@@ -244,6 +244,32 @@ export default {
   '当前 Harness 未注册 /compact 命令，请确认上下文压缩组件已启用。':
     'The current Harness has not registered the /compact command; please make sure the context compaction component is enabled.',
 
+  // clear-command.mjs
+  '/clear  清空当前会话上下文（保留 Session 绑定和历史记录）':
+    '/clear  Clear the current session context (keep the Session binding and history)',
+  '清空当前会话上下文并保留会话绑定':
+    'Clear the current session context and keep the Session binding',
+  '用法：/clear（不带参数且不可附带图片或文件）':
+    'Usage: /clear (no arguments, images or files)',
+  '当前聊天绑定的会话已不存在，未清空上下文；请先发送新消息开启会话。':
+    'The Session bound to this chat no longer exists; the context was not cleared. Send a new message to start a Session first.',
+  '当前会话正在生成回复或等待交互，请先完成交互或发送 /stop，再执行 /clear。':
+    'The current Session is generating a reply or waiting for an interaction. Finish it or send /stop before running /clear.',
+  '上下文清理已取消，当前会话未修改。':
+    'Context clearing was cancelled; the current Session was not changed.',
+  '工作区或机器人状态已发生变化，未清空当前会话，请重试。':
+    'The workspace or bot state changed, so the current Session was not cleared. Please try again.',
+  '当前 Host 不支持 /clear，当前会话未修改。':
+    'The current Host does not support /clear; the current Session was not changed.',
+  '清空当前会话上下文失败，当前会话未修改，请稍后重试。':
+    'Failed to clear the current Session context; the Session was not changed. Please try again later.',
+  '当前机器人没有可用的会话状态，未清空当前会话。':
+    'This bot has no available Session state; the current Session was not cleared.',
+  '当前聊天还没有可清空的会话，请先发送一条消息。':
+    'This chat has no Session to clear yet; please send a message first.',
+  '当前会话上下文已清空；Session 绑定和历史记录仍保留。':
+    'The current Session context was cleared; its binding and history were retained.',
+
   // control-command.mjs
   '用法：/stop（不带参数）': 'Usage: /stop (no arguments)',
   '用法：/version（不带参数）': 'Usage: /version (no arguments)',
@@ -258,6 +284,7 @@ export default {
     'No session is bound to this chat, so an additional instruction cannot be given. Bind a session first.',
   '任务已结束，没有正在运行的任务，无法补充指令。请直接发送消息开始新任务。':
     'The task has ended and there is no running task to steer. Send a message to start a new task.',
+  '已排队，等待前序消息处理。': 'Queued. Waiting for the preceding messages to finish.',
   '已提交补充指令，Agent 会在下一步读取。':
     'Additional instruction submitted; the Agent will read it at the next step.',
 };