@gakr-gakr/matrix 0.1.0

package/src/matrix/monitor/replies.ts

@@ -0,0 +1,136 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import { getMatrixRuntime } from "../../runtime.js";
+import type { MatrixClient } from "../sdk.js";
+import { chunkMatrixText, sendMessageMatrix } from "../send.js";
+import type { MarkdownTableMode, AutoBotConfig, ReplyPayload, RuntimeEnv } from "./runtime-api.js";
+
+const THINKING_TAG_RE = /<\s*\/?\s*(?:think(?:ing)?|thought|antthinking)\b[^<>]*>/gi;
+const THINKING_BLOCK_RE =
+  /<\s*(?:think(?:ing)?|thought|antthinking)\b[^<>]*>[\s\S]*?<\s*\/\s*(?:think(?:ing)?|thought|antthinking)\s*>/gi;
+
+function shouldSuppressReasoningReplyText(text?: string): boolean {
+  if (typeof text !== "string") {
+    return false;
+  }
+  const trimmedStart = text.trimStart();
+  if (!trimmedStart) {
+    return false;
+  }
+  if (normalizeLowercaseStringOrEmpty(trimmedStart).startsWith("reasoning:")) {
+    return true;
+  }
+  THINKING_TAG_RE.lastIndex = 0;
+  if (!THINKING_TAG_RE.test(text)) {
+    return false;
+  }
+  THINKING_BLOCK_RE.lastIndex = 0;
+  const withoutThinkingBlocks = text.replace(THINKING_BLOCK_RE, "");
+  THINKING_TAG_RE.lastIndex = 0;
+  return !withoutThinkingBlocks.replace(THINKING_TAG_RE, "").trim();
+}
+
+export async function deliverMatrixReplies(params: {
+  cfg: AutoBotConfig;
+  replies: ReplyPayload[];
+  roomId: string;
+  client: MatrixClient;
+  runtime: RuntimeEnv;
+  textLimit: number;
+  replyToMode: "off" | "first" | "all" | "batched";
+  threadId?: string;
+  accountId?: string;
+  mediaLocalRoots?: readonly string[];
+  tableMode?: MarkdownTableMode;
+}): Promise<boolean> {
+  const core = getMatrixRuntime();
+  const tableMode =
+    params.tableMode ??
+    core.channel.text.resolveMarkdownTableMode({
+      cfg: params.cfg,
+      channel: "matrix",
+      accountId: params.accountId,
+    });
+  const logVerbose = (message: string) => {
+    if (core.logging.shouldLogVerbose()) {
+      params.runtime.log?.(message);
+    }
+  };
+  let hasReplied = false;
+  let deliveredAny = false;
+  for (const reply of params.replies) {
+    if (reply.isReasoning === true || shouldSuppressReasoningReplyText(reply.text)) {
+      logVerbose("matrix reply suppressed as reasoning-only");
+      continue;
+    }
+    const hasMedia = Boolean(reply?.mediaUrl) || (reply?.mediaUrls?.length ?? 0) > 0;
+    if (!reply?.text && !hasMedia) {
+      if (reply?.audioAsVoice) {
+        logVerbose("matrix reply has audioAsVoice without media/text; skipping");
+        continue;
+      }
+      params.runtime.error?.("matrix reply missing text/media");
+      continue;
+    }
+    const replyToIdRaw = reply.replyToId?.trim();
+    const replyToId = params.threadId || params.replyToMode === "off" ? undefined : replyToIdRaw;
+    const rawText = reply.text ?? "";
+    const mediaList = reply.mediaUrls?.length
+      ? reply.mediaUrls
+      : reply.mediaUrl
+        ? [reply.mediaUrl]
+        : [];
+
+    const shouldIncludeReply = (id?: string) =>
+      Boolean(id) && (params.replyToMode === "all" || !hasReplied);
+    const replyToIdForReply = shouldIncludeReply(replyToId) ? replyToId : undefined;
+
+    if (mediaList.length === 0) {
+      let sentTextChunk = false;
+      const { chunks } = chunkMatrixText(rawText, {
+        cfg: params.cfg,
+        accountId: params.accountId,
+        tableMode,
+      });
+      for (const chunk of chunks) {
+        const trimmed = chunk.trim();
+        if (!trimmed) {
+          continue;
+        }
+        await sendMessageMatrix(params.roomId, trimmed, {
+          client: params.client,
+          cfg: params.cfg,
+          replyToId: replyToIdForReply,
+          threadId: params.threadId,
+          accountId: params.accountId,
+        });
+        deliveredAny = true;
+        sentTextChunk = true;
+      }
+      if (replyToIdForReply && !hasReplied && sentTextChunk) {
+        hasReplied = true;
+      }
+      continue;
+    }
+
+    let first = true;
+    for (const mediaUrl of mediaList) {
+      const caption = first ? rawText : "";
+      await sendMessageMatrix(params.roomId, caption, {
+        client: params.client,
+        cfg: params.cfg,
+        mediaUrl,
+        mediaLocalRoots: params.mediaLocalRoots,
+        replyToId: replyToIdForReply,
+        threadId: params.threadId,
+        audioAsVoice: reply.audioAsVoice,
+        accountId: params.accountId,
+      });
+      deliveredAny = true;
+      first = false;
+    }
+    if (replyToIdForReply && !hasReplied) {
+      hasReplied = true;
+    }
+  }
+  return deliveredAny;
+}

