@xmanrui/dsh-im 4.24.1 → 4.25.0

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

@@ -0,0 +1,227 @@
+import { unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { MatrixConfigStore, MatrixSidecarStore } from '../../../../src/channels/matrix/matrix-config-store.mjs';
+import { MatrixController } from '../../../../src/channels/matrix/matrix-controller.mjs';
+import { MatrixCryptoStore, matrixCryptoPathFor } from '../../../../src/channels/matrix/matrix-crypto-store.mjs';
+import { MatrixHarnessClient } from '../../../../src/channels/matrix/matrix-harness-client.mjs';
+import { MatrixRuntime } from '../../../../src/channels/matrix/matrix-runtime.mjs';
+import { ConversationStateStore } from '../../../../src/channels/shared/conversation-state-store.mjs';
+import {
+  BotWorkspaceStore,
+  createBotWorkspaceScope,
+  createWorkspaceAwareController,
+  observeBotWorkspaceRemovals,
+} from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
+import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
+import { commandsForChannel } from '../../../../src/channels/shared/command-catalog.mjs';
+import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
+import { createTokenConnectionSupervisor } from '../shared/connection-supervisor.mjs';
+import { pluginPaths } from '../shared/production.mjs';
+import { createHarnessCommandExecutor } from '../../harness-command-executor.mjs';
+import { harnessConnection } from '../../harness-connection.mjs';
+import { createHarnessSessionExecutors } from '../../harness-session-coordinator.mjs';
+import {
+  getInboundTtlRuntime,
+  registerInboundTtlWorkspaces,
+} from '../../inbound-ttl-runtime.mjs';
+import {
+  accessPolicyProvider,
+  initialAccessPolicyFor,
+} from '../shared/access-policy-production.mjs';
+
+export async function createProductionController(ctx, config = {}, internals = {}) {
+  if (!ctx?.credentials) throw new TypeError('dsh-im matrix requires ctx.credentials');
+  const connection = harnessConnection(ctx, config);
+
+  const ResolvedConfigStore = internals.ConfigStore ?? MatrixConfigStore;
+  const ResolvedStateStore = internals.StateStore ?? ConversationStateStore;
+  const ResolvedSidecarStore = internals.SidecarStore ?? MatrixSidecarStore;
+  const ResolvedHarness = internals.HarnessClient ?? MatrixHarnessClient;
+  const ResolvedController = internals.Controller ?? MatrixController;
+  const ResolvedRuntime = internals.Runtime ?? MatrixRuntime;
+  const createSupervisor = internals.createConnectionSupervisor ?? createTokenConnectionSupervisor;
+  const logger = typeof ctx.logger === 'function'
+    ? ctx.logger('dsh-im:matrix') : (ctx.logger ?? console);
+  const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
+  const paths = pluginPaths(config, 'matrix');
+  const configStore = await new ResolvedConfigStore(paths.config).load();
+  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
+  const workspaces = internals.workspaces
+    ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
+  const configuredBots = configStore.list();
+  await workspaces.reconcile(configuredBots.map((bot) => bot.botId));
+  await Promise.all(configuredBots.map((bot) => workspaces.ensure(bot.botId, {
+    defaultAgentPreset: config.agentPreset,
+    initialAccessPolicy: initialAccessPolicyFor('matrix', bot),
+  })));
+  const observedConfigStore = typeof configStore.remove === 'function'
+    ? observeBotWorkspaceRemovals(configStore, { workspaces })
+    : configStore;
+  const stateStores = new Map();
+  const sidecarStores = new Map();
+  const cryptoStores = new Map();
+  const ResolvedCryptoStore = internals.CryptoStore ?? MatrixCryptoStore;
+  const statePath = (botId) => resolve(paths.bots, botId, 'state.json');
+  const sidecarPath = (botId) => resolve(paths.bots, botId, 'matrix.json');
+  const cryptoPath = (botId) => matrixCryptoPathFor(resolve(paths.bots, botId));
+  const stateFor = async (botId) => {
+    let state = stateStores.get(botId);
+    if (!state) {
+      state = await new ResolvedStateStore(statePath(botId)).load();
+      stateStores.set(botId, state);
+    }
+    return state;
+  };
+  const sidecarFor = async (botId) => {
+    let sidecar = sidecarStores.get(botId);
+    if (!sidecar) {
+      sidecar = await new ResolvedSidecarStore(sidecarPath(botId)).load();
+      sidecarStores.set(botId, sidecar);
+    }
+    return sidecar;
+  };
+  const cryptoFor = async (botId) => {
+    let crypto = cryptoStores.get(botId);
+    if (!crypto) {
+      crypto = await new ResolvedCryptoStore(cryptoPath(botId)).load();
+      cryptoStores.set(botId, crypto);
+    }
+    return crypto;
+  };
+  const commandExecutor = createHarnessCommandExecutor(ctx, internals.commandExecutor);
+  const inboundTtl = internals.inboundTtl ?? getInboundTtlRuntime(ctx, config);
+  const inboundTtlService = inboundTtl?.service ?? inboundTtl;
+  registerInboundTtlWorkspaces(ctx, inboundTtlService, {
+    workspaces,
+    configStore: observedConfigStore,
+    defaultWorkspace,
+  });
+  const { controlExecutor, sessionMaintenanceExecutor, fileIngressExecutor } = createHarnessSessionExecutors(ctx, {
+    controlExecutor: internals.controlExecutor,
+    sessionMaintenanceExecutor: internals.sessionMaintenanceExecutor,
+    fileIngressExecutor: internals.fileIngressExecutor,
+    inboundTtlService,
+  });
+  const harness = new ResolvedHarness({
+    ...connection,
+    workspace: defaultWorkspace,
+    autostart: false,
+    dshBin: config.dshBin ?? 'dsh',
+    ...(commandExecutor ? { commandExecutor } : {}),
+    ...(controlExecutor ? { controlExecutor } : {}),
+    ...(sessionMaintenanceExecutor ? { sessionMaintenanceExecutor } : {}),
+    ...(fileIngressExecutor ? { fileIngressExecutor } : {}),
+  });
+  const modelCatalog = () => listModelCatalog(harness);
+  const knownCommandNames = new Set(
+    commandsForChannel('matrix').flatMap((entry) => [entry.name, ...entry.aliases.map((alias) => alias.name)]),
+  );
+  const isKnownCommand = (name) => typeof name === 'string' && knownCommandNames.has(name.replace(/^\/+/, ''));
+  const coreController = new ResolvedController({
+    credentials: ctx.credentials,
+    configStore: observedConfigStore,
+    logger,
+    ...(internals.inspectCredentials ? { inspectCredentials: internals.inspectCredentials } : {}),
+    createRuntime: async ({ botId, config: botConfig, accessToken, password, userId }) => {
+      const state = await stateFor(botId);
+      const sidecar = await sidecarFor(botId);
+      await workspaces.ensure(botId, {
+        defaultAgentPreset: config.agentPreset,
+        initialAccessPolicy: initialAccessPolicyFor('matrix', botConfig),
+      });
+      const workspaceScope = createBotWorkspaceScope(harness, {
+        botId, workspaces, state, agentPresetCatalog,
+      });
+      const e2eeMode = String(botConfig?.e2eeMode ?? 'optional').trim().toLowerCase();
+      const cryptoStore = e2eeMode === 'off' ? null : await cryptoFor(botId);
+      return new ResolvedRuntime({
+        config: botConfig,
+        ...(accessToken ? { accessToken } : {}),
+        ...(password ? { password } : {}),
+        ...(userId ? { userId } : {}),
+        harness: workspaceScope.harness,
+        state: workspaceScope.state,
+        sidecar,
+        ...(cryptoStore ? { cryptoStore } : {}),
+        contextEnhancement: { botId, getSettings: () => workspaces.contextEnhancementFor(botId) },
+        accessPolicy: accessPolicyProvider(workspaces, botId, {
+          channel: 'matrix', config: botConfig,
+        }),
+        ...(typeof internals.isKnownCommand === 'function'
+          ? { isKnownCommand: internals.isKnownCommand }
+          : { isKnownCommand }),
+        replyTimeoutMs: config.replyTimeoutMs ?? 600_000,
+        logger: {
+          error: (...args) => logger.error?.(`[${botId}]`, ...args),
+          warn: (...args) => logger.warn?.(`[${botId}]`, ...args),
+          info: (...args) => logger.info?.(`[${botId}]`, ...args),
+          debug: (...args) => logger.debug?.(`[${botId}]`, ...args),
+        },
+      });
+    },
+    deleteState: async ({ botId }) => {
+      const state = stateStores.get(botId);
+      stateStores.delete(botId);
+      const sidecar = sidecarStores.get(botId);
+      sidecarStores.delete(botId);
+      const crypto = cryptoStores.get(botId);
+      cryptoStores.delete(botId);
+      if (crypto && typeof crypto.remove === 'function') {
+        await crypto.remove();
+      } else {
+        try {
+          await unlink(cryptoPath(botId));
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error;
+        }
+      }
+      if (state && typeof state.remove === 'function') {
+        await state.remove();
+      } else {
+        try {
+          await unlink(statePath(botId));
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error;
+        }
+      }
+      if (sidecar && typeof sidecar.remove === 'function') {
+        await sidecar.remove();
+      } else {
+        try {
+          await unlink(sidecarPath(botId));
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error;
+        }
+      }
+    },
+  });
+  const controller = createWorkspaceAwareController(coreController, {
+    workspaces,
+    stateFor,
+    agentPresetCatalog,
+    modelCatalog,
+  });
+  const supervisor = createSupervisor({
+    channel: 'matrix',
+    controller,
+    harness,
+    logger,
+    retryDelaysMs: config.retryDelaysMs,
+    healthyIntervalMs: config.healthyIntervalMs,
+  }).start();
+  return {
+    controller,
+    deliveryAdapter: createDeliveryAdapter({
+      channel: 'matrix', workspaces, coreController, stateFor,
+    }),
+    ready: supervisor.ready,
+    async close() {
+      await supervisor.close();
+      await controller.close();
+      harness.stopManagedProcess();
+    },
+  };
+}

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

@@ -0,0 +1,228 @@
+import { SET_ALIAS_ENDPOINT, validAliasPayload } from '../shared/bot-alias-rpc.mjs';
+import { registerManagementRpc } from '../../../management-rpc.mjs';
+import { SET_CONTEXT_ENHANCEMENT_ENDPOINT, validContextEnhancementPayload } from '../shared/context-enhancement-rpc.mjs';
+import { SET_ACCESS_POLICY_ENDPOINT, validAccessPolicyPayload } from '../shared/access-policy-rpc.mjs';
+import { resolveRpcAuthority } from '../../rpc-authority.mjs';
+import { publicConnectionTestResult } from '../../../../src/channels/shared/connection-test.mjs';
+import {
+  publicWorkspaceError,
+  SET_WORKSPACE_ENDPOINT,
+  validWorkspacePayload,
+} from '../shared/workspace-rpc.mjs';
+import {
+  SET_AGENT_PRESET_ENDPOINT,
+  validAgentPresetPayload,
+} from '../shared/agent-preset-rpc.mjs';
+import { SET_MODEL_ENDPOINT, validModelPayload } from '../shared/model-setting-rpc.mjs';
+import { isMatrixUserId, validateMatrixHomeserver } from '../../../../src/channels/matrix/matrix-api.mjs';
+
+export const MATRIX_RPC_CHANNEL = '/matrix';
+export const MATRIX_ENDPOINTS = Object.freeze({
+  status: 'connection.status',
+  bindCredentials: 'bot.bind-credentials',
+  reconnectBot: 'bot.reconnect',
+  deleteBot: 'bot.delete',
+  setWorkspace: SET_WORKSPACE_ENDPOINT,
+  setModel: SET_MODEL_ENDPOINT,
+  setAgentPreset: SET_AGENT_PRESET_ENDPOINT,
+  setContextEnhancement: SET_CONTEXT_ENHANCEMENT_ENDPOINT,
+  setAccessPolicy: SET_ACCESS_POLICY_ENDPOINT,
+  setAlias: SET_ALIAS_ENDPOINT,
+});
+export const MATRIX_RPC_ENDPOINTS = Object.freeze(Object.values(MATRIX_ENDPOINTS));
+
+const FORBIDDEN_PUBLIC_KEYS = new Set([
+  'token', 'accessToken', 'accessTokenRef', 'tokenRef',
+  'password', 'passwordRef', 'platformId', 'secret', 'secretRef',
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, allowed) {
+  return isRecord(value) && Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function validId(value) {
+  return typeof value === 'string' && /^matrix_[a-f0-9]{24}$/.test(value);
+}
+
+function validHomeserver(value) {
+  return typeof value === 'string' && value.length <= 2_048 && validateMatrixHomeserver(value) !== null;
+}
+
+function validAccessToken(value) {
+  return typeof value === 'string' && value.trim().length >= 8 && value.length <= 4_096;
+}
+
+function validUserId(value) {
+  return typeof value === 'string' && value.length <= 512 && isMatrixUserId(value.trim());
+}
+
+function validPassword(value) {
+  return typeof value === 'string' && value.length >= 1 && value.length <= 1_024;
+}
+
+function payloadFailure(endpoint, payload) {
+  if (!isRecord(payload)) return 'Payload must be an object.';
+  if (endpoint === MATRIX_ENDPOINTS.status) {
+    return exactKeys(payload, []) ? null : 'connection.status does not accept fields.';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.bindCredentials) {
+    const hasToken = payload.accessToken !== undefined;
+    const hasLogin = payload.userId !== undefined && payload.password !== undefined;
+    return exactKeys(payload, ['homeserver', 'accessToken', 'userId', 'password'])
+      && validHomeserver(payload.homeserver)
+      && (hasToken
+        ? (payload.userId === undefined && payload.password === undefined && validAccessToken(payload.accessToken))
+        : (hasLogin && validUserId(payload.userId) && validPassword(payload.password)))
+      ? null : 'bot.bind-credentials requires a homeserver plus an access token or a user id with password.';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.reconnectBot) {
+    return exactKeys(payload, ['botId', 'sendTest']) && validId(payload.botId)
+      && (payload.sendTest === undefined || typeof payload.sendTest === 'boolean')
+      ? null : 'bot.reconnect requires a botId.';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.deleteBot) {
+    return exactKeys(payload, ['botId', 'confirm']) && validId(payload.botId) && payload.confirm === true
+      ? null : 'bot.delete requires a botId and confirm=true.';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.setWorkspace) {
+    return validWorkspacePayload(payload)
+      ? null : '请输入工作区绝对路径。';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.setModel) {
+    return validModelPayload(payload) ? null : '请选择有效模型。';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.setAgentPreset) {
+    return validAgentPresetPayload(payload)
+      ? null : '请选择 Agent Preset。';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.setContextEnhancement) {
+    return validContextEnhancementPayload(payload)
+      ? null : '请提交有效的上下文增强设置。';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.setAccessPolicy) {
+    return validAccessPolicyPayload(payload)
+      ? null : '请提交有效的访问设置。';
+  }
+  if (endpoint === MATRIX_ENDPOINTS.setAlias) {
+    return validAliasPayload(payload)
+      ? null : '请输入有效的别名（最多 80 个字符）。';
+  }
+  return 'Unknown Matrix endpoint.';
+}
+
+function sanitizePublic(value) {
+  if (Array.isArray(value)) return value.map(sanitizePublic);
+  if (!isRecord(value)) return value;
+  const safe = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (!FORBIDDEN_PUBLIC_KEYS.has(key)) safe[key] = sanitizePublic(child);
+  }
+  return safe;
+}
+
+function operationError(error) {
+  const workspaceError = publicWorkspaceError(error);
+  if (workspaceError) return workspaceError;
+  if (error?.code === 'invalid-config') {
+    return { code: 'invalid-config', message: error.message };
+  }
+  if (error?.code === 'auth-failed') {
+    return { code: 'auth-failed', message: error.message };
+  }
+  if (error?.code === 'login-failed' || error?.code === 'network' || error?.code === 'timeout') {
+    return { code: 'homeserver-unreachable', message: error.message };
+  }
+  return { code: 'matrix-operation-failed', message: 'Matrix 操作失败，请稍后重试。' };
+}
+
+export function createMatrixRpcHandler(controller) {
+  for (const method of ['status', 'bindCredentials', 'reconnectBot', 'deleteBot']) {
+    if (typeof controller?.[method] !== 'function') {
+      throw new TypeError(`A complete Matrix controller is required (${method})`);
+    }
+  }
+  return async (endpoint, payload, signal) => {
+    if (signal?.aborted) {
+      return { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } };
+    }
+    if (!MATRIX_RPC_ENDPOINTS.includes(endpoint)) {
+      return { ok: false, error: { code: 'bad-request', message: 'Unknown Matrix endpoint.' } };
+    }
+    const invalid = payloadFailure(endpoint, payload);
+    if (invalid) return { ok: false, error: { code: 'bad-request', message: invalid } };
+    try {
+      let value;
+      if (endpoint === MATRIX_ENDPOINTS.status) value = await controller.status();
+      else if (endpoint === MATRIX_ENDPOINTS.bindCredentials) value = await controller.bindCredentials(payload);
+      else if (endpoint === MATRIX_ENDPOINTS.reconnectBot) {
+        value = await controller.reconnectBot(payload.botId);
+        if (signal?.aborted) {
+          return { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } };
+        }
+        if (payload.sendTest === true) {
+          let testError = null;
+          try {
+            if (value?.bots?.find((bot) => bot?.botId === payload.botId)?.ready !== true) {
+              const unavailable = new Error('Bot is not connected');
+              unavailable.code = 'test-target-unavailable';
+              throw unavailable;
+            }
+            if (typeof controller.sendConnectionTest !== 'function') {
+              const unavailable = new Error('Connection test is unavailable');
+              unavailable.code = 'test-target-unavailable';
+              throw unavailable;
+            }
+            await controller.sendConnectionTest(payload.botId);
+          } catch (error) {
+            testError = error;
+          }
+          value = { ...value, testMessage: publicConnectionTestResult(testError) };
+        }
+      }
+      else if (endpoint === MATRIX_ENDPOINTS.setWorkspace) {
+        if (typeof controller.updateWorkspace !== 'function') throw new Error('Workspace update is unavailable');
+        value = await controller.updateWorkspace(payload.botId, payload.workspace);
+      }
+      else if (endpoint === MATRIX_ENDPOINTS.setModel) {
+        if (typeof controller.updateModel !== 'function') throw new Error('Model update is unavailable');
+        value = await controller.updateModel(payload.botId, payload.model);
+      }
+      else if (endpoint === MATRIX_ENDPOINTS.setContextEnhancement) {
+        if (typeof controller.updateContextEnhancement !== 'function') throw new Error('Context enhancement update is unavailable');
+        value = await controller.updateContextEnhancement(payload.botId, payload.config);
+      }
+      else if (endpoint === MATRIX_ENDPOINTS.setAlias) {
+        if (typeof controller.updateAlias !== 'function') throw new Error('Alias update is unavailable');
+        value = await controller.updateAlias(payload.botId, payload.alias);
+      }
+      else if (endpoint === MATRIX_ENDPOINTS.setAccessPolicy) {
+        if (typeof controller.updateAccessPolicy !== 'function') throw new Error('Access policy update is unavailable');
+        value = await controller.updateAccessPolicy(payload.botId, payload.policy);
+      }
+      else if (endpoint === MATRIX_ENDPOINTS.setAgentPreset) {
+        if (typeof controller.updateAgentPreset !== 'function') throw new Error('Agent preset update is unavailable');
+        value = await controller.updateAgentPreset(payload.botId, payload.agentPreset);
+      }
+      else value = await controller.deleteBot(payload.botId);
+      return signal?.aborted
+        ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
+        : { ok: true, value: sanitizePublic(value) };
+    } catch (error) {
+      return signal?.aborted
+        ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } }
+        : { ok: false, error: operationError(error) };
+    }
+  };
+}
+
+export function installMatrixRpc(ctx, controller, authority) {
+  return registerManagementRpc(ctx,
+    MATRIX_RPC_CHANNEL,
+    createMatrixRpcHandler(controller),
+    { authority: resolveRpcAuthority(authority) },
+  );
+}

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

