@xmanrui/dsh-im 4.21.2 → 4.23.0

package/plugin-src/host/channels/email/rpc.mjs

@@ -0,0 +1,163 @@
+import { createConnectionDiagnostics, diagnosticRpcResult } from '../../../../src/channels/shared/connection-error.mjs';
+import { createTokenBotRpcHandler } from '../shared/rpc.mjs';
+import { registerManagementRpc } from '../../../management-rpc.mjs';
+import { resolveRpcAuthority } from '../../rpc-authority.mjs';
+
+export const EMAIL_RPC_CHANNEL = '/email';
+export const EMAIL_ENDPOINTS = Object.freeze({
+  status: 'connection.status',
+  // Lets the client hide the mailbox entry point while the channel is closed,
+  // instead of offering a form whose submissions the Host would refuse.
+  availability: 'channel.availability',
+  bindMailbox: 'bot.bind-mailbox',
+  updateMailbox: 'bot.mailbox.update',
+  reconnectBot: 'bot.reconnect',
+  deleteBot: 'bot.delete',
+  setWorkspace: 'bot.workspace.set',
+  setModel: 'bot.model.set',
+  setAgentPreset: 'bot.agent-preset.set',
+  setContextEnhancement: 'bot.context-enhancement.set',
+  setAccessPolicy: 'bot.access-policy.set',
+  setAlias: 'bot.alias.set',
+  // Session binding: read the current bindings, change them, and list the
+  // candidate sessions for the picker.
+  // QR device flow for transports that authorize out of band (Agent mailbox).
+  startAuth: 'bot.auth.start',
+  pollAuth: 'bot.auth.poll',
+  getBinding: 'bot.session-binding.get',
+  setBinding: 'bot.session-binding.set',
+  listSessions: 'bot.session.list',
+});
+export const EMAIL_RPC_ENDPOINTS = Object.freeze(Object.values(EMAIL_ENDPOINTS));
+
+/** The mailbox fields, with the addressing field removed. */
+function stripBotId(payload) {
+  if (!payload || typeof payload !== 'object') return {};
+  const { botId, update, ...rest } = payload;
+  return rest;
+}
+
+function failure(code, error) {
+  return {
+    ok: false,
+    error: {
+      code: error?.code ?? code,
+      message: error?.message ?? String(error),
+      details: error?.details ?? {},
+    },
+  };
+}
+
+function withRpcDetails(result) {
+  if (result?.ok !== false) return result;
+  return { ...result, error: { ...result.error, details: result.error?.details ?? {} } };
+}
+
+/**
+ * Mailbox-specific endpoints are handled here; everything else (status,
+ * reconnect, delete, workspace, model, preset, alias, access policy) goes
+ * through the shared token-bot handler, which already knows the endpoint
+ * payload shapes.
+ */
+export function createEmailRpcHandler(controller) {
+  const diagnostics = controller.diagnostics ?? createConnectionDiagnostics({ channel: 'email' });
+  // Availability is answered before anything else, including the controller
+  // shape check: the client asks this endpoint to decide whether to show the
+  // mailbox entry point at all, so it must work even while the channel is
+  // closed and no controller is wired.
+  //
+  // While the channel is closed the settings page must still get a clear,
+  // non-throwing answer rather than a crash from an unwired controller; every
+  // other endpoint fails closed through `controller.disabled()`.
+  const disabled = typeof controller?.disabled === 'function';
+  const closed = disabled ? controller.disabled() : null;
+  const shared = disabled ? null : createTokenBotRpcHandler(controller, { channel: 'Email' });
+  return async (endpoint, payload, signal) => {
+    if (endpoint === EMAIL_ENDPOINTS.availability) {
+      return { ok: true, value: { enabled: !disabled } };
+    }
+    if (disabled) return closed;
+    if (endpoint === EMAIL_ENDPOINTS.bindMailbox) {
+      try {
+        return { ok: true, value: await controller.bindMailbox(payload ?? {}) };
+      } catch (error) {
+        return diagnosticRpcResult(diagnostics, error, withRpcDetails({
+          ok: false,
+          error: {
+            code: error?.code ?? 'email-bind-failed',
+            message: error?.message ?? String(error),
+            details: error?.details ?? {},
+          },
+        }), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
+      }
+    }
+    if (endpoint === EMAIL_ENDPOINTS.startAuth) {
+      try {
+        return { ok: true, value: await controller.startAuthorization(payload ?? {}) };
+      } catch (error) {
+        return diagnosticRpcResult(diagnostics, error, failure('email-auth-failed', error), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
+      }
+    }
+    if (endpoint === EMAIL_ENDPOINTS.pollAuth) {
+      try {
+        return { ok: true, value: await controller.pollAuthorization(payload ?? {}) };
+      } catch (error) {
+        return diagnosticRpcResult(diagnostics, error, failure('email-auth-failed', error), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
+      }
+    }
+    if (endpoint === EMAIL_ENDPOINTS.getBinding) {
+      try {
+        return { ok: true, value: await controller.getSessionBinding(payload?.botId) };
+      } catch (error) {
+        return diagnosticRpcResult(diagnostics, error, failure('email-binding-failed', error), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
+      }
+    }
+    if (endpoint === EMAIL_ENDPOINTS.setBinding) {
+      try {
+        return { ok: true, value: await controller.setSessionBinding(payload?.botId, payload ?? {}) };
+      } catch (error) {
+        return diagnosticRpcResult(diagnostics, error, failure('email-binding-failed', error), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
+      }
+    }
+    if (endpoint === EMAIL_ENDPOINTS.listSessions) {
+      try {
+        return { ok: true, value: await controller.listSessions(payload?.botId) };
+      } catch (error) {
+        return diagnosticRpcResult(diagnostics, error, failure('email-sessions-failed', error), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
+      }
+    }
+    if (endpoint === EMAIL_ENDPOINTS.updateMailbox) {
+      try {
+        return {
+          ok: true,
+          // The client sends the mailbox fields flat alongside botId (as every
+          // other endpoint here does). Reading a nested `update` silently
+          // discarded the whole change: the call succeeded and nothing moved.
+          value: await controller.updateMailboxSettings(
+            payload?.botId,
+            payload?.update ?? stripBotId(payload),
+          ),
+        };
+      } catch (error) {
+        return diagnosticRpcResult(diagnostics, error, withRpcDetails({
+          ok: false,
+          error: {
+            code: error?.code ?? 'email-update-failed',
+            message: error?.message ?? String(error),
+            details: error?.details ?? {},
+          },
+        }), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
+      }
+    }
+    return withRpcDetails(await shared(endpoint, payload, signal));
+  };
+}
+
+export function installEmailRpc(ctx, controller, authority) {
+  return registerManagementRpc(
+    ctx,
+    EMAIL_RPC_CHANNEL,
+    createEmailRpcHandler(controller),
+    { authority: resolveRpcAuthority(authority) },
+  );
+}

package/plugin-src/host/channels/feishu/production.mjs

@@ -1,3 +1,4 @@
+import { getImageInputSettingsStore } from '../../../../src/channels/shared/image-input-settings-store.mjs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { unlink } from 'node:fs/promises';
@@ -26,6 +27,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -117,7 +119,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -201,6 +203,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     // This plugin is already hosted by a running DSH process. Starting a
     // second DSH would create a competing server and lifecycle.
     autostart: false,
@@ -209,12 +212,14 @@ export async function createProductionController(ctx, config = {}, internals = {
     ...(controlExecutor ? { controlExecutor } : {}),
     ...(sessionMaintenanceExecutor ? { sessionMaintenanceExecutor } : {}),
     ...(fileIngressExecutor ? { fileIngressExecutor } : {}),
+    imageInputPolicy: () => getImageInputSettingsStore(config).get(),
   });
   const proxyEnv = internals.proxyEnv ?? process.env;
   const wsAgent = createFeishuWebSocketAgent(proxyEnv, internals.createProxyAgent);
 
   const modelCatalog = () => listModelCatalog(harness);
   const coreController = new Controller({
+    logger,
     registerApp: (options) => lark.registerApp(options),
     verifyApp,
     credentials: ctx.credentials,

package/plugin-src/host/channels/feishu/rpc.mjs

@@ -1,3 +1,5 @@
+import { diagnosticFields } from '../../../../src/channels/shared/diagnostic-details.mjs';
+import { createConnectionDiagnostics, diagnosticRpcResult } from '../../../../src/channels/shared/connection-error.mjs';
 import { normalizeBotAlias } from '../../../../src/channels/shared/bot-alias.mjs';
 import { SET_ALIAS_ENDPOINT, validAliasPayload } from '../shared/bot-alias-rpc.mjs';
 import { registerManagementRpc } from '../../../management-rpc.mjs';
@@ -137,7 +139,7 @@ function publicError(error) {
   const code = typeof error.code === 'string' && Object.hasOwn(PUBLIC_ERROR_MESSAGES, error.code)
     ? error.code
     : 'registration_failed';
-  return { code, message: PUBLIC_ERROR_MESSAGES[code] };
+  return { code, message: PUBLIC_ERROR_MESSAGES[code], ...diagnosticFields(error) };
 }
 
 function publicRegistration(registration) {
@@ -560,6 +562,7 @@ function assertController(controller) {
 
 /** DSH rc.6 handler: (endpoint, payload, signal) => Promise<RpcResult>. */
 export function createFeishuRpcHandler(controller, { encodeQr = qrCodeDataUrl } = {}) {
+  const diagnostics = controller.diagnostics ?? createConnectionDiagnostics({ channel: 'feishu' });
   assertController(controller);
   const qrCache = new Map();
   const attemptQr = new Map();
@@ -721,7 +724,7 @@ export function createFeishuRpcHandler(controller, { encodeQr = qrCodeDataUrl }
               testError = error;
             }
           }
-          value = { ...value, testMessage: publicConnectionTestResult(testError) };
+          value = { ...value, testMessage: publicConnectionTestResult(testError, { diagnostics, botId: payload.botId }) };
         }
       } else if (endpoint === FEISHU_MULTI_ENDPOINTS.disconnectBot) {
         if (typeof controller.disconnectBot !== 'function') throw new Error('Multi-bot disconnect is unavailable');
@@ -802,9 +805,9 @@ export function createFeishuRpcHandler(controller, { encodeQr = qrCodeDataUrl }
       return { ok: true, value };
     } catch (error) {
       const workspaceError = publicWorkspaceError(error);
-      return signal?.aborted ? cancelled() : workspaceError
+      return diagnosticRpcResult(diagnostics, error, signal?.aborted ? cancelled() : workspaceError
         ? { ok: false, error: { ...workspaceError, details: {} } }
-        : internalFailure();
+        : internalFailure(), { operation: endpoint, botId: payload?.botId });
     }
   };
 }

package/plugin-src/host/channels/imessage/rpc.mjs

@@ -1,3 +1,4 @@
+import { createConnectionDiagnostics, diagnosticRpcResult } from '../../../../src/channels/shared/connection-error.mjs';
 import { createTokenBotRpcHandler } from '../shared/rpc.mjs';
 import { registerManagementRpc } from '../../../management-rpc.mjs';
 import { resolveRpcAuthority } from '../../rpc-authority.mjs';
@@ -28,32 +29,38 @@ function withRpcDetails(result) {
 }
 
 export function createIMessageRpcHandler(controller) {
+  const diagnostics = controller.diagnostics ?? createConnectionDiagnostics({ channel: 'imessage' });
   const tokenHandler = createTokenBotRpcHandler(controller, {
     channel: 'iMessage',
   });
   return async (endpoint, payload, signal) => {
     if (endpoint === IMESSAGE_ENDPOINTS.status) {
-      const value = await controller.status();
-      return { ok: true, value: { ...value, permissions: await controller.permissions() } };
+      try {
+        const value = await controller.status();
+        return { ok: true, value: { ...value, permissions: await controller.permissions() } };
+      } catch (error) {
+        return diagnosticRpcResult(diagnostics, error, { ok: false, error: { code: 'status-failed' } },
+          { operation: endpoint, untrustedPublicError: true });
+      }
     }
     if (endpoint === IMESSAGE_ENDPOINTS.permissions) {
       try {
         return { ok: true, value: await controller.permissions() };
       } catch (error) {
-        return withRpcDetails({
+        return diagnosticRpcResult(diagnostics, error, withRpcDetails({
           ok: false,
           error: { code: 'permissions-check-failed', message: error.message },
-        });
+        }), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
       }
     }
     if (endpoint === IMESSAGE_ENDPOINTS.bindNative) {
       try {
         return { ok: true, value: await controller.bindNative() };
       } catch (error) {
-        return withRpcDetails({
+        return diagnosticRpcResult(diagnostics, error, withRpcDetails({
           ok: false,
           error: { code: error.code ?? 'imessage-bind-failed', message: error.message },
-        });
+        }), { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
       }
     }
     const translated = endpoint === IMESSAGE_ENDPOINTS.setModel ? 'bot.model.set' : endpoint;

package/plugin-src/host/channels/office/rpc.mjs

@@ -1,3 +1,4 @@
+import { createConnectionDiagnostics, diagnosticRpcResult } from '../../../../src/channels/shared/connection-error.mjs';
 import { registerManagementRpc } from '../../../management-rpc.mjs';
 import { resolveRpcAuthority } from '../../rpc-authority.mjs';
 import { OFFICE_RPC_CHANNEL, OFFICE_RPC_ENDPOINTS } from '../../../../src/channels/office/protocol.mjs';
@@ -15,6 +16,7 @@ function validConfigure(payload) {
 }
 
 export function createOfficeRpcHandler(controller) {
+  const diagnostics = controller.diagnostics ?? createConnectionDiagnostics({ channel: 'office' });
   for (const method of ['status', 'configure', 'reconnect', 'test', 'remove']) {
     if (typeof controller?.[method] !== 'function') throw new TypeError(`AI Office controller requires ${method}()`);
   }
@@ -35,7 +37,7 @@ export function createOfficeRpcHandler(controller) {
       const message = code === 'invalid-device-token' ? 'AI Office Device Token 无效。'
         : code === 'office-hook-unavailable' ? 'AI Office Hook 尚未上线或地址不正确。'
           : error instanceof TypeError ? error.message : 'AI Office 连接操作失败，请稍后重试。';
-      return { ok: false, error: { code, message } };
+      return diagnosticRpcResult(diagnostics, error, { ok: false, error: { code, message } }, { operation: endpoint, botId: payload?.botId, untrustedPublicError: true });
     }
   };
 }

package/plugin-src/host/channels/qq/production.mjs

@@ -1,3 +1,4 @@
+import { getImageInputSettingsStore } from '../../../../src/channels/shared/image-input-settings-store.mjs';
 import { unlink } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
@@ -14,6 +15,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -55,7 +57,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -96,12 +98,14 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),
     ...(controlExecutor ? { controlExecutor } : {}),
     ...(sessionMaintenanceExecutor ? { sessionMaintenanceExecutor } : {}),
     ...(fileIngressExecutor ? { fileIngressExecutor } : {}),
+    imageInputPolicy: () => getImageInputSettingsStore(config).get(),
   });
   const modelCatalog = () => listModelCatalog(harness);
   const coreController = new Controller({

package/plugin-src/host/channels/qq/rpc.mjs

@@ -1,3 +1,4 @@
+import { createConnectionDiagnostics, diagnosticRpcResult } from '../../../../src/channels/shared/connection-error.mjs';
 import { SET_ALIAS_ENDPOINT, validAliasPayload } from '../shared/bot-alias-rpc.mjs';
 import { registerManagementRpc } from '../../../management-rpc.mjs';
 import QRCode from 'qrcode';
@@ -132,6 +133,7 @@ async function publicStatus(status, encodeQr) {
 }
 
 export function createQqRpcHandler(controller, { encodeQr = qrDataUrl } = {}) {
+  const diagnostics = controller.diagnostics ?? createConnectionDiagnostics({ channel: 'qq' });
   for (const method of ['status', 'startProvisioning', 'registrationStatus', 'cancelProvisioning', 'bindCredentials', 'reconnectBot', 'deleteBot']) {
     if (typeof controller?.[method] !== 'function') throw new TypeError(`A complete QQ controller is required (${method})`);
   }
@@ -183,7 +185,7 @@ export function createQqRpcHandler(controller, { encodeQr = qrDataUrl } = {}) {
             } catch (error) {
               testError = error;
             }
-            testMessage = publicConnectionTestResult(testError);
+            testMessage = publicConnectionTestResult(testError, { diagnostics, botId: payload.botId });
           }
         }
         value = await publicStatus({
@@ -231,10 +233,10 @@ export function createQqRpcHandler(controller, { encodeQr = qrDataUrl } = {}) {
         : { ok: true, value };
     } catch (error) {
       const workspaceError = publicWorkspaceError(error);
-      return signal?.aborted
+      return diagnosticRpcResult(diagnostics, error, signal?.aborted
         ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
         : { ok: false, error: publicQqStateError(error) ?? workspaceError
-          ?? { code: 'qq-operation-failed', message: 'QQ 操作失败，请稍后重试。' } };
+          ?? { code: 'qq-operation-failed', message: 'QQ 操作失败，请稍后重试。' } }, { operation: endpoint, botId: payload?.botId });
     }
   };
 }

package/plugin-src/host/channels/shared/production.mjs

@@ -1,3 +1,4 @@
+import { getImageInputSettingsStore } from '../../../../src/channels/shared/image-input-settings-store.mjs';
 import { unlink } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
@@ -16,6 +17,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import {
@@ -65,7 +67,7 @@ export async function createTokenProductionController(ctx, config, internals, de
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config, channel);
   const configStore = await new ResolvedConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -78,6 +80,16 @@ export async function createTokenProductionController(ctx, config, internals, de
   const observedConfigStore = typeof configStore.remove === 'function'
     ? observeBotWorkspaceRemovals(configStore, { workspaces })
     : configStore;
+  // Idempotent, and shared with createRuntime below so both paths seed a new
+  // bot's workspace identically. A channel that must write something into the
+  // workspace store before the runtime exists (email pushes its sender
+  // allowlist into the access policy) needs the record to exist first —
+  // setAccessPolicy refuses a bot the store has never seen. The call is safe to
+  // repeat: ensure() only seeds the policy when the bot has none yet.
+  const ensureWorkspace = (botId, botConfig) => workspaces.ensure(botId, {
+    defaultAgentPreset: config.agentPreset,
+    initialAccessPolicy: seedAccessPolicy(botConfig),
+  });
   const stateStores = new Map();
   const statePath = (botId) => resolve(paths.bots, botId, 'state.json');
   const stateFor = async (botId) => {
@@ -105,32 +117,68 @@ export async function createTokenProductionController(ctx, config, internals, de
   const harness = new ResolvedHarness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),
     ...(controlExecutor ? { controlExecutor } : {}),
     ...(sessionMaintenanceExecutor ? { sessionMaintenanceExecutor } : {}),
     ...(fileIngressExecutor ? { fileIngressExecutor } : {}),
+    imageInputPolicy: () => getImageInputSettingsStore(config).get(),
   });
   const modelCatalog = () => listModelCatalog(harness);
+  // Assigned just below. A transport may need to write a rotated token back
+  // through the controller, which is only constructible after createRuntime is
+  // defined, so the reference is held in a slot rather than captured directly.
+  let controllerRef = null;
   const coreController = new ResolvedController({
     credentials: ctx.credentials,
     configStore: observedConfigStore,
     logger,
     ...(internals.inspectToken ? { inspectToken: internals.inspectToken } : {}),
-    createRuntime: async ({ botId, config: botConfig, token }) => {
+    // Optional per-channel hook: a channel whose own settings also express an
+    // access rule (email's sender allowlist) can push the derived policy into
+    // the workspace store, which is what the runtime actually reads.
+    ...(typeof definitions.accessPolicyForBot === 'function' ? {
+      syncAccessPolicy: async (botId, policy) => {
+        await workspaces.setAccessPolicy(botId, policy, {
+          incarnation: workspaces.incarnationFor(botId),
+        });
+      },
+      // Exposed so the controller can create the workspace record before it
+      // pushes a policy into it.
+      ensureWorkspace,
+    } : {}),
+    // Channels that pin conversations to an existing session need the per-bot
+    // state and the session catalog to drive their settings UI.
+    ...(definitions.supportsSessionBinding ? {
+      stateFor,
+      listWorkspaceSessions: (workspace) => harness.listWorkspaceSessions(workspace),
+      botWorkspaceFor: (botId) => workspaces.workspaceFor(botId),
+      defaultWorkspace,
+    } : {}),
+    createRuntime: async ({ botId, config: botConfig, token, credential, createTransport }) => {
       const state = await stateFor(botId);
-      await workspaces.ensure(botId, {
-        defaultAgentPreset: config.agentPreset,
-        initialAccessPolicy: seedAccessPolicy(botConfig),
-      });
+      await ensureWorkspace(botId, botConfig);
       const workspaceScope = createBotWorkspaceScope(harness, {
         botId, workspaces, state, agentPresetCatalog,
       });
+      const persistTokens = typeof definitions.persistBotCredential === 'function'
+        ? (tokens) => definitions.persistBotCredential({
+          botId, config: botConfig, tokens, controller: controllerRef,
+        })
+        : null;
       return new ResolvedRuntime({
         ...channelRuntimeOptions,
         config: botConfig,
         token,
+        // The mailbox may authenticate with an OAuth pair instead of a password.
+        ...(credential ? { credential } : {}),
+        // A transport that rotates its tokens needs them written back.
+        ...(persistTokens ? { onTokensRefreshed: persistTokens } : {}),
+        // The channel decides which transport a mailbox uses; without this the
+        // runtime falls back to its own IMAP/SMTP default.
+        ...(typeof createTransport === 'function' ? { createTransport } : {}),
         harness: workspaceScope.harness,
         state: workspaceScope.state,
         contextEnhancement: { botId, getSettings: () => workspaces.contextEnhancementFor(botId) },
@@ -159,6 +207,7 @@ export async function createTokenProductionController(ctx, config, internals, de
       }
     },
   });
+  controllerRef = coreController;
   const controller = createWorkspaceAwareController(coreController, {
     workspaces,
     stateFor,

package/plugin-src/host/channels/shared/rpc.mjs

@@ -1,3 +1,4 @@
+import { createConnectionDiagnostics, diagnosticRpcResult } from '../../../../src/channels/shared/connection-error.mjs';
 import { SET_ALIAS_ENDPOINT, validAliasPayload } from './bot-alias-rpc.mjs';
 import { registerManagementRpc } from '../../../management-rpc.mjs';
 import { SET_CONTEXT_ENHANCEMENT_ENDPOINT, validContextEnhancementPayload } from './context-enhancement-rpc.mjs';
@@ -131,6 +132,7 @@ function operationError(channel, error) {
 }
 
 export function createTokenBotRpcHandler(controller, { channel }) {
+  const diagnostics = controller.diagnostics ?? createConnectionDiagnostics({ channel: channel.toLowerCase() });
   for (const method of ['status', 'bindCredentials', 'reconnectBot', 'deleteBot']) {
     if (typeof controller?.[method] !== 'function') {
       throw new TypeError(`A complete ${channel} controller is required (${method})`);
@@ -172,7 +174,7 @@ export function createTokenBotRpcHandler(controller, { channel }) {
           } catch (error) {
             testError = error;
           }
-          value = { ...value, testMessage: publicConnectionTestResult(testError) };
+          value = { ...value, testMessage: publicConnectionTestResult(testError, { diagnostics, botId: payload.botId }) };
         }
       } else if (endpoint === TOKEN_BOT_ENDPOINTS.setWorkspace) {
         if (typeof controller.updateWorkspace !== 'function') throw new Error('Workspace update is unavailable');
@@ -199,9 +201,9 @@ export function createTokenBotRpcHandler(controller, { channel }) {
         ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
         : { ok: true, value: sanitizePublic(value) };
     } catch (error) {
-      return signal?.aborted
+      return diagnosticRpcResult(diagnostics, error, signal?.aborted
         ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
-        : { ok: false, error: operationError(channel, error) };
+        : { ok: false, error: operationError(channel, error) }, { operation: endpoint, botId: payload?.botId });
     }
   };
 }

package/plugin-src/host/channels/shared/startup-error.mjs

@@ -3,7 +3,8 @@ import { t } from '../../../../src/channels/shared/i18n.mjs';
 const CHANNEL_NAMES = {
   weixin: '微信', feishu: '飞书', dingtalk: '钉钉', wecom: '企业微信',
   'wecom-app': '企业微信应用', qq: 'QQ', slack: 'Slack', telegram: 'Telegram',
-  discord: 'Discord', whatsapp: 'WhatsApp', office: 'AI Office',
+  discord: 'Discord', whatsapp: 'WhatsApp', imessage: 'iMessage',
+  email: '邮箱', office: 'AI Office',
 };
 const INVALID_CONFIG_MESSAGES = new Set([
   'dsh-weixin config contains invalid account data',
@@ -11,7 +12,7 @@ const INVALID_CONFIG_MESSAGES = new Set([
   'dsh-feishu config contains duplicate bot identities',
   'dsh-feishu config is incomplete or invalid',
   'dsh-dingtalk config contains invalid bot data',
-  ...['Enterprise WeChat', 'Enterprise WeChat app', 'QQ', 'Slack', 'Telegram', 'Discord']
+  ...['Enterprise WeChat', 'Enterprise WeChat app', 'QQ', 'Slack', 'Telegram', 'Discord', 'Email']
     .map(channel => `dsh-im ${channel} config contains invalid bot data`),
   'dsh-im WhatsApp config contains invalid account data',
   'dsh-im AI Office config is invalid',
@@ -47,7 +48,7 @@ export function publicChannelStartupError(channel, error) {
   }
   return {
     code: `${channel}-startup-failed`,
-    message: t('{channel}初始化失败。请查看 DSH 启动日志中 failed to activate {id} 后的错误，修复后重启 DSH。', params),
+    message: t('{channel}初始化失败。请展开诊断详情，并通过参考号查找 DSH 启动日志，修复后重启 DSH。', params),
     details: {},
   };
 }

package/plugin-src/host/channels/shared/startup.mjs

@@ -2,6 +2,7 @@ import { registerManagementRpc } from '../../../management-rpc.mjs';
 import { onImHostLanguageChange } from '../../../../src/channels/shared/i18n.mjs';
 import { resolveRpcAuthority } from '../../rpc-authority.mjs';
 import { publicChannelInitializing, publicChannelStartupError } from './startup-error.mjs';
+import { createConnectionDiagnostics, diagnosticRpcResult } from '../../../../src/channels/shared/connection-error.mjs';
 
 /**
  * Keep a channel's platform-side command menu in the current host message
@@ -30,13 +31,18 @@ export async function installProductionChannel(ctx, config, {
 }) {
   let startupError = publicChannelInitializing(channel);
   let handler = async () => ({ ok: false, error: startupError });
-  const disposeRpc = registerManagementRpc(ctx, rpcChannel, (endpoint, payload, signal) => {
+  const logger = typeof ctx.logger === 'function' ? ctx.logger(`dsh-im:${channel}`) : (ctx.logger ?? console);
+  const diagnostics = createConnectionDiagnostics({ channel, logger });
+  const disposeRpc = registerManagementRpc(ctx, rpcChannel, async (endpoint, payload, signal) => {
     if (signal?.aborted) {
       return { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.', details: {} } };
     }
-    return handler(endpoint, payload, signal);
+    try { return await handler(endpoint, payload, signal); }
+    catch (error) {
+      // Preserve a final Host diagnostic if an endpoint misses its own catch.
+      return diagnosticRpcResult(diagnostics, error, { ok: false, error: { code: `${channel}-operation-failed` } }, { operation: endpoint });
+    }
   }, { authority: resolveRpcAuthority(config.rpcAuthority) });
-  const logger = typeof ctx.logger === 'function' ? ctx.logger(`dsh-im:${channel}`) : (ctx.logger ?? console);
   let production;
   let unregisterDelivery;
   let closing;
@@ -58,13 +64,12 @@ export async function installProductionChannel(ctx, config, {
   } catch (error) {
     startupError = reportStartupError
       ? reportStartupError(error, false)
-      : publicChannelStartupError(channel, error);
-    if (!reportStartupError) logger.error?.(`[dsh-im] failed to activate ${channel}; management RPC remains available`, error);
+      : diagnostics.report(error, { operation: 'startup', stage: 'startup.load', publicError: publicChannelStartupError(channel, error) }).publicError;
     try {
       await closeProduction();
     } catch (cleanupError) {
       if (reportStartupError) reportStartupError(cleanupError, true);
-      else logger.error?.(`[dsh-im] failed to close partially initialized ${channel} resources`, cleanupError);
+      else diagnostics.report(cleanupError, { operation: 'startup', stage: 'connection.stop', warning: true });
     }
   }
   return disposeRpc;