package/src/matrix/monitor/reply-context.ts

@@ -0,0 +1,92 @@
+import type { MatrixClient } from "../sdk.js";
+import { summarizeMatrixMessageContextEvent, trimMatrixMaybeString } from "./context-summary.js";
+import type { MatrixRawEvent } from "./types.js";
+
+const MAX_CACHED_REPLY_CONTEXTS = 256;
+const MAX_REPLY_BODY_LENGTH = 500;
+
+type MatrixReplyContext = {
+  replyToBody?: string;
+  replyToSender?: string;
+  replyToSenderId?: string;
+};
+
+function truncateReplyBody(value: string): string {
+  if (value.length <= MAX_REPLY_BODY_LENGTH) {
+    return value;
+  }
+  return `${value.slice(0, MAX_REPLY_BODY_LENGTH - 3)}...`;
+}
+
+export function summarizeMatrixReplyEvent(event: MatrixRawEvent): string | undefined {
+  const body = summarizeMatrixMessageContextEvent(event);
+  return body ? truncateReplyBody(body) : undefined;
+}
+
+/**
+ * Creates a cached resolver that fetches the body and sender of a replied-to
+ * Matrix event. This allows the agent to see the content of the message being
+ * replied to, not just its event ID.
+ */
+export function createMatrixReplyContextResolver(params: {
+  client: MatrixClient;
+  getMemberDisplayName: (roomId: string, userId: string) => Promise<string>;
+  logVerboseMessage: (message: string) => void;
+}) {
+  const cache = new Map<string, MatrixReplyContext>();
+
+  const remember = (key: string, value: MatrixReplyContext): MatrixReplyContext => {
+    cache.set(key, value);
+    if (cache.size > MAX_CACHED_REPLY_CONTEXTS) {
+      const oldest = cache.keys().next().value;
+      if (typeof oldest === "string") {
+        cache.delete(oldest);
+      }
+    }
+    return value;
+  };
+
+  return async (input: { roomId: string; eventId: string }): Promise<MatrixReplyContext> => {
+    const cacheKey = `${input.roomId}:${input.eventId}`;
+    const cached = cache.get(cacheKey);
+    if (cached) {
+      // Move to end for LRU semantics so frequently accessed entries survive eviction.
+      cache.delete(cacheKey);
+      cache.set(cacheKey, cached);
+      return cached;
+    }
+
+    const event = await params.client.getEvent(input.roomId, input.eventId).catch((err) => {
+      params.logVerboseMessage(
+        `matrix: failed resolving reply context room=${input.roomId} id=${input.eventId}: ${String(err)}`,
+      );
+      return null;
+    });
+    if (!event) {
+      // Do not cache failures so transient errors can be retried on the next
+      // message that references the same event.
+      return {};
+    }
+
+    const rawEvent = event as MatrixRawEvent;
+    if (rawEvent.unsigned?.redacted_because) {
+      return remember(cacheKey, {});
+    }
+
+    const replyToBody = summarizeMatrixReplyEvent(rawEvent);
+    if (!replyToBody) {
+      return remember(cacheKey, {});
+    }
+
+    const senderId = trimMatrixMaybeString(rawEvent.sender);
+    const senderName =
+      senderId &&
+      (await params.getMemberDisplayName(input.roomId, senderId).catch(() => undefined));
+
+    return remember(cacheKey, {
+      replyToBody,
+      replyToSender: senderName ?? senderId,
+      replyToSenderId: senderId,
+    });
+  };
+}