@@ -91,7 +91,7 @@ export function initialAccessPolicyFor(channel, config = {}) {
       group: allowlistScope(),
     });
   }
-  if (['dingtalk', 'wecom', 'wecom-app', 'slack', 'discord', 'imessage'].includes(key)) {
+  if (['dingtalk', 'wecom', 'wecom-app', 'slack', 'discord', 'imessage', 'matrix'].includes(key)) {
     return createAccessPolicy({ direct: openScope(), group: openScope() });
   }
   throw new TypeError(`Unsupported access-policy channel: ${channel}`);

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

@@ -4,7 +4,7 @@ const CHANNEL_NAMES = {
   weixin: '微信', feishu: '飞书', dingtalk: '钉钉', wecom: '企业微信',
   'wecom-app': '企业微信应用', qq: 'QQ', slack: 'Slack', telegram: 'Telegram',
   discord: 'Discord', whatsapp: 'WhatsApp', imessage: 'iMessage',
-  email: '邮箱', office: 'AI Office',
+  email: '邮箱', matrix: 'Matrix', office: 'AI Office',
 };
 const INVALID_CONFIG_MESSAGES = new Set([
   'dsh-weixin config contains invalid account data',
@@ -15,6 +15,7 @@ const INVALID_CONFIG_MESSAGES = new Set([
   ...['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 Matrix config contains invalid bot data',
   'dsh-im AI Office config is invalid',
   'dsh-im workspace config is invalid',
 ]);

package/plugin-src/host/delivery-adapter.mjs

@@ -17,6 +17,7 @@ const CHANNELS = new Set([
   'whatsapp',
   'imessage',
   'email',
+  'matrix',
 ]);
 
 export function supportsDeliveryChannel(channel) {
@@ -137,6 +138,23 @@ function normalizeRoute(channel, kind, route) {
       }
       return { address: normalized.address.toLowerCase() };
     }
+    case 'matrix': {
+      oneOf(kind, ['room', 'thread', 'dm']);
+      const normalized = routeWithStrings(
+        route,
+        kind === 'room' ? ['roomId'] : kind === 'thread' ? ['roomId', 'threadId'] : ['userId'],
+      );
+      if (kind === 'dm' && !/^@[^:\s]+:[^\s:]+(?::\d{1,5})?$/u.test(normalized.userId)) {
+        throw invalidTarget('route.userId must be a Matrix user id');
+      }
+      if (kind !== 'dm' && !/^[!][^:$\s]+:[^\s:$]+(?::\d{1,5})?$/.test(normalized.roomId)) {
+        throw invalidTarget('route.roomId must be a Matrix room id');
+      }
+      if (kind === 'thread' && !/^\$[^\s]+/.test(normalized.threadId)) {
+        throw invalidTarget('route.threadId must be a Matrix event id');
+      }
+      return normalized;
+    }
     default:
       throw new TypeError(`Unsupported delivery channel: ${channel}`);
   }

package/plugin-src/host/delivery-suggestions.mjs

@@ -9,6 +9,7 @@ const CHANNELS = new Set([
   'telegram',
   'discord',
   'whatsapp',
+  'matrix',
 ]);
 
 function isRecord(value) {
@@ -80,6 +81,15 @@ function whatsappSuggestion(key) {
   return group ? { kind: 'group', route: { jid: group[1] } } : null;
 }
 
+function matrixSuggestion(key) {
+  const dm = /^dm:(@[A-Za-z0-9._=\-\/+]+:[A-Za-z0-9.-]+(?::\d{1,5})?)$/.exec(key);
+  if (dm) return { kind: 'dm', route: { userId: dm[1] } };
+  const room = /^room:([!#][^:$\s]+:[A-Za-z0-9.-]+(?::\d{1,5})?)(?:\$(\$[^\s]+))?$/u.exec(key);
+  if (!room) return null;
+  if (room[2] === undefined) return { kind: 'room', route: { roomId: room[1] } };
+  return { kind: 'thread', route: { roomId: room[1], threadId: room[2] } };
+}
+
 /** Convert one persisted conversation key into a stable proactive-delivery route. */
 export function deliverySuggestionFromConversationKey(channel, key) {
   if (!CHANNELS.has(channel) || typeof key !== 'string') return null;
@@ -113,6 +123,8 @@ export function deliverySuggestionFromConversationKey(channel, key) {
       return discordSuggestion(key);
     case 'whatsapp':
       return whatsappSuggestion(key);
+    case 'matrix':
+      return matrixSuggestion(key);
     default:
       return null;
   }
@@ -133,6 +145,7 @@ export function privateDeliverySuggestionFromConversationKey(channel, key) {
     telegram: 'direct',
     discord: 'direct',
     whatsapp: 'direct',
+    matrix: 'dm',
   }[channel];
   if (!privatePrefix || prefix !== privatePrefix) return null;
   return deliverySuggestionFromConversationKey(channel, key);

package/plugin-src/host/index.mjs

@@ -11,6 +11,7 @@ import { apply as applyWeixin } from './channels/weixin/index.mjs';
 import { apply as applyWhatsapp } from './channels/whatsapp/index.mjs';
 import { apply as applyIMessage } from './channels/imessage/index.mjs';
 import { apply as applyEmail } from './channels/email/index.mjs';
+import { apply as applyMatrix } from './channels/matrix/index.mjs';
 import { installOutboundArtifactTool } from '../../src/channels/shared/semantic/artifact.mjs';
 import { installHostLanguage } from './host-language.mjs';
 import { installHostLanguageRpc } from './host-language-rpc.mjs';
@@ -62,6 +63,7 @@ export function createImHostPlugin(internals = {}) {
   const startWhatsapp = internals.applyWhatsapp ?? applyWhatsapp;
   const startIMessage = internals.applyIMessage ?? applyIMessage;
   const startEmail = internals.applyEmail ?? applyEmail;
+  const startMatrix = internals.applyMatrix ?? applyMatrix;
   const channels = [
     ['feishu', startFeishu],
     ['weixin', startWeixin],
@@ -75,6 +77,7 @@ export function createImHostPlugin(internals = {}) {
     ['whatsapp', startWhatsapp],
     ['imessage', startIMessage],
     ['email', startEmail],
+    ['matrix', startMatrix],
     ['office', startOffice],
   ];
   return Object.freeze({

package/scripts/verify-lan-management.mjs

@@ -161,7 +161,7 @@ try {
     headers: { cookie: lan.cookie },
   }), 200);
   const channels = ['feishu', 'weixin', 'dingtalk', 'wecom', 'wecom-app', 'qq',
-    'slack', 'telegram', 'discord', 'whatsapp', 'imessage', 'office'];
+    'slack', 'telegram', 'discord', 'whatsapp', 'imessage', 'matrix', 'office'];
   for (const channel of channels) {
     expectStatus(`LAN default: ${channel}`, await readyStatus(lan, channel), 200, true);
   }

package/scripts/verify-package.mjs

@@ -45,6 +45,8 @@ const required = [
   'plugin-src/host/channels/telegram/index.mjs',
   'plugin-src/host/channels/discord/index.mjs',
   'plugin-src/host/channels/whatsapp/index.mjs',
+  'plugin-src/host/channels/matrix/index.mjs',
+  'plugin-src/client/channels/matrix/index.js',
   'src/channels/feishu/feishu-runtime.mjs',
   'src/channels/weixin/weixin-runtime.mjs',
   'src/channels/dingtalk/dingtalk-runtime.mjs',
@@ -56,6 +58,8 @@ const required = [
   'src/channels/discord/discord-runtime.mjs',
   'src/channels/whatsapp/whatsapp-runtime.mjs',
   'src/channels/whatsapp/whatsapp-web-session.mjs',
+  'src/channels/matrix/matrix-runtime.mjs',
+  'src/channels/matrix/matrix-api.mjs',
   'src/channels/shared/context-enhancement.mjs',
 ];
 await Promise.all(required.map((path) => access(resolve(root, path))));
@@ -174,7 +178,7 @@ if (!client.includes('container-type: inline-size')
   || !client.includes('@container (max-width: 680px)')) {
   throw new Error('client bundle does not contain the narrow-panel DingTalk QR layout');
 }
-for (const marker of ['/feishu', '/weixin', '/dingtalk', '/wecom', '/qq', '/slack', '/telegram', '/discord', '/whatsapp']) {
+for (const marker of ['/feishu', '/weixin', '/dingtalk', '/wecom', '/qq', '/slack', '/telegram', '/discord', '/whatsapp', '/matrix']) {
   if (!host.includes(marker)) {
     throw new Error(`host bundle does not contain the internal ${marker} RPC provider`);
   }