From 534511bebbb13475b9f3dfb638444b5104b316a4 Mon Sep 17 00:00:00 2001 From: nepenth Date: Sun, 5 Apr 2026 11:19:27 -0700 Subject: [PATCH] =?UTF-8?q?feat(matrix):=20Tier=201=20enhancement=20?= =?UTF-8?q?=E2=80=94=20reactions,=20read=20receipts,=20rich=20formatting,?= =?UTF-8?q?=20room=20management?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cherry-picked from PR #4338 by nepenth, resolved against current main. Adds: - Processing lifecycle reactions (eyes/checkmark/cross) via MATRIX_REACTIONS env - Reaction send/receive with ReactionEvent + UnknownEvent fallback for older nio - Fire-and-forget read receipts on text and media messages - Message redaction, room history fetch, room creation, user invite - Presence status control (online/offline/unavailable) - Emote (/me) and notice message types with HTML rendering - XSS-hardened markdown-to-HTML converter (strips raw HTML preprocessor, sanitizes link URLs against javascript:/data:/vbscript: schemes) - Comprehensive regex fallback with full block/inline markdown support - Markdown>=3.6 added to [matrix] extras in pyproject.toml - 46 new tests covering all features and security hardening --- gateway/platforms/matrix.py | 588 +++++++++++++++++++++++++++++++++-- pyproject.toml | 2 +- tests/gateway/test_matrix.py | 418 +++++++++++++++++++++++++ 3 files changed, 989 insertions(+), 19 deletions(-) diff --git a/gateway/platforms/matrix.py b/gateway/platforms/matrix.py index 25f701d95..35cf72ad4 100644 --- a/gateway/platforms/matrix.py +++ b/gateway/platforms/matrix.py @@ -10,8 +10,10 @@ Environment variables: MATRIX_USER_ID Full user ID (@bot:server) — required for password login MATRIX_PASSWORD Password (alternative to access token) MATRIX_ENCRYPTION Set "true" to enable E2EE - MATRIX_ALLOWED_USERS Comma-separated Matrix user IDs (@user:server) - MATRIX_HOME_ROOM Room ID for cron/notification delivery + MATRIX_ALLOWED_USERS Comma-separated Matrix user IDs (@user:server) + MATRIX_HOME_ROOM Room ID for cron/notification delivery + MATRIX_REACTIONS Set "false" to disable processing lifecycle reactions + (eyes/checkmark/cross). Default: true MATRIX_REQUIRE_MENTION Require @mention in rooms (default: true) MATRIX_FREE_RESPONSE_ROOMS Comma-separated room IDs exempt from mention requirement MATRIX_AUTO_THREAD Auto-create threads for room messages (default: true) @@ -30,6 +32,8 @@ import time from pathlib import Path from typing import Any, Dict, Optional, Set +from html import escape as _html_escape + from gateway.config import Platform, PlatformConfig from gateway.platforms.base import ( BasePlatformAdapter, @@ -130,6 +134,11 @@ class MatrixAdapter(BasePlatformAdapter): self._bot_participated_threads: set = self._load_participated_threads() self._MAX_TRACKED_THREADS = 500 + # Reactions: configurable via MATRIX_REACTIONS (default: true). + self._reactions_enabled: bool = os.getenv( + "MATRIX_REACTIONS", "true" + ).lower() not in ("false", "0", "no") + def _is_duplicate_event(self, event_id) -> bool: """Return True if this event was already processed. Tracks the ID otherwise.""" if not event_id: @@ -283,6 +292,13 @@ class MatrixAdapter(BasePlatformAdapter): client.add_event_callback(self._on_room_message_media, encrypted_media_cls) client.add_event_callback(self._on_invite, nio.InviteMemberEvent) + # Reaction events (m.reaction). + if hasattr(nio, "ReactionEvent"): + client.add_event_callback(self._on_reaction, nio.ReactionEvent) + else: + # Older matrix-nio versions: use UnknownEvent fallback. + client.add_event_callback(self._on_unknown_event, nio.UnknownEvent) + # If E2EE: handle encrypted events. if self._encryption and hasattr(client, "olm"): client.add_event_callback( @@ -1002,6 +1018,9 @@ class MatrixAdapter(BasePlatformAdapter): if thread_id: self._track_thread(thread_id) + # Acknowledge receipt so the room shows as read (fire-and-forget). + self._background_read_receipt(room.room_id, event.event_id) + await self.handle_message(msg_event) async def _on_room_message_media(self, room: Any, event: Any) -> None: @@ -1220,6 +1239,9 @@ class MatrixAdapter(BasePlatformAdapter): if thread_id: self._track_thread(thread_id) + # Acknowledge receipt so the room shows as read (fire-and-forget). + self._background_read_receipt(room.room_id, event.event_id) + await self.handle_message(msg_event) async def _on_invite(self, room: Any, event: Any) -> None: @@ -1255,6 +1277,369 @@ class MatrixAdapter(BasePlatformAdapter): except Exception as exc: logger.warning("Matrix: error joining %s: %s", room.room_id, exc) + # ------------------------------------------------------------------ + # Reactions (send, receive, processing lifecycle) + # ------------------------------------------------------------------ + + async def _send_reaction( + self, room_id: str, event_id: str, emoji: str, + ) -> bool: + """Send an emoji reaction to a message in a room.""" + import nio + + if not self._client: + return False + content = { + "m.relates_to": { + "rel_type": "m.annotation", + "event_id": event_id, + "key": emoji, + } + } + try: + resp = await self._client.room_send( + room_id, "m.reaction", content, + ignore_unverified_devices=True, + ) + if isinstance(resp, nio.RoomSendResponse): + logger.debug("Matrix: sent reaction %s to %s", emoji, event_id) + return True + logger.debug("Matrix: reaction send failed: %s", resp) + return False + except Exception as exc: + logger.debug("Matrix: reaction send error: %s", exc) + return False + + async def _redact_reaction( + self, room_id: str, reaction_event_id: str, reason: str = "", + ) -> bool: + """Remove a reaction by redacting its event.""" + return await self.redact_message(room_id, reaction_event_id, reason) + + async def on_processing_start(self, event: MessageEvent) -> None: + """Add eyes reaction when the agent starts processing a message.""" + if not self._reactions_enabled: + return + msg_id = event.message_id + room_id = event.source.chat_id + if msg_id and room_id: + await self._send_reaction(room_id, msg_id, "\U0001f440") + + async def on_processing_complete( + self, event: MessageEvent, success: bool, + ) -> None: + """Replace eyes with checkmark (success) or cross (failure).""" + if not self._reactions_enabled: + return + msg_id = event.message_id + room_id = event.source.chat_id + if not msg_id or not room_id: + return + # Note: Matrix doesn't support removing a specific reaction easily + # without tracking the reaction event_id. We send the new reaction; + # the eyes stays (acceptable UX — both are visible). + await self._send_reaction( + room_id, msg_id, "\u2705" if success else "\u274c", + ) + + async def _on_reaction(self, room: Any, event: Any) -> None: + """Handle incoming reaction events.""" + if event.sender == self._user_id: + return + if self._is_duplicate_event(getattr(event, "event_id", None)): + return + # Log for now; future: trigger agent actions based on emoji. + reacts_to = getattr(event, "reacts_to", "") + key = getattr(event, "key", "") + logger.info( + "Matrix: reaction %s from %s on %s in %s", + key, event.sender, reacts_to, room.room_id, + ) + + async def _on_unknown_event(self, room: Any, event: Any) -> None: + """Fallback handler for events not natively parsed by matrix-nio. + + Catches m.reaction on older nio versions that lack ReactionEvent. + """ + source = getattr(event, "source", {}) + if source.get("type") != "m.reaction": + return + content = source.get("content", {}) + relates_to = content.get("m.relates_to", {}) + if relates_to.get("rel_type") != "m.annotation": + return + if source.get("sender") == self._user_id: + return + logger.info( + "Matrix: reaction %s from %s on %s in %s", + relates_to.get("key", "?"), + source.get("sender", "?"), + relates_to.get("event_id", "?"), + room.room_id, + ) + + # ------------------------------------------------------------------ + # Read receipts + # ------------------------------------------------------------------ + + def _background_read_receipt(self, room_id: str, event_id: str) -> None: + """Fire-and-forget read receipt with error logging.""" + async def _send() -> None: + try: + await self.send_read_receipt(room_id, event_id) + except Exception as exc: # pragma: no cover — defensive + logger.debug("Matrix: background read receipt failed: %s", exc) + asyncio.ensure_future(_send()) + + async def send_read_receipt(self, room_id: str, event_id: str) -> bool: + """Send a read receipt (m.read) for an event. + + Also sets the fully-read marker so the room is marked as read + in all clients. + """ + if not self._client: + return False + try: + if hasattr(self._client, "room_read_markers"): + await self._client.room_read_markers( + room_id, + fully_read_event=event_id, + read_event=event_id, + ) + else: + # Fallback for older matrix-nio. + await self._client.room_send( + room_id, "m.receipt", {"event_id": event_id}, + ) + logger.debug("Matrix: sent read receipt for %s in %s", event_id, room_id) + return True + except Exception as exc: + logger.debug("Matrix: read receipt failed: %s", exc) + return False + + # ------------------------------------------------------------------ + # Message redaction + # ------------------------------------------------------------------ + + async def redact_message( + self, room_id: str, event_id: str, reason: str = "", + ) -> bool: + """Redact (delete) a message or event from a room.""" + import nio + + if not self._client: + return False + try: + resp = await self._client.room_redact( + room_id, event_id, reason=reason, + ) + if isinstance(resp, nio.RoomRedactResponse): + logger.info("Matrix: redacted %s in %s", event_id, room_id) + return True + logger.warning("Matrix: redact failed: %s", resp) + return False + except Exception as exc: + logger.warning("Matrix: redact error: %s", exc) + return False + + # ------------------------------------------------------------------ + # Room history + # ------------------------------------------------------------------ + + async def fetch_room_history( + self, + room_id: str, + limit: int = 50, + start: str = "", + ) -> list: + """Fetch recent messages from a room. + + Returns a list of dicts with keys: event_id, sender, body, + timestamp, type. Uses the ``room_messages()`` API. + """ + import nio + + if not self._client: + return [] + try: + resp = await self._client.room_messages( + room_id, + start=start or "", + limit=limit, + direction=nio.Api.MessageDirection.back + if hasattr(nio.Api, "MessageDirection") + else "b", + ) + except Exception as exc: + logger.warning("Matrix: room_messages failed for %s: %s", room_id, exc) + return [] + + if not isinstance(resp, nio.RoomMessagesResponse): + logger.warning("Matrix: room_messages returned %s", type(resp).__name__) + return [] + + messages = [] + for event in reversed(resp.chunk): + body = getattr(event, "body", "") or "" + messages.append({ + "event_id": getattr(event, "event_id", ""), + "sender": getattr(event, "sender", ""), + "body": body, + "timestamp": getattr(event, "server_timestamp", 0), + "type": type(event).__name__, + }) + return messages + + # ------------------------------------------------------------------ + # Room creation & management + # ------------------------------------------------------------------ + + async def create_room( + self, + name: str = "", + topic: str = "", + invite: Optional[list] = None, + is_direct: bool = False, + preset: str = "private_chat", + ) -> Optional[str]: + """Create a new Matrix room. + + Args: + name: Human-readable room name. + topic: Room topic. + invite: List of user IDs to invite. + is_direct: Mark as a DM room. + preset: One of private_chat, public_chat, trusted_private_chat. + + Returns the room_id on success, None on failure. + """ + import nio + + if not self._client: + return None + try: + resp = await self._client.room_create( + name=name or None, + topic=topic or None, + invite=invite or [], + is_direct=is_direct, + preset=getattr( + nio.Api.RoomPreset if hasattr(nio.Api, "RoomPreset") else type("", (), {}), + preset, None, + ) or preset, + ) + if isinstance(resp, nio.RoomCreateResponse): + room_id = resp.room_id + self._joined_rooms.add(room_id) + logger.info("Matrix: created room %s (%s)", room_id, name or "unnamed") + return room_id + logger.warning("Matrix: room_create failed: %s", resp) + return None + except Exception as exc: + logger.warning("Matrix: room_create error: %s", exc) + return None + + async def invite_user(self, room_id: str, user_id: str) -> bool: + """Invite a user to a room.""" + import nio + + if not self._client: + return False + try: + resp = await self._client.room_invite(room_id, user_id) + if isinstance(resp, nio.RoomInviteResponse): + logger.info("Matrix: invited %s to %s", user_id, room_id) + return True + logger.warning("Matrix: invite failed: %s", resp) + return False + except Exception as exc: + logger.warning("Matrix: invite error: %s", exc) + return False + + # ------------------------------------------------------------------ + # Presence + # ------------------------------------------------------------------ + + _VALID_PRESENCE_STATES = frozenset(("online", "offline", "unavailable")) + + async def set_presence(self, state: str = "online", status_msg: str = "") -> bool: + """Set the bot's presence status.""" + if not self._client: + return False + if state not in self._VALID_PRESENCE_STATES: + logger.warning("Matrix: invalid presence state %r", state) + return False + try: + if hasattr(self._client, "set_presence"): + await self._client.set_presence(state, status_msg=status_msg or None) + logger.debug("Matrix: presence set to %s", state) + return True + except Exception as exc: + logger.debug("Matrix: set_presence failed: %s", exc) + return False + + # ------------------------------------------------------------------ + # Emote & notice message types + # ------------------------------------------------------------------ + + async def send_emote( + self, chat_id: str, text: str, metadata: Optional[Dict[str, Any]] = None, + ) -> SendResult: + """Send an emote message (/me style action).""" + import nio + + if not self._client or not text: + return SendResult(success=False, error="No client or empty text") + + msg_content: Dict[str, Any] = { + "msgtype": "m.emote", + "body": text, + } + html = self._markdown_to_html(text) + if html and html != text: + msg_content["format"] = "org.matrix.custom.html" + msg_content["formatted_body"] = html + + try: + resp = await self._client.room_send( + chat_id, "m.room.message", msg_content, + ignore_unverified_devices=True, + ) + if isinstance(resp, nio.RoomSendResponse): + return SendResult(success=True, message_id=resp.event_id) + return SendResult(success=False, error=str(resp)) + except Exception as exc: + return SendResult(success=False, error=str(exc)) + + async def send_notice( + self, chat_id: str, text: str, metadata: Optional[Dict[str, Any]] = None, + ) -> SendResult: + """Send a notice message (bot-appropriate, non-alerting).""" + import nio + + if not self._client or not text: + return SendResult(success=False, error="No client or empty text") + + msg_content: Dict[str, Any] = { + "msgtype": "m.notice", + "body": text, + } + html = self._markdown_to_html(text) + if html and html != text: + msg_content["format"] = "org.matrix.custom.html" + msg_content["formatted_body"] = html + + try: + resp = await self._client.room_send( + chat_id, "m.room.message", msg_content, + ignore_unverified_devices=True, + ) + if isinstance(resp, nio.RoomSendResponse): + return SendResult(success=True, message_id=resp.event_id) + return SendResult(success=False, error=str(resp)) + except Exception as exc: + return SendResult(success=False, error=str(exc)) + # ------------------------------------------------------------------ # Helpers # ------------------------------------------------------------------ @@ -1406,29 +1791,196 @@ class MatrixAdapter(BasePlatformAdapter): return f"{self._homeserver}/_matrix/client/v1/media/download/{parts}" def _markdown_to_html(self, text: str) -> str: - """Convert Markdown to Matrix-compatible HTML. + """Convert Markdown to Matrix-compatible HTML (org.matrix.custom.html). - Uses a simple conversion for common patterns. For full fidelity - a markdown-it style library could be used, but this covers the - common cases without an extra dependency. + Uses the ``markdown`` library when available (installed with the + ``matrix`` extra). Falls back to a comprehensive regex converter + that handles fenced code blocks, inline code, headers, bold, + italic, strikethrough, links, blockquotes, lists, and horizontal + rules — everything the Matrix HTML spec allows. """ try: - import markdown - html = markdown.markdown( - text, - extensions=["fenced_code", "tables", "nl2br"], + import markdown as _md + + md = _md.Markdown( + extensions=["fenced_code", "tables", "nl2br", "sane_lists"], ) - # Strip wrapping

tags for single-paragraph messages. + # Remove the raw HTML preprocessor so ") + assert "") + assert "") + assert "") + assert "*") + assert "\n```') + assert "<script>" in result + assert "