package/src/matrix/monitor/room-history.ts

@@ -0,0 +1,301 @@
+/**
+ * Per-room group chat history tracking for Matrix.
+ *
+ * Maintains a shared per-room message queue and per-(agentId, roomId) watermarks so
+ * each agent independently tracks which messages it has already consumed. This design
+ * lets multiple agents in the same room see independent history windows:
+ *
+ * - dev replies to @dev msgB (watermark advances to B) → room queue still has [A, B]
+ * - spark replies to @spark msgC → spark watermark starts at 0 and sees [A, B, C]
+ *
+ * Race-condition safety: the watermark only advances to the snapshot index taken at
+ * dispatch time, NOT to the queue's end at reply time.  Messages that land in the queue
+ * while the agent is processing stay visible to the next trigger for that agent.
+ */
+
+import type { HistoryEntry } from "autobot/plugin-sdk/reply-history";
+
+/** Maximum entries retained per room (hard cap to bound memory). */
+const DEFAULT_MAX_QUEUE_SIZE = 200;
+/** Maximum number of rooms to retain queues for (FIFO eviction beyond this). */
+const DEFAULT_MAX_ROOM_QUEUES = 1000;
+/** Maximum number of (agentId, roomId) watermark entries to retain. */
+const MAX_WATERMARK_ENTRIES = 5000;
+/** Maximum prepared trigger snapshots retained per room for retry reuse. */
+const MAX_PREPARED_TRIGGER_ENTRIES = 500;
+
+export type { HistoryEntry };
+
+type HistorySnapshotToken = {
+  snapshotIdx: number;
+  queueGeneration: number;
+};
+
+type PreparedTriggerResult = {
+  history: HistoryEntry[];
+} & HistorySnapshotToken;
+
+type RoomHistoryTracker = {
+  /**
+   * Record a non-trigger message for future context.
+   * Call this when a room message arrives but does not mention the bot.
+   */
+  recordPending: (roomId: string, entry: HistoryEntry) => void;
+
+  /**
+   * Capture pending history and append the trigger as one idempotent operation.
+   * Retries of the same Matrix event reuse the original prepared history window.
+   */
+  prepareTrigger: (
+    agentId: string,
+    roomId: string,
+    limit: number,
+    entry: HistoryEntry,
+  ) => PreparedTriggerResult;
+
+  /**
+   * Advance the agent's watermark to the snapshot index returned by prepareTrigger
+   * (or the lower-level recordTrigger helper used in tests).
+   * Only messages appended after that snapshot remain visible on the next trigger.
+   */
+  consumeHistory: (
+    agentId: string,
+    roomId: string,
+    snapshot: HistorySnapshotToken,
+    messageId?: string,
+  ) => void;
+};
+
+type RoomHistoryTrackerTestApi = RoomHistoryTracker & {
+  /**
+   * Test-only helper for inspecting pending room history directly.
+   */
+  getPendingHistory: (agentId: string, roomId: string, limit: number) => HistoryEntry[];
+
+  /**
+   * Test-only helper for manually appending a trigger entry and snapshot index.
+   */
+  recordTrigger: (roomId: string, entry: HistoryEntry) => HistorySnapshotToken;
+};
+
+type RoomQueue = {
+  entries: HistoryEntry[];
+  /** Absolute index of entries[0] — increases as old entries are trimmed. */
+  baseIndex: number;
+  generation: number;
+  preparedTriggers: Map<string, PreparedTriggerResult>;
+};
+
+function createRoomHistoryTrackerInternal(
+  maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+  maxRoomQueues = DEFAULT_MAX_ROOM_QUEUES,
+  maxWatermarkEntries = MAX_WATERMARK_ENTRIES,
+  maxPreparedTriggerEntries = MAX_PREPARED_TRIGGER_ENTRIES,
+): RoomHistoryTrackerTestApi {
+  const roomQueues = new Map<string, RoomQueue>();
+  /** Maps `${agentId}:${roomId}` → absolute consumed-up-to index */
+  const agentWatermarks = new Map<string, number>();
+  let nextQueueGeneration = 1;
+
+  function clearRoomWatermarks(roomId: string): void {
+    const roomSuffix = `:${roomId}`;
+    for (const key of agentWatermarks.keys()) {
+      if (key.endsWith(roomSuffix)) {
+        agentWatermarks.delete(key);
+      }
+    }
+  }
+
+  function getOrCreateQueue(roomId: string): RoomQueue {
+    let queue = roomQueues.get(roomId);
+    if (!queue) {
+      queue = {
+        entries: [],
+        baseIndex: 0,
+        generation: nextQueueGeneration++,
+        preparedTriggers: new Map(),
+      };
+      roomQueues.set(roomId, queue);
+      // FIFO eviction to prevent unbounded growth across many rooms
+      if (roomQueues.size > maxRoomQueues) {
+        const oldest = roomQueues.keys().next().value;
+        if (oldest !== undefined) {
+          roomQueues.delete(oldest);
+          clearRoomWatermarks(oldest);
+        }
+      }
+    }
+    return queue;
+  }
+
+  function appendToQueue(queue: RoomQueue, entry: HistoryEntry): HistorySnapshotToken {
+    queue.entries.push(entry);
+    if (queue.entries.length > maxQueueSize) {
+      const overflow = queue.entries.length - maxQueueSize;
+      queue.entries.splice(0, overflow);
+      queue.baseIndex += overflow;
+    }
+    return {
+      snapshotIdx: queue.baseIndex + queue.entries.length,
+      queueGeneration: queue.generation,
+    };
+  }
+
+  function wmKey(agentId: string, roomId: string): string {
+    return `${agentId}:${roomId}`;
+  }
+
+  function preparedTriggerKey(agentId: string, messageId?: string): string | null {
+    if (!messageId?.trim()) {
+      return null;
+    }
+    return `${agentId}:${messageId.trim()}`;
+  }
+
+  function rememberWatermark(key: string, snapshotIdx: number): void {
+    const nextSnapshotIdx = Math.max(agentWatermarks.get(key) ?? 0, snapshotIdx);
+    if (agentWatermarks.has(key)) {
+      // Refresh insertion order so capped-map eviction removes the stalest pair, not an active one.
+      agentWatermarks.delete(key);
+    }
+    agentWatermarks.set(key, nextSnapshotIdx);
+    if (agentWatermarks.size > maxWatermarkEntries) {
+      const oldest = agentWatermarks.keys().next().value;
+      if (oldest !== undefined) {
+        agentWatermarks.delete(oldest);
+      }
+    }
+  }
+
+  function rememberPreparedTrigger(
+    queue: RoomQueue,
+    retryKey: string,
+    prepared: PreparedTriggerResult,
+  ): PreparedTriggerResult {
+    if (queue.preparedTriggers.has(retryKey)) {
+      // Refresh insertion order so capped eviction keeps actively retried events hot.
+      queue.preparedTriggers.delete(retryKey);
+    }
+    queue.preparedTriggers.set(retryKey, prepared);
+    if (queue.preparedTriggers.size > maxPreparedTriggerEntries) {
+      const oldest = queue.preparedTriggers.keys().next().value;
+      if (oldest !== undefined) {
+        queue.preparedTriggers.delete(oldest);
+      }
+    }
+    return prepared;
+  }
+
+  function computePendingHistory(
+    queue: RoomQueue,
+    agentId: string,
+    roomId: string,
+    limit: number,
+  ): HistoryEntry[] {
+    if (limit <= 0 || queue.entries.length === 0) {
+      return [];
+    }
+    const wm = agentWatermarks.get(wmKey(agentId, roomId)) ?? 0;
+    // startAbs: the first absolute index the agent hasn't seen yet
+    const startAbs = Math.max(wm, queue.baseIndex);
+    const startRel = startAbs - queue.baseIndex;
+    const available = queue.entries.slice(startRel);
+    return available.length > limit ? available.slice(-limit) : available;
+  }
+
+  return {
+    recordPending(roomId, entry) {
+      const queue = getOrCreateQueue(roomId);
+      appendToQueue(queue, entry);
+    },
+
+    getPendingHistory(agentId, roomId, limit) {
+      const queue = roomQueues.get(roomId);
+      if (!queue) {
+        return [];
+      }
+      return computePendingHistory(queue, agentId, roomId, limit);
+    },
+
+    recordTrigger(roomId, entry) {
+      const queue = getOrCreateQueue(roomId);
+      return appendToQueue(queue, entry);
+    },
+
+    prepareTrigger(agentId, roomId, limit, entry) {
+      const queue = getOrCreateQueue(roomId);
+      const retryKey = preparedTriggerKey(agentId, entry.messageId);
+      if (retryKey) {
+        const prepared = queue.preparedTriggers.get(retryKey);
+        if (prepared) {
+          return rememberPreparedTrigger(queue, retryKey, prepared);
+        }
+      }
+      const prepared = {
+        history: computePendingHistory(queue, agentId, roomId, limit),
+        ...appendToQueue(queue, entry),
+      };
+      if (retryKey) {
+        return rememberPreparedTrigger(queue, retryKey, prepared);
+      }
+      return prepared;
+    },
+
+    consumeHistory(agentId, roomId, snapshot, messageId) {
+      const key = wmKey(agentId, roomId);
+      const queue = roomQueues.get(roomId);
+      if (!queue) {
+        // The room was evicted while this trigger was in flight. Keep eviction authoritative
+        // so a late completion cannot recreate a stale watermark against a fresh queue.
+        agentWatermarks.delete(key);
+        return;
+      }
+      if (queue.generation !== snapshot.queueGeneration) {
+        // The room was evicted and recreated before this trigger completed. Reject the stale
+        // snapshot so it cannot advance or erase state for the new queue generation.
+        return;
+      }
+      // Monotone write: never regress an already-advanced watermark.
+      // Guards against out-of-order completion when two triggers for the same
+      // (agentId, roomId) are in-flight concurrently.
+      rememberWatermark(key, snapshot.snapshotIdx);
+      const retryKey = preparedTriggerKey(agentId, messageId);
+      if (queue && retryKey) {
+        queue.preparedTriggers.delete(retryKey);
+      }
+    },
+  };
+}
+
+export function createRoomHistoryTracker(
+  maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+  maxRoomQueues = DEFAULT_MAX_ROOM_QUEUES,
+  maxWatermarkEntries = MAX_WATERMARK_ENTRIES,
+  maxPreparedTriggerEntries = MAX_PREPARED_TRIGGER_ENTRIES,
+): RoomHistoryTracker {
+  const tracker = createRoomHistoryTrackerInternal(
+    maxQueueSize,
+    maxRoomQueues,
+    maxWatermarkEntries,
+    maxPreparedTriggerEntries,
+  );
+  return {
+    recordPending: tracker.recordPending,
+    prepareTrigger: tracker.prepareTrigger,
+    consumeHistory: tracker.consumeHistory,
+  };
+}
+
+export function createRoomHistoryTrackerForTests(
+  maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+  maxRoomQueues = DEFAULT_MAX_ROOM_QUEUES,
+  maxWatermarkEntries = MAX_WATERMARK_ENTRIES,
+  maxPreparedTriggerEntries = MAX_PREPARED_TRIGGER_ENTRIES,
+): RoomHistoryTrackerTestApi {
+  return createRoomHistoryTrackerInternal(
+    maxQueueSize,
+    maxRoomQueues,
+    maxWatermarkEntries,
+    maxPreparedTriggerEntries,
+  );
+}

