From d1d36da700779bd72daa45831595996fe7d7f546 Mon Sep 17 00:00:00 2001
From: Gustavo Madeira Santana <gumadeiras@gmail.com>
Date: Wed, 18 Mar 2026 04:03:18 +0000
Subject: [PATCH] Matrix: move outbound session routing behind plugin boundary

---
 extensions/matrix/runtime-api.ts         | 78 ++++++++++++++++++++++--
 extensions/matrix/src/channel.ts         |  2 +
 extensions/matrix/src/matrix/accounts.ts |  2 +-
 extensions/matrix/src/session-route.ts   | 29 +++++++++
 4 files changed, 106 insertions(+), 5 deletions(-)
 create mode 100644 extensions/matrix/src/session-route.ts

diff --git a/extensions/matrix/runtime-api.ts b/extensions/matrix/runtime-api.ts
index 3db7923b18f..449f580d8bd 100644
--- a/extensions/matrix/runtime-api.ts
+++ b/extensions/matrix/runtime-api.ts
@@ -1,4 +1,74 @@
-import { createAccountListHelpers as createAccountListHelpersFromSdk } from "openclaw/plugin-sdk/matrix";
-
-export * from "openclaw/plugin-sdk/matrix";
-export const createAccountListHelpers = createAccountListHelpersFromSdk;
+export {
+  GROUP_POLICY_BLOCKED_LABEL,
+  MarkdownConfigSchema,
+  PAIRING_APPROVED_MESSAGE,
+  ToolPolicySchema,
+  buildChannelConfigSchema,
+  buildChannelKeyCandidates,
+  buildProbeChannelStatusSummary,
+  buildSecretInputSchema,
+  collectStatusIssuesFromLastError,
+  compileAllowlist,
+  createActionGate,
+  createReplyPrefixOptions,
+  createScopedPairingAccess,
+  createTypingCallbacks,
+  dispatchReplyFromConfigWithSettledDispatcher,
+  evaluateGroupRouteAccessForPolicy,
+  fetchWithSsrFGuard,
+  formatAllowlistMatchMeta,
+  formatLocationText,
+  hasConfiguredSecretInput,
+  issuePairingChallenge,
+  jsonResult,
+  logInboundDrop,
+  logTypingFailure,
+  mergeAllowlist,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+  normalizeStringEntries,
+  readNumberParam,
+  readReactionParams,
+  readStoreAllowFromForDmPolicy,
+  readStringParam,
+  resolveAllowlistProviderRuntimeGroupPolicy,
+  resolveChannelEntryMatch,
+  resolveCompiledAllowlistMatch,
+  resolveControlCommandGate,
+  resolveDefaultGroupPolicy,
+  resolveDmGroupAccessWithLists,
+  resolveInboundSessionEnvelopeContext,
+  resolveRuntimeEnv,
+  resolveSenderScopedGroupPolicy,
+  runPluginCommandWithTimeout,
+  summarizeMapping,
+  toLocationContext,
+  warnMissingProviderGroupPolicyFallbackOnce,
+  DEFAULT_ACCOUNT_ID,
+} from "openclaw/plugin-sdk/matrix";
+export { createAccountListHelpers } from "openclaw/plugin-sdk/account-helpers";
+export type {
+  AllowlistMatch,
+  BaseProbeResult,
+  ChannelDirectoryEntry,
+  ChannelGroupContext,
+  ChannelMessageActionAdapter,
+  ChannelMessageActionContext,
+  ChannelMessageActionName,
+  ChannelOutboundAdapter,
+  ChannelPlugin,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  ChannelToolSend,
+  DmPolicy,
+  GroupPolicy,
+  GroupToolPolicyConfig,
+  MarkdownTableMode,
+  NormalizedLocation,
+  PluginRuntime,
+  PollInput,
+  ReplyPayload,
+  RuntimeEnv,
+  RuntimeLogger,
+  SecretInput,
+} from "openclaw/plugin-sdk/matrix";
diff --git a/extensions/matrix/src/channel.ts b/extensions/matrix/src/channel.ts
index e31d4ae2488..7a3f485d21d 100644
--- a/extensions/matrix/src/channel.ts
+++ b/extensions/matrix/src/channel.ts
@@ -32,6 +32,7 @@ import {
 } from "./matrix/accounts.js";
 import { normalizeMatrixAllowList, normalizeMatrixUserId } from "./matrix/monitor/allowlist.js";
 import { getMatrixRuntime } from "./runtime.js";
+import { resolveMatrixOutboundSessionRoute } from "./session-route.js";
 import { matrixSetupAdapter } from "./setup-core.js";
 import { matrixSetupWizard } from "./setup-surface.js";
 import type { CoreConfig } from "./types.js";
@@ -172,6 +173,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
   },
   messaging: {
     normalizeTarget: normalizeMatrixMessagingTarget,
+    resolveOutboundSessionRoute: (params) => resolveMatrixOutboundSessionRoute(params),
     targetResolver: {
       looksLikeId: (raw) => {
         const trimmed = raw.trim();
diff --git a/extensions/matrix/src/matrix/accounts.ts b/extensions/matrix/src/matrix/accounts.ts
index 52fba376200..cf221c70d5a 100644
--- a/extensions/matrix/src/matrix/accounts.ts
+++ b/extensions/matrix/src/matrix/accounts.ts
@@ -1,5 +1,5 @@
+import { createAccountListHelpers } from "openclaw/plugin-sdk/account-helpers";
 import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { createAccountListHelpers } from "openclaw/plugin-sdk/matrix";
 import { hasConfiguredSecretInput } from "../secret-input.js";
 import type { CoreConfig, MatrixConfig } from "../types.js";
 import { resolveMatrixConfigForAccount } from "./client.js";
diff --git a/extensions/matrix/src/session-route.ts b/extensions/matrix/src/session-route.ts
new file mode 100644
index 00000000000..2272c81e693
--- /dev/null
+++ b/extensions/matrix/src/session-route.ts
@@ -0,0 +1,29 @@
+import {
+  buildChannelOutboundSessionRoute,
+  stripChannelTargetPrefix,
+  stripTargetKindPrefix,
+  type ChannelOutboundSessionRouteParams,
+} from "openclaw/plugin-sdk/core";
+
+export function resolveMatrixOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
+  const stripped = stripChannelTargetPrefix(params.target, "matrix");
+  const isUser =
+    params.resolvedTarget?.kind === "user" || stripped.startsWith("@") || /^user:/i.test(stripped);
+  const rawId = stripTargetKindPrefix(stripped);
+  if (!rawId) {
+    return null;
+  }
+  return buildChannelOutboundSessionRoute({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "matrix",
+    accountId: params.accountId,
+    peer: {
+      kind: isUser ? "direct" : "channel",
+      id: rawId,
+    },
+    chatType: isUser ? "direct" : "channel",
+    from: isUser ? `matrix:${rawId}` : `matrix:channel:${rawId}`,
+    to: `room:${rawId}`,
+  });
+}