@xmanrui/dsh-im 4.24.1 → 4.26.0

package/src/channels/matrix/matrix-harness-client.mjs

@@ -0,0 +1,11 @@
+import { HarnessClient } from '../shared/harness-client.mjs';
+
+export class MatrixHarnessClient extends HarnessClient {
+  constructor(options) {
+    super({
+      ...options,
+      rpcIdPrefix: 'matrix',
+      logPrefix: 'dsh-matrix',
+    });
+  }
+}

package/src/channels/matrix/matrix-normalize.mjs

@@ -0,0 +1,357 @@
+/**
+ * Pure Matrix inbound funnel helpers: identity guards, dedup ring, startup
+ * grace and clock-skew detection, mention detection with its fallback chain,
+ * mention stripping, the `!command` normalization and the normalized-message
+ * projection the TextHarnessBridge consumes. Every function is deterministic
+ * and side-effect free so the funnel is unit-testable without a homeserver.
+ */
+
+import { isMatrixEventId, isMatrixRoomId, isMatrixUserId } from './matrix-api.mjs';
+
+const GRACE_MS = 5_000;
+const SKEW_OBSERVE_AFTER_MS = 30_000;
+const SKEW_THRESHOLD_MS = 300_000;
+const SKEW_STREAK_TO_WARN = 3;
+
+function lowerId(value) {
+  return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+
+export function localpartOf(mxid) {
+  const raw = lowerId(mxid);
+  if (!raw.startsWith('@')) return '';
+  const separator = raw.indexOf(':');
+  return separator > 1 ? raw.slice(1, separator) : '';
+}
+
+export function serverNameOf(mxid) {
+  const raw = lowerId(mxid);
+  if (!raw.startsWith('@')) return '';
+  const separator = raw.indexOf(':');
+  return separator > 1 ? raw.slice(separator + 1) : '';
+}
+
+export class EventDedupeRing {
+  #capacity;
+  #seen = new Set();
+  #order = [];
+
+  constructor(capacity = 1_000) {
+    this.#capacity = capacity;
+  }
+
+  seed(ids) {
+    for (const id of Array.isArray(ids) ? ids : []) this.#push(id);
+  }
+
+  has(eventId) {
+    return this.#seen.has(eventId);
+  }
+
+  /** Returns true only for the first observation of an event id. */
+  mark(eventId) {
+    if (typeof eventId !== 'string' || !eventId || this.#seen.has(eventId)) return false;
+    this.#push(eventId);
+    return true;
+  }
+
+  snapshot() {
+    return [...this.#order];
+  }
+
+  #push(eventId) {
+    if (this.#seen.has(eventId)) return;
+    this.#seen.add(eventId);
+    this.#order.push(eventId);
+    while (this.#order.length > this.#capacity) {
+      const oldest = this.#order.shift();
+      this.#seen.delete(oldest);
+    }
+  }
+}
+
+/**
+ * Drops timeline events stamped before the connection became live and detects a
+ * host clock running ahead of the homeserver: after the observation window,
+ * three consecutive far-past timestamps with a consistent offset mark the
+ * local clock skewed, so the guard warns exactly once and keeps dropping the
+ * stale backlog instead of silencing the bot forever.
+ */
+export class ClockSkewGuard {
+  #startupTsMs;
+  #firstObservedAt = null;
+  #skewStreak = 0;
+  #warned = false;
+
+  constructor({ startupTsMs = Date.now() } = {}) {
+    this.#startupTsMs = startupTsMs;
+  }
+
+  evaluate(eventOriginServerTsMs, nowMs = Date.now()) {
+    if (!Number.isSafeInteger(eventOriginServerTsMs) || eventOriginServerTsMs <= 0) {
+      return { drop: false, warnSkew: false };
+    }
+    if (eventOriginServerTsMs < this.#startupTsMs - GRACE_MS) {
+      return { drop: true, warnSkew: false };
+    }
+    const skewMs = nowMs - eventOriginServerTsMs;
+    if (skewMs <= SKEW_THRESHOLD_MS || nowMs - this.#startupTsMs < SKEW_OBSERVE_AFTER_MS) {
+      this.#skewStreak = 0;
+      return { drop: false, warnSkew: false };
+    }
+    this.#skewStreak += 1;
+    if (!this.#warned && this.#skewStreak >= SKEW_STREAK_TO_WARN) {
+      this.#warned = true;
+      return { drop: true, warnSkew: true };
+    }
+    return { drop: this.#warned, warnSkew: false };
+  }
+
+  get warned() {
+    return this.#warned;
+  }
+}
+
+export function isSelfSender(sender, botUserId) {
+  // An unresolved own identity is treated as self: dropping a first message is
+  // survivable, answering oneself in a loop is not.
+  const own = lowerId(botUserId);
+  if (!own) return true;
+  return lowerId(sender) === own;
+}
+
+export function isBridgeOrSystemSender(sender) {
+  const raw = typeof sender === 'string' ? sender.trim() : '';
+  if (!raw.startsWith('@')) return true;
+  const localpart = localpartOf(raw);
+  if (!localpart) return true;
+  // Appservice bridges and puppeting conventions prefix virtual users with `_`.
+  return localpart.startsWith('_');
+}
+
+export function compileIgnorePatterns(values) {
+  const patterns = [];
+  for (const value of Array.isArray(values) ? values : []) {
+    if (typeof value !== 'string' || !value.trim()) continue;
+    try {
+      patterns.push(new RegExp(value, 'iu'));
+    } catch {
+      // A broken operator pattern must not break the funnel; it is skipped.
+    }
+  }
+  return patterns;
+}
+
+export function matchesIgnoredSender(sender, patterns) {
+  const raw = typeof sender === 'string' ? sender.trim() : '';
+  if (!raw) return false;
+  return patterns.some((pattern) => {
+    pattern.lastIndex = 0;
+    return pattern.test(raw);
+  });
+}
+
+/**
+ * Mention detection with a fallback chain: the MSC3952 `m.mentions.user_ids`
+ * signal is authoritative, then a raw full MXID in the body, then a pill link
+ * in formatted_body, then a word-bounded localpart. One weak signal missing
+ * never silences the bot because the chain keeps the stronger ones.
+ */
+export function detectMatrixMention(content, botUserId) {
+  const own = lowerId(botUserId);
+  if (!own) return false;
+  const mentions = Array.isArray(content?.['m.mentions']?.user_ids) ? content['m.mentions'].user_ids : [];
+  if (mentions.some((candidate) => lowerId(candidate) === own)) return true;
+  const body = typeof content?.body === 'string' ? content.body : '';
+  if (body.toLowerCase().includes(`<${own}>`)) return true;
+  if (body.toLowerCase().includes(own)) {
+    const escaped = own.replace(/[.*+?^${}()|\\\[\]]/g, '\\$&');
+    if (new RegExp(`(^|[^A-Za-z0-9._=\\-\\/+])${escaped}($|[^A-Za-z0-9._=\\-\\/+])`, 'iu').test(body)) return true;
+  }
+  const formatted = typeof content?.formatted_body === 'string' ? content.formatted_body : '';
+  if (formatted.toLowerCase().includes(`matrix.to/#/${own}`)) return true;
+  const localpart = localpartOf(own);
+  if (localpart.length >= 2 && localpart !== 'room' && localpart !== 'all') {
+    const escaped = localpart.replace(/[.*+?^${}()|\\\[\]]/g, '\\$&');
+    const bodyHit = new RegExp(`(^|[^A-Za-z0-9._=\\-\\/+])@${escaped}($|[^A-Za-z0-9._=\\-\\/+])`, 'iu').test(body);
+    if (bodyHit) return true;
+  }
+  return false;
+}
+
+/**
+ * Remove bot-directed mention forms from prompt text. Only full `@local:server`
+ * forms and Matrix pill forms are stripped; a bare localpart word is never
+ * removed so phrases like "Hermes Agent" survive intact.
+ */
+export function stripMatrixMentions(body, botUserId) {
+  let text = String(body ?? '');
+  const own = lowerId(botUserId);
+  if (own) {
+    const escaped = own.replace(/[.*+?^${}()|\\\[\]]/g, '\\$&');
+    const pill = new RegExp(`\\[<${escaped}>\\]\\(https?://matrix\\.to/[^)]*\\)`, 'gi');
+    text = text.replaceAll(pill, '');
+    text = text.replaceAll(new RegExp(`<${escaped}>`, 'gi'), '');
+    text = text.replaceAll(new RegExp(escaped, 'gi'), '');
+  }
+  return text.trim();
+}
+
+export function isMatrixCommandLike(text) {
+  return /^[/!][A-Za-z][A-Za-z0-9_-]{0,63}(\s|$)/.test(String(text ?? '').trim());
+}
+
+export function resolveBangMatrixCommand(text, isKnownSlashCommand) {
+  const trimmed = String(text ?? '');
+  if (!trimmed.startsWith('!') || trimmed.startsWith('!!')) return trimmed;
+  const candidate = trimmed.replace(/^!/, '');
+  const token = `/${candidate.split(/\s/u, 1)[0] ?? ''}`.replace(/[。？！,.!?；;:]+$/u, '');
+  const name = token.slice(1);
+  if (!name || typeof isKnownSlashCommand !== 'function') return trimmed;
+  if (!isKnownSlashCommand(name) && !isKnownSlashCommand(token)) return trimmed;
+  return `/${candidate}`;
+}
+
+const MEDIA_MSGTYPES = new Set(['m.image', 'm.audio', 'm.video', 'm.file']);
+
+function eventOriginTs(event) {
+  const ts = Number(event?.origin_server_ts ?? event?.['org.matrix.server_ts']);
+  return Number.isSafeInteger(ts) && ts > 0 ? (ts < 1e12 ? ts * 1_000 : ts) : null;
+}
+
+function threadIdOf(content) {
+  const relates = content?.['m.relates_to'];
+  if (!relates || typeof relates !== 'object') return null;
+  const chain = Array.isArray(relates.chain) ? relates.chain : [];
+  const threaded = chain.find((entry) => entry?.rel_type === 'm.thread') ?? (relates.rel_type === 'm.thread' ? relates : null);
+  const eventId = typeof threaded?.event_id === 'string' ? threaded.event_id : null;
+  return eventId && isMatrixEventId(eventId) ? eventId : null;
+}
+
+function replyEventIdOf(content) {
+  const inReplyTo = content?.['m.relates_to']?.['m.in_reply_to'];
+  const eventId = typeof inReplyTo?.event_id === 'string' ? inReplyTo.event_id : null;
+  return eventId && isMatrixEventId(eventId) ? eventId : null;
+}
+
+/**
+ * Project one timeline event into the normalized bridge message, or into a
+ * typed drop reason. The order of gates is fixed: self, bridge/system,
+ * ignore patterns, dedup, clock, shape, notice/edit, room policy, mention
+ * policy. Media sources are created through `deps.createMediaSource` so the
+ * funnel stays free of transport code.
+ */
+export function normalizeMatrixTimelineEvent({
+  event,
+  roomId,
+  botUserId,
+  isDirect,
+  config = {},
+  patterns = [],
+  ring,
+  clock,
+  deps = {},
+} = {}) {
+  const senderId = typeof event?.sender === 'string' ? event.sender.trim() : '';
+  const eventId = typeof event?.event_id === 'string' ? event.event_id.trim() : '';
+  if (!isMatrixRoomId(roomId) || !eventId || !senderId) return { drop: 'malformed' };
+  if (isSelfSender(senderId, botUserId)) return { drop: 'self' };
+  if (isBridgeOrSystemSender(senderId)) return { drop: 'bridge' };
+  if (matchesIgnoredSender(senderId, patterns)) return { drop: 'ignored' };
+  if (ring && !ring.mark(eventId)) return { drop: 'duplicate' };
+  if (clock) {
+    const verdict = clock.evaluate(eventOriginTs(event));
+    if (verdict.drop) return { drop: 'clock', warnSkew: verdict.warnSkew };
+  }
+  if (event?.type !== 'm.room.message') return { drop: 'type' };
+  const content = event.content && typeof event.content === 'object' ? event.content : {};
+  const msgtype = typeof content.msgtype === 'string' ? content.msgtype : 'm.text';
+  if (msgtype === 'm.notice' && config.processNotices !== true) return { drop: 'notice' };
+  const isEdit = content['m.relates_to']?.rel_type === 'm.replace';
+  if (isEdit) return { drop: 'edit' };
+
+  const kind = isDirect ? 'direct' : 'group';
+  const allowedRooms = config.allowedRooms instanceof Set ? config.allowedRooms : null;
+  if (kind === 'group' && allowedRooms && allowedRooms.size > 0 && !allowedRooms.has(roomId)) {
+    return { drop: 'room-not-allowed' };
+  }
+
+  const threadId = threadIdOf(content);
+  const replyToEventId = replyEventIdOf(content);
+  const rawText = typeof content.body === 'string' ? content.body : '';
+  const mentioned = detectMatrixMention(content, botUserId);
+  const commandLike = isMatrixCommandLike(rawText);
+  const requiresMention = kind === 'group'
+    && config.requireMention !== false
+    && !(config.freeResponseRooms instanceof Set && config.freeResponseRooms.has(roomId));
+  if (requiresMention && !mentioned && !commandLike && replyToEventId === null) return { drop: 'mention-required' };
+
+  const text = stripMatrixMentions(rawText, botUserId);
+  const media = MEDIA_MSGTYPES.has(msgtype)
+    ? (deps.createMediaSource ? deps.createMediaSource(content, msgtype) : null)
+    : null;
+  if (MEDIA_MSGTYPES.has(msgtype) && !media) return { drop: 'media-unusable' };
+  if (msgtype !== 'm.text' && msgtype !== 'm.notice' && !MEDIA_MSGTYPES.has(msgtype)) return { drop: 'type' };
+
+  const conversationId = kind === 'direct'
+    ? `dm:${senderId.toLowerCase()}`
+    : `room:${roomId}${threadId ? `$${threadId}` : ''}`;
+
+  return {
+    message: {
+      kind,
+      roomId,
+      messageId: eventId,
+      senderId,
+      senderIsBot: false,
+      conversationId,
+      contextSource: () => ({ chatId: roomId, ...(threadId ? { threadId } : {}) }),
+      content: text,
+      plainText: msgtype === 'm.text' && content.format !== 'org.matrix.custom.html',
+      images: media?.images ?? [],
+      files: media?.files ?? [],
+      addressed: kind === 'direct' || mentioned || commandLike || replyToEventId !== null,
+      mentioned,
+      threadId,
+      replyToEventId,
+      reactionTarget: { roomId, eventId },
+      replyTarget: {
+        roomId,
+        ...(threadId ? { threadId } : {}),
+        ...(!threadId && replyToEventId ? { replyToEventId } : {}),
+        recipientUserId: senderId,
+      },
+      ...(kind === 'direct' ? { connectionTestTarget: { roomId } } : {}),
+    },
+  };
+}
+
+export function normalizeMatrixDeliveryTarget({ kind, route } = {}) {
+  if (kind === 'room') {
+    if (Object.keys(route ?? {}).join(',') !== 'roomId') return { error: 'route' };
+    const roomId = String(route.roomId ?? '').trim();
+    if (!isMatrixRoomId(roomId)) return { error: 'roomId' };
+    return { value: { kind, roomId } };
+  }
+  if (kind === 'thread') {
+    if (Object.keys(route ?? {}).sort().join(',') !== 'roomId,threadId') return { error: 'route' };
+    const roomId = String(route.roomId ?? '').trim();
+    const threadId = String(route.threadId ?? '').trim();
+    if (!isMatrixRoomId(roomId)) return { error: 'roomId' };
+    if (!isMatrixEventId(threadId)) return { error: 'threadId' };
+    return { value: { kind, roomId, threadId } };
+  }
+  if (kind === 'dm') {
+    if (Object.keys(route ?? {}).join(',') !== 'userId') return { error: 'route' };
+    const userId = String(route.userId ?? '').trim();
+    if (!isMatrixUserId(userId)) return { error: 'userId' };
+    return { value: { kind, userId } };
+  }
+  return { error: 'kind' };
+}
+
+export function matrixConversationKeyFromTarget(target) {
+  if (!target) return null;
+  if (target.kind === 'dm') return `dm:${target.userId.toLowerCase()}`;
+  return `room:${target.roomId}${'threadId' in target && target.threadId ? `$${target.threadId}` : ''}`;
+}

package/src/channels/matrix/matrix-rich-text.mjs

@@ -0,0 +1,313 @@
+/**
+ * Matrix-side rich-text construction and pure event-content builders.
+ *
+ * The harness replies with Markdown or plain text. Matrix clients render
+ * `formatted_body` when the format is recognized, so this module produces the
+ * sanitized HTML projection plus the always-present plain `body` fallback,
+ * injects MXID pills outside code regions, and builds the relation events for
+ * replies, threads, edits and reactions exactly once per message pipeline.
+ */
+
+const SAFE_URL_SCHEMES = new Set(['http:', 'https:', 'matrix:', 'mailto:']);
+
+const ALLOWED_TAGS = Object.freeze({
+  br: [], b: [], strong: [], i: [], em: [], u: [], del: [], s: [],
+  code: ['class'], pre: [], blockquote: [], ul: [], ol: [], li: [],
+  a: ['href'], h1: [], h2: [], h3: [], h4: [], h5: [], h6: [],
+  table: [], thead: [], tbody: [], tr: [], th: [], td: [],
+  p: [], hr: [], details: [], summary: [], span: ['data-mx-id', 'data-mx-pill'],
+});
+
+const TAG_PATTERN = /<\s*(\/?)\s*([a-zA-Z][a-zA-Z0-9-]*)((?:[^<>"']|"[^"]*"|'[^']*')*)\s*(\/?)\s*>/g;
+const ATTRIBUTE_PATTERN = /([a-zA-Z_:][-a-zA-Z0-9_:]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/g;
+
+export function escapeMatrixHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
+
+function safeMatrixUrl(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw || /[\u0000-\u0020\u007f]/u.test(raw)) return null;
+  if (raw.startsWith('#') || raw.startsWith('/')) return null;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    // Relative and scheme-less links stay visible as plain text instead of
+    // becoming dead anchors; Matrix clients cannot resolve them anyway.
+    if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:/u.test(raw)) return raw;
+    return null;
+  }
+  return SAFE_URL_SCHEMES.has(url.protocol) ? url.href : null;
+}
+
+function decodeAttributeEntities(value) {
+  return String(value ?? '')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&#39;', "'")
+    .replaceAll(/&#(\d{1,7});/gu, (match) => String.fromCodePoint(Number(match.slice(2, -1))))
+    .replaceAll(/&#x([0-9A-Fa-f]{1,6});/gu, (match) => String.fromCodePoint(Number(`0x${match.slice(3, -1)}`)))
+    .replaceAll('&amp;', '&');
+}
+
+function sanitizeAttributes(tag, attributeText) {
+  const allowed = ALLOWED_TAGS[tag] ?? [];
+  if (allowed.length === 0 || !attributeText.trim()) return '';
+  const kept = [];
+  for (const match of attributeText.matchAll(ATTRIBUTE_PATTERN)) {
+    const name = String(match[1] ?? '').toLowerCase();
+    const value = match[2] ?? match[3] ?? match[4] ?? '';
+    if (!allowed.includes(name)) continue;
+    if (name === 'href') {
+      const safe = safeMatrixUrl(decodeAttributeEntities(value));
+      if (safe) kept.push(`href="${escapeMatrixHtml(safe)}"`);
+      continue;
+    }
+    if (name === 'class') {
+      if (/^language-[A-Za-z0-9+-]{1,64}$/.test(value)) kept.push(`class="${escapeMatrixHtml(value)}"`);
+      continue;
+    }
+    kept.push(`${name}="${escapeMatrixHtml(value)}"`);
+  }
+  return kept.length ? ` ${kept.join(' ')}` : '';
+}
+
+/**
+ * Whitelist-only HTML sanitizer for outbound `formatted_body`. Unknown tags are
+ * dropped while their text content survives; `on*` attributes, inline event
+ * handlers and `javascript:`/`data:` schemes never survive the attribute pass.
+ */
+export function sanitizeMatrixHtml(html) {
+  if (typeof html !== 'string' || !html) return '';
+  const stripped = html
+    .replaceAll(/<\s*(script|style|iframe|form|object|embed)\b[\s\S]*?<\s*\/\s*\1\s*>/gi, '')
+    .replaceAll(/<\s*(script|style|iframe|form|object|embed)\b[^>]*\/?\s*>/gi, '');
+  return stripped.replaceAll(TAG_PATTERN, (whole, closing, rawTag, attributes, selfClose) => {
+    const tag = rawTag.toLowerCase();
+    if (!Object.hasOwn(ALLOWED_TAGS, tag)) return '';
+    if (closing) return selfClose ? '' : `</${tag}>`;
+    const attribute = sanitizeAttributes(tag, attributes ?? '');
+    const selfClosing = selfClose && (tag === 'br' || tag === 'hr' || tag === 'img') ? ' /' : '';
+    return `<${tag}${attribute}${selfClosing}>`;
+  });
+}
+
+function inlineMatrixPass(escaped) {
+  const codeStash = [];
+  const stash = (html) => {
+    codeStash.push(html);
+    return `\u0000${codeStash.length - 1}\u0000`;
+  };
+  let text = escaped.replace(/`([^`\n]+)`/g, (_whole, inner) => stash(`<code>${inner}</code>`));
+  text = text.replace(/\*\*([^*\n]+)\*\*|__([^_\n]+)__/g, (_whole, a, b) => `<strong>${a ?? b}</strong>`);
+  text = text.replace(/(^|[^*])\*([^*\n]+)\*(?!\*)/g, (_whole, lead, inner) => `${lead}<em>${inner}</em>`);
+  text = text.replace(/~~([^~\n]+)~~/g, (_whole, inner) => `<del>${inner}</del>`);
+  text = text.replace(/\[([^\]\n]*)\]\(([^)\s]+)\)/g, (_whole, label, target) => {
+    const safe = safeMatrixUrl(target.replaceAll(/&amp;/g, '&'));
+    if (!safe) return `${label} (${target})`;
+    return stash(`<a href="${escapeMatrixHtml(safe)}">${label}</a>`);
+  });
+  text = text.replace(/\u0000(\d+)\u0000/g, (_whole, index) => codeStash[Number(index)] ?? '');
+  return text;
+}
+
+/**
+ * Deterministic Markdown subset for Matrix rendering: fenced and inline code,
+ * bold/italic/strikethrough, links, ATX headings, bullet and ordered lists,
+ * blockquotes, thematic breaks and hard line breaks. Everything else stays
+ * literal text, so tables keep readable prose instead of collapsing.
+ */
+export function markdownToMatrixHtml(text) {
+  const source = String(text ?? '');
+  if (!source) return '';
+  const lines = source.replaceAll('\r\n', '\n').split('\n');
+  const blocks = [];
+  let paragraph = [];
+  let list = null;
+  let quote = [];
+  let fence = null;
+
+  const flushParagraph = () => {
+    if (!paragraph.length) return;
+    blocks.push(`<p>${paragraph.map((line) => inlineMatrixPass(escapeMatrixHtml(line))).join('<br/>')}</p>`);
+    paragraph = [];
+  };
+  const flushList = () => {
+    if (!list) return;
+    const items = list.items.map((item) => `<li>${inlineMatrixPass(escapeMatrixHtml(item))}</li>`).join('');
+    blocks.push(list.ordered ? `<ol>${items}</ol>` : `<ul>${items}</ul>`);
+    list = null;
+  };
+  const flushQuote = () => {
+    if (!quote.length) return;
+    blocks.push(`<blockquote>${quote.map((line) => inlineMatrixPass(escapeMatrixHtml(line))).join('<br/>')}</blockquote>`);
+    quote = [];
+  };
+  const flushAll = () => {
+    flushParagraph();
+    flushList();
+    flushQuote();
+  };
+
+  for (const line of lines) {
+    const fenceMatch = /^\s{0,3}(`{3,}|~{3,})\s*([A-Za-z0-9+._-]*)\s*$/.exec(line);
+    if (fence && line.trim().endsWith(fence.marker) && line.trim().length >= fence.marker.length) {
+      blocks.push(`<pre><code class="language-${escapeMatrixHtml(fence.lang || 'plain')}">${
+        escapeMatrixHtml(fence.body.join('\n'))
+      }</code></pre>`);
+      fence = null;
+      continue;
+    }
+    if (fence) {
+      fence.body.push(line);
+      continue;
+    }
+    if (fenceMatch) {
+      flushAll();
+      fence = { marker: fenceMatch[1], lang: fenceMatch[2] ?? '', body: [] };
+      continue;
+    }
+    const heading = /^\s{0,3}(#{1,6})\s+(.*)$/.exec(line);
+    if (heading) {
+      flushAll();
+      blocks.push(`<p><strong>${inlineMatrixPass(escapeMatrixHtml(heading[2].trim()))}</strong></p>`);
+      continue;
+    }
+    if (/^\s{0,3}([-*_])\s*(?:\1\s*){2,}$/.test(line)) {
+      flushAll();
+      blocks.push('<hr/>');
+      continue;
+    }
+    const quoteMatch = /^\s{0,3}>\s?(.*)$/.exec(line);
+    if (quoteMatch) {
+      flushParagraph();
+      flushList();
+      quote.push(quoteMatch[1]);
+      continue;
+    }
+    flushQuote();
+    const bullet = /^\s*[-+*]\s+(.*)$/.exec(line);
+    const ordered = /^\s*(\d{1,9})[.)]\s+(.*)$/.exec(line);
+    if (bullet || ordered) {
+      flushParagraph();
+      const orderedItem = ordered ? ordered[2] : bullet[1];
+      if (!list || list.ordered !== Boolean(ordered)) {
+        flushList();
+        list = { ordered: Boolean(ordered), items: [] };
+      }
+      list.items.push(orderedItem);
+      continue;
+    }
+    if (!line.trim()) {
+      flushAll();
+      continue;
+    }
+    flushList();
+    flushQuote();
+    paragraph.push(line);
+  }
+  if (fence) {
+    blocks.push(`<pre><code class="language-${escapeMatrixHtml(fence.lang || 'plain')}">${
+      escapeMatrixHtml(fence.body.join('\n'))
+    }</code></pre>`);
+  }
+  flushAll();
+  return blocks.join('\n');
+}
+
+function protectCodeRegions(text) {
+  const stash = [];
+  const protectedText = text
+    .replaceAll(/```[\s\S]*?```/g, (whole) => {
+      stash.push(whole);
+      return `\u0001${stash.length - 1}\u0001`;
+    })
+    .replaceAll(/`[^`\n]+`/g, (whole) => {
+      stash.push(whole);
+      return `\u0001${stash.length - 1}\u0001`;
+    });
+  return { protectedText, stash };
+}
+
+function restoreCodeRegions(text, stash) {
+  return text.replaceAll(/\u0001(\d+)\u0001/g, (_whole, index) => stash[Number(index)] ?? '');
+}
+
+const OUTBOUND_MENTION_PATTERN = /(^|[\s(])@([A-Za-z0-9._=\-\/+]+):([A-Za-z0-9.-]+(?::\d{1,5})?)/g;
+
+/** Collect the full MXIDs an outbound message mentions for `m.mentions`. */
+export function extractOutboundMentions(text) {
+  const mentions = [];
+  const { protectedText } = protectCodeRegions(String(text ?? ''));
+  for (const match of protectedText.matchAll(OUTBOUND_MENTION_PATTERN)) {
+    mentions.push(`@${match[2]}:${match[3]}`);
+  }
+  return [...new Set(mentions)];
+}
+
+export function hasRoomMention(text) {
+  const { protectedText } = protectCodeRegions(String(text ?? ''));
+  return /(^|[\s(])@(room|all)\b/u.test(protectedText);
+}
+
+/**
+ * Wrap full MXIDs outside code regions into Matrix pill links so Element-style
+ * clients render them as chips; `m.mentions` still carries the notification set.
+ */
+export function injectOutboundMentionPills(text) {
+  const { protectedText, stash } = protectCodeRegions(String(text ?? ''));
+  const pillText = protectedText.replaceAll(
+    OUTBOUND_MENTION_PATTERN,
+    (_whole, lead, localpart, server) => `${lead}[<@${localpart}:${server}>](https://matrix.to/#/@${localpart}:${server})`,
+  );
+  return restoreCodeRegions(pillText, stash);
+}
+
+export function buildMatrixTextContent({ text, mentionUserIds = [], roomMention = false } = {}) {
+  const body = String(text ?? '');
+  const html = sanitizeMatrixHtml(markdownToMatrixHtml(injectOutboundMentionPills(body)));
+  const hasHtml = Boolean(html) && html !== escapeMatrixHtml(body).replaceAll(/\n/g, '<br/>');
+  const content = { msgtype: 'm.text', body };
+  if (hasHtml) {
+    content.format = 'org.matrix.custom.html';
+    content.formatted_body = html;
+  }
+  const user_ids = [...new Set(mentionUserIds)];
+  if (user_ids.length || roomMention) content['m.mentions'] = { user_ids, 'm.room': roomMention };
+  return content;
+}
+
+export function buildMatrixEditContent({ originalContent, newText, eventId } = {}) {
+  const edited = buildMatrixTextContent({ text: newText, mentionUserIds: originalContent?.['m.mentions']?.user_ids ?? [] });
+  const content = { ...originalContent, ...edited, body: `* ${edited.body}` };
+  if (edited.formatted_body) content.formatted_body = `* ${edited.formatted_body}`;
+  content['m.new_content'] = edited;
+  content['m.relates_to'] = { event_id: eventId, rel_type: 'm.replace' };
+  return content;
+}
+
+export function buildMatrixReactionContent(eventId, key) {
+  return { 'm.relates_to': { event_id: eventId, rel_type: 'm.annotation' }, 'm.reaction': key };
+}
+
+export function applyMatrixRelations(content, { threadId, replyToEventId } = {}) {
+  if (replyToEventId && !threadId) {
+    content['m.relates_to'] = { 'm.in_reply_to': { event_id: replyToEventId }, is_falling_back: false };
+    return content;
+  }
+  if (threadId) {
+    content['m.relates_to'] = {
+      event_id: threadId,
+      rel_type: 'm.thread',
+      is_falling_back: true,
+      'm.in_reply_to': { event_id: replyToEventId ?? threadId },
+    };
+  }
+  return content;
+}