package/src/matrix/monitor/room-info.ts

@@ -0,0 +1,126 @@
+import { isMatrixNotFoundError } from "../errors.js";
+import type { MatrixClient } from "../sdk.js";
+
+export type MatrixRoomInfo = {
+  name?: string;
+  canonicalAlias?: string;
+  altAliases: string[];
+  nameResolved: boolean;
+  aliasesResolved: boolean;
+};
+
+const MAX_TRACKED_ROOM_INFO = 1024;
+const MAX_TRACKED_MEMBER_DISPLAY_NAMES = 4096;
+
+function rememberBounded<T>(map: Map<string, T>, key: string, value: T, maxEntries: number): void {
+  map.set(key, value);
+  if (map.size > maxEntries) {
+    const oldest = map.keys().next().value;
+    if (typeof oldest === "string") {
+      map.delete(oldest);
+    }
+  }
+}
+
+export function createMatrixRoomInfoResolver(client: MatrixClient) {
+  const roomNameCache = new Map<string, Pick<MatrixRoomInfo, "name" | "nameResolved">>();
+  const roomAliasCache = new Map<
+    string,
+    Pick<MatrixRoomInfo, "canonicalAlias" | "altAliases" | "aliasesResolved">
+  >();
+  const memberDisplayNameCache = new Map<string, string>();
+
+  const getRoomName = async (
+    roomId: string,
+  ): Promise<Pick<MatrixRoomInfo, "name" | "nameResolved">> => {
+    if (roomNameCache.has(roomId)) {
+      return roomNameCache.get(roomId) ?? { nameResolved: false };
+    }
+    let name: string | undefined;
+    let nameResolved = false;
+    try {
+      const nameState = await client.getRoomStateEvent(roomId, "m.room.name", "");
+      nameResolved = true;
+      if (nameState && typeof nameState.name === "string") {
+        name = nameState.name;
+      }
+    } catch (err) {
+      if (isMatrixNotFoundError(err)) {
+        nameResolved = true;
+      }
+    }
+    const info = { name, nameResolved };
+    if (nameResolved) {
+      rememberBounded(roomNameCache, roomId, info, MAX_TRACKED_ROOM_INFO);
+    }
+    return info;
+  };
+
+  const getRoomAliases = async (
+    roomId: string,
+  ): Promise<Pick<MatrixRoomInfo, "canonicalAlias" | "altAliases" | "aliasesResolved">> => {
+    const cached = roomAliasCache.get(roomId);
+    if (cached) {
+      return cached;
+    }
+    let canonicalAlias: string | undefined;
+    let altAliases: string[] = [];
+    let aliasesResolved = false;
+    try {
+      const aliasState = await client.getRoomStateEvent(roomId, "m.room.canonical_alias", "");
+      aliasesResolved = true;
+      if (aliasState && typeof aliasState.alias === "string") {
+        canonicalAlias = aliasState.alias;
+      }
+      const rawAliases = aliasState?.alt_aliases;
+      if (Array.isArray(rawAliases)) {
+        altAliases = rawAliases.filter((entry): entry is string => typeof entry === "string");
+      }
+    } catch (err) {
+      if (isMatrixNotFoundError(err)) {
+        aliasesResolved = true;
+      }
+    }
+    const info = { canonicalAlias, altAliases, aliasesResolved };
+    if (aliasesResolved) {
+      rememberBounded(roomAliasCache, roomId, info, MAX_TRACKED_ROOM_INFO);
+    }
+    return info;
+  };
+
+  const getRoomInfo = async (
+    roomId: string,
+    opts: { includeAliases?: boolean } = {},
+  ): Promise<MatrixRoomInfo> => {
+    const { name, nameResolved } = await getRoomName(roomId);
+    if (!opts.includeAliases) {
+      return { name, altAliases: [], nameResolved, aliasesResolved: false };
+    }
+    const aliases = await getRoomAliases(roomId);
+    return { name, nameResolved, ...aliases };
+  };
+
+  const getMemberDisplayName = async (roomId: string, userId: string): Promise<string> => {
+    const cacheKey = `${roomId}:${userId}`;
+    if (memberDisplayNameCache.has(cacheKey)) {
+      return memberDisplayNameCache.get(cacheKey) ?? userId;
+    }
+    const memberState = await client
+      .getRoomStateEvent(roomId, "m.room.member", userId)
+      .catch(() => null);
+    const displayName =
+      memberState && typeof memberState.displayname === "string" ? memberState.displayname : userId;
+    rememberBounded(
+      memberDisplayNameCache,
+      cacheKey,
+      displayName,
+      MAX_TRACKED_MEMBER_DISPLAY_NAMES,
+    );
+    return displayName;
+  };
+
+  return {
+    getRoomInfo,
+    getMemberDisplayName,
+  };
+}

