@openclaw/matrix 2026.1.29 → 2026.2.2

package/src/matrix/send/formatting.ts

@@ -1,5 +1,5 @@
-import { markdownToMatrixHtml } from "../format.js";
 import { getMatrixRuntime } from "../../runtime.js";
+import { markdownToMatrixHtml } from "../format.js";
 import {
   MsgType,
   RelationType,
@@ -13,10 +13,7 @@ import {
 
 const getCore = () => getMatrixRuntime();
 
-export function buildTextContent(
-  body: string,
-  relation?: MatrixRelation,
-): MatrixTextContent {
+export function buildTextContent(body: string, relation?: MatrixRelation): MatrixTextContent {
   const content: MatrixTextContent = relation
     ? {
         msgtype: MsgType.Text,
@@ -33,34 +30,32 @@ export function buildTextContent(
 
 export function applyMatrixFormatting(content: MatrixFormattedContent, body: string): void {
   const formatted = markdownToMatrixHtml(body ?? "");
-  if (!formatted) return;
+  if (!formatted) {
+    return;
+  }
   content.format = "org.matrix.custom.html";
   content.formatted_body = formatted;
 }
 
 export function buildReplyRelation(replyToId?: string): MatrixReplyRelation | undefined {
   const trimmed = replyToId?.trim();
-  if (!trimmed) return undefined;
+  if (!trimmed) {
+    return undefined;
+  }
   return { "m.in_reply_to": { event_id: trimmed } };
 }
 
-export function buildThreadRelation(
-  threadId: string,
-  replyToId?: string,
-): MatrixThreadRelation {
+export function buildThreadRelation(threadId: string, replyToId?: string): MatrixThreadRelation {
   const trimmed = threadId.trim();
   return {
     rel_type: RelationType.Thread,
     event_id: trimmed,
     is_falling_back: true,
-    "m.in_reply_to": { event_id: (replyToId?.trim() || trimmed) },
+    "m.in_reply_to": { event_id: replyToId?.trim() || trimmed },
   };
 }
 
-export function resolveMatrixMsgType(
-  contentType?: string,
-  _fileName?: string,
-): MatrixMediaMsgType {
+export function resolveMatrixMsgType(contentType?: string, _fileName?: string): MatrixMediaMsgType {
   const kind = getCore().media.mediaKindFromMime(contentType ?? "");
   switch (kind) {
     case "image":
@@ -79,7 +74,9 @@ export function resolveMatrixVoiceDecision(opts: {
   contentType?: string;
   fileName?: string;
 }): { useVoice: boolean } {
-  if (!opts.wantsVoice) return { useVoice: false };
+  if (!opts.wantsVoice) {
+    return { useVoice: false };
+  }
   if (
     getCore().media.isVoiceCompatibleAudio({
       contentType: opts.contentType,

package/src/matrix/send/media.ts

@@ -7,8 +7,8 @@ import type {
   VideoFileInfo,
 } from "@vector-im/matrix-bot-sdk";
 import { parseBuffer, type IFileInfo } from "music-metadata";
-
 import { getMatrixRuntime } from "../../runtime.js";
+import { applyMatrixFormatting } from "./formatting.js";
 import {
   type MatrixMediaContent,
   type MatrixMediaInfo,
@@ -16,7 +16,6 @@ import {
   type MatrixRelation,
   type MediaKind,
 } from "./types.js";
-import { applyMatrixFormatting } from "./formatting.js";
 
 const getCore = () => getMatrixRuntime();
 
@@ -54,7 +53,9 @@ export function buildMatrixMediaInfo(params: {
     };
     return timedInfo;
   }
-  if (Object.keys(base).length === 0) return undefined;
+  if (Object.keys(base).length === 0) {
+    return undefined;
+  }
   return base;
 }
 
@@ -113,8 +114,12 @@ export async function prepareImageInfo(params: {
   buffer: Buffer;
   client: MatrixClient;
 }): Promise<DimensionalFileInfo | undefined> {
-  const meta = await getCore().media.getImageMetadata(params.buffer).catch(() => null);
-  if (!meta) return undefined;
+  const meta = await getCore()
+    .media.getImageMetadata(params.buffer)
+    .catch(() => null);
+  if (!meta) {
+    return undefined;
+  }
   const imageInfo: DimensionalFileInfo = { w: meta.width, h: meta.height };
   const maxDim = Math.max(meta.width, meta.height);
   if (maxDim > THUMBNAIL_MAX_SIDE) {
@@ -125,7 +130,9 @@ export async function prepareImageInfo(params: {
         quality: THUMBNAIL_QUALITY,
         withoutEnlargement: true,
       });
-      const thumbMeta = await getCore().media.getImageMetadata(thumbBuffer).catch(() => null);
+      const thumbMeta = await getCore()
+        .media.getImageMetadata(thumbBuffer)
+        .catch(() => null);
       const thumbUri = await params.client.uploadContent(
         thumbBuffer,
         "image/jpeg",
@@ -153,7 +160,9 @@ export async function resolveMediaDurationMs(params: {
   fileName?: string;
   kind: MediaKind;
 }): Promise<number | undefined> {
-  if (params.kind !== "audio" && params.kind !== "video") return undefined;
+  if (params.kind !== "audio" && params.kind !== "video") {
+    return undefined;
+  }
   try {
     const fileInfo: IFileInfo | string | undefined =
       params.contentType || params.fileName
@@ -201,7 +210,7 @@ export async function uploadMediaMaybeEncrypted(
   },
 ): Promise<{ url: string; file?: EncryptedFile }> {
   // Check if room is encrypted and crypto is available
-  const isEncrypted = client.crypto && await client.crypto.isRoomEncrypted(roomId);
+  const isEncrypted = client.crypto && (await client.crypto.isRoomEncrypted(roomId));
 
   if (isEncrypted && client.crypto) {
     // Encrypt the media before uploading

package/src/matrix/send/targets.test.ts

@@ -1,6 +1,5 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { EventType } from "./types.js";
 
 let resolveMatrixRoomId: typeof import("./targets.js").resolveMatrixRoomId;
@@ -26,7 +25,9 @@ describe("resolveMatrixRoomId", () => {
     const roomId = await resolveMatrixRoomId(client, userId);
 
     expect(roomId).toBe("!room:example.org");
+    // oxlint-disable-next-line typescript/unbound-method
     expect(client.getJoinedRooms).not.toHaveBeenCalled();
+    // oxlint-disable-next-line typescript/unbound-method
     expect(client.setAccountData).not.toHaveBeenCalled();
   });
 
@@ -37,10 +38,7 @@ describe("resolveMatrixRoomId", () => {
     const client = {
       getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
       getJoinedRooms: vi.fn().mockResolvedValue([roomId]),
-      getJoinedRoomMembers: vi.fn().mockResolvedValue([
-        "@bot:example.org",
-        userId,
-      ]),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot:example.org", userId]),
       setAccountData,
     } as unknown as MatrixClient;
 
@@ -80,11 +78,9 @@ describe("resolveMatrixRoomId", () => {
     const client = {
       getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
       getJoinedRooms: vi.fn().mockResolvedValue([roomId]),
-      getJoinedRoomMembers: vi.fn().mockResolvedValue([
-        "@bot:example.org",
-        userId,
-        "@extra:example.org",
-      ]),
+      getJoinedRoomMembers: vi
+        .fn()
+        .mockResolvedValue(["@bot:example.org", userId, "@extra:example.org"]),
       setAccountData: vi.fn().mockResolvedValue(undefined),
     } as unknown as MatrixClient;
 

package/src/matrix/send/targets.ts

@@ -1,5 +1,4 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-
 import { EventType, type MatrixDirectAccountData } from "./types.js";
 
 function normalizeTarget(raw: string): string {
@@ -11,7 +10,9 @@ function normalizeTarget(raw: string): string {
 }
 
 export function normalizeThreadId(raw?: string | number | null): string | null {
-  if (raw === undefined || raw === null) return null;
+  if (raw === undefined || raw === null) {
+    return null;
+  }
   const trimmed = String(raw).trim();
   return trimmed ? trimmed : null;
 }
@@ -25,16 +26,15 @@ async function persistDirectRoom(
 ): Promise<void> {
   let directContent: MatrixDirectAccountData | null = null;
   try {
-    directContent = (await client.getAccountData(
-      EventType.Direct,
-    )) as MatrixDirectAccountData | null;
+    directContent = await client.getAccountData(EventType.Direct);
   } catch {
     // Ignore fetch errors and fall back to an empty map.
   }
-  const existing =
-    directContent && !Array.isArray(directContent) ? directContent : {};
+  const existing = directContent && !Array.isArray(directContent) ? directContent : {};
   const current = Array.isArray(existing[userId]) ? existing[userId] : [];
-  if (current[0] === roomId) return;
+  if (current[0] === roomId) {
+    return;
+  }
   const next = [roomId, ...current.filter((id) => id !== roomId)];
   try {
     await client.setAccountData(EventType.Direct, {
@@ -46,28 +46,21 @@ async function persistDirectRoom(
   }
 }
 
-async function resolveDirectRoomId(
-  client: MatrixClient,
-  userId: string,
-): Promise<string> {
+async function resolveDirectRoomId(client: MatrixClient, userId: string): Promise<string> {
   const trimmed = userId.trim();
   if (!trimmed.startsWith("@")) {
-    throw new Error(
-      `Matrix user IDs must be fully qualified (got "${trimmed}")`,
-    );
+    throw new Error(`Matrix user IDs must be fully qualified (got "${trimmed}")`);
   }
 
   const cached = directRoomCache.get(trimmed);
-  if (cached) return cached;
+  if (cached) {
+    return cached;
+  }
 
   // 1) Fast path: use account data (m.direct) for *this* logged-in user (the bot).
   try {
-    const directContent = (await client.getAccountData(
-      EventType.Direct,
-    )) as MatrixDirectAccountData | null;
-    const list = Array.isArray(directContent?.[trimmed])
-      ? directContent[trimmed]
-      : [];
+    const directContent = await client.getAccountData(EventType.Direct);
+    const list = Array.isArray(directContent?.[trimmed]) ? directContent[trimmed] : [];
     if (list.length > 0) {
       directRoomCache.set(trimmed, list[0]);
       return list[0];
@@ -88,7 +81,9 @@ async function resolveDirectRoomId(
       } catch {
         continue;
       }
-      if (!members.includes(trimmed)) continue;
+      if (!members.includes(trimmed)) {
+        continue;
+      }
       // Prefer classic 1:1 rooms, but allow larger rooms if requested.
       if (members.length === 2) {
         directRoomCache.set(trimmed, roomId);
@@ -112,10 +107,7 @@ async function resolveDirectRoomId(
   throw new Error(`No direct room found for ${trimmed} (m.direct missing)`);
 }
 
-export async function resolveMatrixRoomId(
-  client: MatrixClient,
-  raw: string,
-): Promise<string> {
+export async function resolveMatrixRoomId(client: MatrixClient, raw: string): Promise<string> {
   const target = normalizeTarget(raw);
   const lowered = target.toLowerCase();
   if (lowered.startsWith("matrix:")) {

package/src/matrix/send.test.ts

@@ -1,6 +1,5 @@
-import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-
 import type { PluginRuntime } from "openclaw/plugin-sdk";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { setMatrixRuntime } from "../runtime.js";
 
 vi.mock("@vector-im/matrix-bot-sdk", () => ({

package/src/matrix/send.ts

@@ -1,5 +1,4 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-
 import type { PollInput } from "openclaw/plugin-sdk";
 import { getMatrixRuntime } from "../runtime.js";
 import { buildPollStartContent, M_POLL_START } from "./poll-types.js";
@@ -123,7 +122,9 @@ export async function sendMessageMatrix(
       const followupRelation = threadId ? relation : undefined;
       for (const chunk of textChunks) {
         const text = chunk.trim();
-        if (!text) continue;
+        if (!text) {
+          continue;
+        }
         const followup = buildTextContent(text, followupRelation);
         const followupEventId = await sendContent(followup);
         lastMessageId = followupEventId ?? lastMessageId;
@@ -131,7 +132,9 @@ export async function sendMessageMatrix(
     } else {
       for (const chunk of chunks.length ? chunks : [""]) {
         const text = chunk.trim();
-        if (!text) continue;
+        if (!text) {
+          continue;
+        }
         const content = buildTextContent(text, relation);
         const eventId = await sendContent(content);
         lastMessageId = eventId ?? lastMessageId;
@@ -211,7 +214,9 @@ export async function sendReadReceiptMatrix(
   eventId: string,
   client?: MatrixClient,
 ): Promise<void> {
-  if (!eventId?.trim()) return;
+  if (!eventId?.trim()) {
+    return;
+  }
   const { client: resolved, stopOnDone } = await resolveMatrixClient({
     client,
   });

package/src/onboarding.ts

@@ -6,16 +6,17 @@ import {
   type ChannelOnboardingDmPolicy,
   type WizardPrompter,
 } from "openclaw/plugin-sdk";
+import type { CoreConfig, DmPolicy } from "./types.js";
 import { listMatrixDirectoryGroupsLive } from "./directory-live.js";
 import { listMatrixDirectoryPeersLive } from "./directory-live.js";
 import { resolveMatrixAccount } from "./matrix/accounts.js";
 import { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./matrix/deps.js";
-import type { CoreConfig, DmPolicy } from "./types.js";
 
 const channel = "matrix" as const;
 
 function setMatrixDmPolicy(cfg: CoreConfig, policy: DmPolicy) {
-  const allowFrom = policy === "open" ? addWildcardAllowFrom(cfg.channels?.matrix?.dm?.allowFrom) : undefined;
+  const allowFrom =
+    policy === "open" ? addWildcardAllowFrom(cfg.channels?.matrix?.dm?.allowFrom) : undefined;
   return {
     ...cfg,
     channels: {
@@ -248,8 +249,12 @@ export const matrixOnboardingAdapter: ChannelOnboardingAdapter = {
         initialValue: existing.homeserver ?? envHomeserver,
         validate: (value) => {
           const raw = String(value ?? "").trim();
-          if (!raw) return "Required";
-          if (!/^https?:\/\//i.test(raw)) return "Use a full URL (https://...)";
+          if (!raw) {
+            return "Required";
+          }
+          if (!/^https?:\/\//i.test(raw)) {
+            return "Use a full URL (https://...)";
+          }
           return undefined;
         },
       }),
@@ -273,13 +278,13 @@ export const matrixOnboardingAdapter: ChannelOnboardingAdapter = {
 
     if (!accessToken && !password) {
       // Ask auth method FIRST before asking for user ID
-      const authMode = (await prompter.select({
+      const authMode = await prompter.select({
         message: "Matrix auth method",
         options: [
           { value: "token", label: "Access token (user ID fetched automatically)" },
           { value: "password", label: "Password (requires user ID)" },
         ],
-      })) as "token" | "password";
+      });
 
       if (authMode === "token") {
         accessToken = String(
@@ -299,9 +304,15 @@ export const matrixOnboardingAdapter: ChannelOnboardingAdapter = {
             initialValue: existing.userId ?? envUserId,
             validate: (value) => {
               const raw = String(value ?? "").trim();
-              if (!raw) return "Required";
-              if (!raw.startsWith("@")) return "Matrix user IDs should start with @";
-              if (!raw.includes(":")) return "Matrix user IDs should include a server (:server)";
+              if (!raw) {
+                return "Required";
+              }
+              if (!raw.startsWith("@")) {
+                return "Matrix user IDs should start with @";
+              }
+              if (!raw.includes(":")) {
+                return "Matrix user IDs should include a server (:server)";
+              }
               return undefined;
             },
           }),
@@ -369,7 +380,9 @@ export const matrixOnboardingAdapter: ChannelOnboardingAdapter = {
             const unresolved: string[] = [];
             for (const entry of accessConfig.entries) {
               const trimmed = entry.trim();
-              if (!trimmed) continue;
+              if (!trimmed) {
+                continue;
+              }
               const cleaned = trimmed.replace(/^(room|channel):/i, "").trim();
               if (cleaned.startsWith("!") && cleaned.includes(":")) {
                 resolvedIds.push(cleaned);
@@ -390,10 +403,7 @@ export const matrixOnboardingAdapter: ChannelOnboardingAdapter = {
                 unresolved.push(entry);
               }
             }
-            roomKeys = [
-              ...resolvedIds,
-              ...unresolved.map((entry) => entry.trim()).filter(Boolean),
-            ];
+            roomKeys = [...resolvedIds, ...unresolved.map((entry) => entry.trim()).filter(Boolean)];
             if (resolvedIds.length > 0 || unresolved.length > 0) {
               await prompter.note(
                 [

package/src/outbound.ts

@@ -1,7 +1,6 @@
 import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
-
-import { getMatrixRuntime } from "./runtime.js";
 import { sendMessageMatrix, sendPollMatrix } from "./matrix/send.js";
+import { getMatrixRuntime } from "./runtime.js";
 
 export const matrixOutbound: ChannelOutboundAdapter = {
   deliveryMode: "direct",

package/src/resolve-targets.test.ts

@@ -0,0 +1,48 @@
+import type { ChannelDirectoryEntry } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { listMatrixDirectoryPeersLive } from "./directory-live.js";
+import { resolveMatrixTargets } from "./resolve-targets.js";
+
+vi.mock("./directory-live.js", () => ({
+  listMatrixDirectoryPeersLive: vi.fn(),
+  listMatrixDirectoryGroupsLive: vi.fn(),
+}));
+
+describe("resolveMatrixTargets (users)", () => {
+  beforeEach(() => {
+    vi.mocked(listMatrixDirectoryPeersLive).mockReset();
+  });
+
+  it("resolves exact unique display name matches", async () => {
+    const matches: ChannelDirectoryEntry[] = [
+      { kind: "user", id: "@alice:example.org", name: "Alice" },
+    ];
+    vi.mocked(listMatrixDirectoryPeersLive).mockResolvedValue(matches);
+
+    const [result] = await resolveMatrixTargets({
+      cfg: {},
+      inputs: ["Alice"],
+      kind: "user",
+    });
+
+    expect(result?.resolved).toBe(true);
+    expect(result?.id).toBe("@alice:example.org");
+  });
+
+  it("does not resolve ambiguous or non-exact matches", async () => {
+    const matches: ChannelDirectoryEntry[] = [
+      { kind: "user", id: "@alice:example.org", name: "Alice" },
+      { kind: "user", id: "@alice:evil.example", name: "Alice" },
+    ];
+    vi.mocked(listMatrixDirectoryPeersLive).mockResolvedValue(matches);
+
+    const [result] = await resolveMatrixTargets({
+      cfg: {},
+      inputs: ["Alice"],
+      kind: "user",
+    });
+
+    expect(result?.resolved).toBe(false);
+    expect(result?.note).toMatch(/use full Matrix ID/i);
+  });
+});

package/src/resolve-targets.ts

@@ -4,17 +4,15 @@ import type {
   ChannelResolveResult,
   RuntimeEnv,
 } from "openclaw/plugin-sdk";
-
-import {
-  listMatrixDirectoryGroupsLive,
-  listMatrixDirectoryPeersLive,
-} from "./directory-live.js";
+import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
 
 function pickBestGroupMatch(
   matches: ChannelDirectoryEntry[],
   query: string,
 ): ChannelDirectoryEntry | undefined {
-  if (matches.length === 0) return undefined;
+  if (matches.length === 0) {
+    return undefined;
+  }
   const normalized = query.trim().toLowerCase();
   if (normalized) {
     const exact = matches.find((match) => {
@@ -23,11 +21,59 @@ function pickBestGroupMatch(
       const id = match.id.trim().toLowerCase();
       return name === normalized || handle === normalized || id === normalized;
     });
-    if (exact) return exact;
+    if (exact) {
+      return exact;
+    }
   }
   return matches[0];
 }
 
+function pickBestUserMatch(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): ChannelDirectoryEntry | undefined {
+  if (matches.length === 0) {
+    return undefined;
+  }
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return undefined;
+  }
+  const exact = matches.filter((match) => {
+    const id = match.id.trim().toLowerCase();
+    const name = match.name?.trim().toLowerCase();
+    const handle = match.handle?.trim().toLowerCase();
+    return normalized === id || normalized === name || normalized === handle;
+  });
+  if (exact.length === 1) {
+    return exact[0];
+  }
+  return undefined;
+}
+
+function describeUserMatchFailure(matches: ChannelDirectoryEntry[], query: string): string {
+  if (matches.length === 0) {
+    return "no matches";
+  }
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return "empty input";
+  }
+  const exact = matches.filter((match) => {
+    const id = match.id.trim().toLowerCase();
+    const name = match.name?.trim().toLowerCase();
+    const handle = match.handle?.trim().toLowerCase();
+    return normalized === id || normalized === name || normalized === handle;
+  });
+  if (exact.length === 0) {
+    return "no exact match; use full Matrix ID";
+  }
+  if (exact.length > 1) {
+    return "multiple exact matches; use full Matrix ID";
+  }
+  return "no exact match; use full Matrix ID";
+}
+
 export async function resolveMatrixTargets(params: {
   cfg: unknown;
   inputs: string[];
@@ -52,13 +98,13 @@ export async function resolveMatrixTargets(params: {
           query: trimmed,
           limit: 5,
         });
-        const best = matches[0];
+        const best = pickBestUserMatch(matches, trimmed);
         results.push({
           input,
           resolved: Boolean(best?.id),
           id: best?.id,
           name: best?.name,
-          note: matches.length > 1 ? "multiple matches; chose first" : undefined,
+          note: best ? undefined : describeUserMatchFailure(matches, trimmed),
         });
       } catch (err) {
         params.runtime?.error?.(`matrix resolve failed: ${String(err)}`);

package/src/tool-actions.ts

@@ -1,5 +1,11 @@
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
-
+import {
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+} from "openclaw/plugin-sdk";
 import type { CoreConfig } from "./types.js";
 import {
   deleteMatrixMessage,
@@ -15,13 +21,6 @@ import {
   unpinMatrixMessage,
 } from "./matrix/actions.js";
 import { reactMatrixMessage } from "./matrix/send.js";
-import {
-  createActionGate,
-  jsonResult,
-  readNumberParam,
-  readReactionParams,
-  readStringParam,
-} from "openclaw/plugin-sdk";
 
 const messageActions = new Set(["sendMessage", "editMessage", "deleteMessage", "readMessages"]);
 const reactionActions = new Set(["react", "reactions"]);
@@ -29,8 +28,12 @@ const pinActions = new Set(["pinMessage", "unpinMessage", "listPins"]);
 
 function readRoomId(params: Record<string, unknown>, required = true): string {
   const direct = readStringParam(params, "roomId") ?? readStringParam(params, "channelId");
-  if (direct) return direct;
-  if (!required) return readStringParam(params, "to") ?? "";
+  if (direct) {
+    return direct;
+  }
+  if (!required) {
+    return readStringParam(params, "to") ?? "";
+  }
   return readStringParam(params, "to", { required: true });
 }
 
@@ -76,7 +79,8 @@ export async function handleMatrixAction(
           allowEmpty: true,
         });
         const mediaUrl = readStringParam(params, "mediaUrl");
-        const replyToId = readStringParam(params, "replyToId") ?? readStringParam(params, "replyTo");
+        const replyToId =
+          readStringParam(params, "replyToId") ?? readStringParam(params, "replyTo");
         const threadId = readStringParam(params, "threadId");
         const result = await sendMatrixMessage(to, content, {
           mediaUrl: mediaUrl ?? undefined,

package/src/types.ts

@@ -7,7 +7,7 @@ export type MatrixDmConfig = {
   enabled?: boolean;
   /** Direct message access policy (default: pairing). */
   policy?: DmPolicy;
-  /** Allowlist for DM senders (matrix user IDs, localparts, or "*"). */
+  /** Allowlist for DM senders (matrix user IDs or "*"). */
   allowFrom?: Array<string | number>;
 };
 
@@ -22,7 +22,7 @@ export type MatrixRoomConfig = {
   tools?: { allow?: string[]; deny?: string[] };
   /** If true, reply without mention requirements. */
   autoReply?: boolean;
-  /** Optional allowlist for room senders (user IDs or localparts). */
+  /** Optional allowlist for room senders (matrix user IDs). */
   users?: Array<string | number>;
   /** Optional skill filter for this room. */
   skills?: string[];
@@ -61,7 +61,7 @@ export type MatrixConfig = {
   allowlistOnly?: boolean;
   /** Group message policy (default: allowlist). */
   groupPolicy?: GroupPolicy;
-  /** Allowlist for group senders (user IDs or localparts). */
+  /** Allowlist for group senders (matrix user IDs). */
   groupAllowFrom?: Array<string | number>;
   /** Control reply threading when reply tags are present (off|first|all). */
   replyToMode?: ReplyToMode;
@@ -79,9 +79,9 @@ export type MatrixConfig = {
   autoJoinAllowlist?: Array<string | number>;
   /** Direct message policy + allowlist overrides. */
   dm?: MatrixDmConfig;
-  /** Room config allowlist keyed by room ID, alias, or name. */
+  /** Room config allowlist keyed by room ID or alias (names resolved to IDs when possible). */
   groups?: Record<string, MatrixRoomConfig>;
-  /** Room config allowlist keyed by room ID, alias, or name. Legacy; use groups. */
+  /** Room config allowlist keyed by room ID or alias. Legacy; use groups. */
   rooms?: Record<string, MatrixRoomConfig>;
   /** Per-action tool gating (default: true for all). */
   actions?: MatrixActionConfig;