package/src/matrix/monitor/rooms.ts

@@ -0,0 +1,52 @@
+import type { MatrixRoomConfig } from "../../types.js";
+import { buildChannelKeyCandidates, resolveChannelEntryMatch } from "./runtime-api.js";
+
+type MatrixRoomConfigResolved = {
+  allowed: boolean;
+  allowlistConfigured: boolean;
+  config?: MatrixRoomConfig;
+  matchKey?: string;
+  matchSource?: "direct" | "wildcard";
+};
+
+function readLegacyRoomAllowAlias(room: MatrixRoomConfig | undefined): boolean | undefined {
+  const rawRoom = room as Record<string, unknown> | undefined;
+  return typeof rawRoom?.allow === "boolean" ? rawRoom.allow : undefined;
+}
+
+export function resolveMatrixRoomConfig(params: {
+  rooms?: Record<string, MatrixRoomConfig>;
+  roomId: string;
+  aliases: string[];
+}): MatrixRoomConfigResolved {
+  const rooms = params.rooms ?? {};
+  const keys = Object.keys(rooms);
+  const allowlistConfigured = keys.length > 0;
+  const candidates = buildChannelKeyCandidates(
+    params.roomId,
+    `room:${params.roomId}`,
+    ...params.aliases,
+  );
+  const {
+    entry: matched,
+    key: matchedKey,
+    wildcardEntry,
+    wildcardKey,
+  } = resolveChannelEntryMatch({
+    entries: rooms,
+    keys: candidates,
+    wildcardKey: "*",
+  });
+  const resolved = matched ?? wildcardEntry;
+  const legacyAllow = readLegacyRoomAllowAlias(resolved);
+  const allowed = resolved ? resolved.enabled !== false && legacyAllow !== false : false;
+  const matchKey = matchedKey ?? wildcardKey;
+  const matchSource = matched ? "direct" : wildcardEntry ? "wildcard" : undefined;
+  return {
+    allowed,
+    allowlistConfigured,
+    config: resolved,
+    matchKey,
+    matchSource,
+  };
+}