mindroom 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

mindroom/matrix/mentions.py

@@ -0,0 +1,141 @@
+"""Matrix mention utilities."""
+
+import re
+from typing import Any
+
+from mindroom.config import Config
+
+from .client import markdown_to_html
+from .identity import MatrixID
+from .message_builder import build_message_content
+
+
+def parse_mentions_in_text(text: str, sender_domain: str, config: Config) -> tuple[str, list[str], str]:
+    """Parse text for agent mentions and return processed text with user IDs.
+
+    Args:
+        text: Text that may contain @agent_name mentions
+        sender_domain: Domain part of the sender's user ID (e.g., "localhost" from "@user:localhost")
+        config: Application configuration
+
+    Returns:
+        Tuple of (plain_text, list_of_mentioned_user_ids, markdown_text_with_links)
+
+    """
+    # Pattern to match @agent_name (with optional @mindroom_ prefix or domain)
+    # Matches: @calculator, @mindroom_calculator, @mindroom_calculator:localhost
+    pattern = r"@(mindroom_)?(\w+)(?::[^\s]+)?"
+
+    # Find all mentions and process them
+    mentions_data = []
+    for match in re.finditer(pattern, text):
+        mention_info = _process_mention(match, config, sender_domain)
+        if mention_info:
+            mentions_data.append(mention_info)
+
+    # Build outputs from collected data
+    plain_text = text
+    markdown_text = text
+    mentioned_user_ids: list[str] = []
+
+    # Apply replacements (reverse order to preserve positions)
+    for original, user_id, display_name in reversed(mentions_data):
+        # Plain text: replace with full Matrix ID
+        plain_text = plain_text.replace(original, user_id, 1)
+
+        # Markdown: replace with clickable link
+        link = f"[@{display_name}](https://matrix.to/#/{user_id})"
+        markdown_text = markdown_text.replace(original, link, 1)
+
+        # Collect unique user IDs
+        if user_id not in mentioned_user_ids:
+            mentioned_user_ids.insert(0, user_id)  # Insert at start to maintain order
+
+    return plain_text, mentioned_user_ids, markdown_text
+
+
+def _process_mention(match: re.Match, config: Config, sender_domain: str) -> tuple[str, str, str] | None:
+    """Process a single mention match and return replacement data.
+
+    Args:
+        match: The regex match object
+        config: The loaded config
+        sender_domain: Domain for constructing Matrix IDs
+
+    Returns:
+        Tuple of (original_text, matrix_user_id, display_name) or None if not a valid agent
+
+    """
+    original = match.group(0)
+    prefix = match.group(1) or ""  # "mindroom_" or empty
+    name = match.group(2)
+
+    # Skip user mentions (mindroom_user_*)
+    if name.startswith("user_"):
+        return None
+
+    # Try to find the agent (case-insensitive)
+    agent_name = None
+    name_lower = name.lower()
+
+    # Check for direct match (case-insensitive)
+    for config_agent_name in config.agents:
+        if config_agent_name.lower() == name_lower:
+            agent_name = config_agent_name
+            break
+
+    # If not found, try with mindroom_ prefix removed
+    if not agent_name and prefix:
+        name_without_prefix = name.replace("mindroom_", "")
+        name_without_prefix_lower = name_without_prefix.lower()
+        for config_agent_name in config.agents:
+            if config_agent_name.lower() == name_without_prefix_lower:
+                agent_name = config_agent_name
+                break
+
+    if agent_name:
+        agent_config = config.agents[agent_name]
+        user_id = MatrixID.from_agent(agent_name, sender_domain).full_id
+        return (original, user_id, agent_config.display_name)
+
+    return None
+
+
+def format_message_with_mentions(
+    config: Config,
+    text: str,
+    sender_domain: str = "localhost",
+    thread_event_id: str | None = None,
+    reply_to_event_id: str | None = None,
+    latest_thread_event_id: str | None = None,
+) -> dict[str, Any]:
+    """Parse text for mentions and create properly formatted Matrix message.
+
+    This is the universal function that should be used everywhere.
+
+    Args:
+        config: Application configuration
+        text: Message text that may contain @agent_name mentions
+        sender_domain: Domain part of the sender's user ID
+        thread_event_id: Optional thread root event ID
+        reply_to_event_id: Optional event ID to reply to (for genuine replies)
+        latest_thread_event_id: Optional latest event ID in thread (for fallback compatibility)
+
+    Returns:
+        Properly formatted content dict for room_send
+
+    """
+    plain_text, mentioned_user_ids, markdown_text = parse_mentions_in_text(text, sender_domain, config)
+
+    # Convert markdown (with links) to HTML
+    # The markdown converter will properly handle the [@DisplayName](url) format
+    formatted_html = markdown_to_html(markdown_text)
+
+    return build_message_content(
+        body=plain_text,
+        formatted_body=formatted_html,
+        mentioned_user_ids=mentioned_user_ids,
+        thread_event_id=thread_event_id,
+        reply_to_event_id=reply_to_event_id,
+        latest_thread_event_id=latest_thread_event_id,
+    )

mindroom/matrix/message_builder.py

@@ -0,0 +1,94 @@
+"""Matrix message content builder with proper threading support."""
+
+from typing import Any
+
+from .client import markdown_to_html
+
+
+def build_thread_relation(
+    thread_event_id: str,
+    reply_to_event_id: str | None = None,
+    latest_thread_event_id: str | None = None,
+) -> dict[str, Any]:
+    """Build the m.relates_to structure for thread messages per MSC3440.
+
+    Args:
+        thread_event_id: The thread root event ID
+        reply_to_event_id: Optional event ID for genuine replies within thread
+        latest_thread_event_id: Latest event in thread (required for fallback if no reply_to)
+
+    Returns:
+        The m.relates_to structure for the message content
+
+    """
+    if reply_to_event_id:
+        # Genuine reply to a specific message in the thread
+        return {
+            "rel_type": "m.thread",
+            "event_id": thread_event_id,
+            "is_falling_back": False,
+            "m.in_reply_to": {"event_id": reply_to_event_id},
+        }
+    # Fallback: continuing thread without specific reply
+    # Per MSC3440, should point to latest message in thread for backwards compatibility
+    assert latest_thread_event_id is not None, "latest_thread_event_id is required for thread fallback"
+    return {
+        "rel_type": "m.thread",
+        "event_id": thread_event_id,
+        "is_falling_back": True,
+        "m.in_reply_to": {"event_id": latest_thread_event_id},
+    }
+
+
+def build_message_content(
+    body: str,
+    formatted_body: str | None = None,
+    mentioned_user_ids: list[str] | None = None,
+    thread_event_id: str | None = None,
+    reply_to_event_id: str | None = None,
+    latest_thread_event_id: str | None = None,
+) -> dict[str, Any]:
+    """Build a complete Matrix message content dictionary.
+
+    This handles all the Matrix protocol requirements for messages including:
+    - Basic message structure
+    - HTML formatting
+    - User mentions
+    - Thread relations (MSC3440 compliant)
+    - Reply relations
+
+    Args:
+        body: The plain text message body
+        formatted_body: Optional HTML formatted body (if not provided, converts from markdown)
+        mentioned_user_ids: Optional list of Matrix user IDs to mention
+        thread_event_id: Optional thread root event ID
+        reply_to_event_id: Optional event ID to reply to
+        latest_thread_event_id: Optional latest event in thread (for MSC3440 fallback)
+
+    Returns:
+        Complete content dictionary ready for room_send
+
+    """
+    content: dict[str, Any] = {
+        "msgtype": "m.text",
+        "body": body,
+        "format": "org.matrix.custom.html",
+        "formatted_body": formatted_body if formatted_body else markdown_to_html(body),
+    }
+
+    # Add mentions if any
+    if mentioned_user_ids:
+        content["m.mentions"] = {"user_ids": mentioned_user_ids}
+
+    # Add thread/reply relationship if specified
+    if thread_event_id:
+        content["m.relates_to"] = build_thread_relation(
+            thread_event_id=thread_event_id,
+            reply_to_event_id=reply_to_event_id,
+            latest_thread_event_id=latest_thread_event_id,
+        )
+    elif reply_to_event_id:
+        # Plain reply without thread (shouldn't happen in this bot)
+        content["m.relates_to"] = {"m.in_reply_to": {"event_id": reply_to_event_id}}
+
+    return content

mindroom/matrix/message_content.py

@@ -0,0 +1,209 @@
+"""Centralized message content extraction with large message support.
+
+This module provides utilities to extract the full content from Matrix messages,
+including handling large messages that are stored as MXC attachments.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import nio
+from nio import crypto
+
+from mindroom.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# MXC download cache - stores (content, timestamp) tuples
+# Key: mxc_url, Value: (content, timestamp)
+_mxc_cache: dict[str, tuple[str, float]] = {}
+_cache_ttl = 3600.0  # 1 hour TTL
+
+
+async def _get_full_message_body(
+    message_data: dict[str, Any],
+    client: nio.AsyncClient | None = None,
+) -> str:
+    """Extract the full message body, handling large message attachments.
+
+    For regular messages, returns the body directly.
+    For large messages with attachments, downloads and returns the full content.
+
+    Args:
+        message_data: Dict with message data including 'body' and 'content' keys
+        client: Optional Matrix client for downloading attachments
+
+    Returns:
+        The full message body text
+
+    """
+    content = message_data.get("content", {})
+    body = str(message_data.get("body", ""))
+
+    # Check if this is a large message with our custom metadata
+    if "io.mindroom.long_text" in content:
+        # This is a large message - need to fetch the attachment
+        if not client:
+            logger.warning("Cannot fetch large message attachment without client, returning preview")
+            return body
+
+        # Get the MXC URL from either 'url' (unencrypted) or 'file' (encrypted)
+        mxc_url = None
+        if "url" in content:
+            mxc_url = content["url"]
+        elif "file" in content:
+            file_info = content["file"]
+            mxc_url = file_info.get("url")
+
+        if not mxc_url:
+            logger.warning("Large message missing MXC URL, returning preview")
+            return body
+
+        # Download the full content
+        full_text = await _download_mxc_text(client, mxc_url, content.get("file"))
+        if full_text:
+            return full_text
+        logger.warning("Failed to download large message, returning preview")
+        return body
+
+    # Regular message or no custom metadata
+    return body
+
+
+async def _download_mxc_text(  # noqa: PLR0911, C901
+    client: nio.AsyncClient,
+    mxc_url: str,
+    file_info: dict[str, Any] | None = None,
+) -> str | None:
+    """Download text content from an MXC URL with caching.
+
+    Args:
+        client: Matrix client
+        mxc_url: The MXC URL to download from
+        file_info: Optional encryption info for E2EE rooms
+
+    Returns:
+        The downloaded text content, or None if download failed
+
+    """
+    # Check cache first
+    current_time = time.time()
+    if mxc_url in _mxc_cache:
+        content, timestamp = _mxc_cache[mxc_url]
+        if current_time - timestamp < _cache_ttl:
+            logger.debug(f"Cache hit for MXC URL: {mxc_url}")
+            return content
+        # Expired, remove from cache
+        del _mxc_cache[mxc_url]
+
+    try:
+        # Parse MXC URL
+        if not mxc_url.startswith("mxc://"):
+            logger.error(f"Invalid MXC URL: {mxc_url}")
+            return None
+
+        # Extract server and media ID
+        parts = mxc_url[6:].split("/", 1)
+        if len(parts) != 2:
+            logger.error(f"Invalid MXC URL format: {mxc_url}")
+            return None
+
+        server_name, media_id = parts
+
+        # Download the content
+        response = await client.download(server_name, media_id)
+
+        if not isinstance(response, nio.DownloadResponse):
+            logger.error(f"Failed to download MXC content: {response}")
+            return None
+
+        # Handle encryption if needed
+        if file_info and "key" in file_info:
+            # Decrypt the content
+            try:
+                decrypted = crypto.attachments.decrypt_attachment(
+                    response.body,
+                    file_info["key"],
+                    file_info["hashes"]["sha256"],
+                    file_info["iv"],
+                )
+                text_bytes = decrypted
+            except Exception:
+                logger.exception("Failed to decrypt attachment")
+                return None
+        else:
+            text_bytes = response.body
+
+        # Decode to text
+        try:
+            decoded_text: str = text_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            logger.exception("Downloaded content is not valid UTF-8 text")
+            return None
+
+        else:
+            # Cache the result
+            _mxc_cache[mxc_url] = (decoded_text, time.time())
+            logger.debug(f"Cached MXC content for: {mxc_url}")
+
+            # Clean old entries if cache is getting large
+            if len(_mxc_cache) > 100:
+                _clean_expired_cache()
+
+            return decoded_text
+
+    except Exception:
+        logger.exception("Error downloading MXC content")
+        return None
+
+
+async def extract_and_resolve_message(
+    event: nio.RoomMessageText,
+    client: nio.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """Extract message data and resolve large message content if needed.
+
+    This is a convenience function that combines extraction and resolution
+    of large message content in a single call.
+
+    Args:
+        event: The Matrix event to extract data from
+        client: Optional Matrix client for downloading attachments
+
+    Returns:
+        Dict with sender, body, timestamp, event_id, and content fields.
+        If the message is large and client is provided, body will contain
+        the full text from the attachment.
+
+    """
+    # Extract basic message data
+    data = {
+        "sender": event.sender,
+        "body": event.body,
+        "timestamp": event.server_timestamp,
+        "event_id": event.event_id,
+        "content": event.source.get("content", {}),
+    }
+
+    # Check if this is a large message and resolve if we have a client
+    if client and "io.mindroom.long_text" in data["content"]:
+        data["body"] = await _get_full_message_body(data, client)
+
+    return data
+
+
+def _clean_expired_cache() -> None:
+    """Remove expired entries from the MXC cache."""
+    current_time = time.time()
+    expired_keys = [key for key, (_, timestamp) in _mxc_cache.items() if current_time - timestamp >= _cache_ttl]
+    for key in expired_keys:
+        del _mxc_cache[key]
+    if expired_keys:
+        logger.debug(f"Cleaned {len(expired_keys)} expired cache entries")
+
+
+def clear_mxc_cache() -> None:
+    """Clear the entire MXC cache. Useful for testing."""
+    _mxc_cache.clear()

mindroom/matrix/presence.py

@@ -0,0 +1,178 @@
+"""Matrix presence and status message utilities."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import nio
+
+from mindroom.constants import ENABLE_STREAMING, ROUTER_AGENT_NAME
+from mindroom.logging_config import get_logger
+
+if TYPE_CHECKING:
+    from mindroom.config import Config
+
+logger = get_logger(__name__)
+
+
+async def set_presence_status(
+    client: nio.AsyncClient,
+    status_msg: str,
+    presence: str = "online",
+) -> None:
+    """Set presence status for a Matrix user.
+
+    Args:
+        client: The Matrix client
+        status_msg: The status message to display
+        presence: The presence state (online, offline, unavailable)
+
+    """
+    response = await client.set_presence(presence, status_msg)
+
+    if isinstance(response, nio.PresenceSetResponse):
+        logger.info(f"Set presence status: {status_msg}")
+    else:
+        logger.warning(f"Failed to set presence: {response}")
+
+
+def build_agent_status_message(
+    agent_name: str,
+    config: Config,
+) -> str:
+    """Build status message with model and role information for an agent.
+
+    Args:
+        agent_name: Name of the agent
+        config: Application configuration
+
+    Returns:
+        Status message string, limited to 250 characters
+
+    """
+    status_parts = []
+
+    # Get model name using the config method
+    model_name = config.get_entity_model_name(agent_name)
+
+    # Format model info
+    if model_name in config.models:
+        model_config = config.models[model_name]
+        model_info = f"{model_config.provider}/{model_config.id}"
+    else:
+        model_info = model_name
+
+    status_parts.append(f"🤖 Model: {model_info}")
+
+    # Add role/purpose for teams and agents
+    if agent_name == ROUTER_AGENT_NAME:
+        status_parts.append("📍 Routes messages to appropriate agents")
+    elif agent_name in config.teams:
+        team_config = config.teams[agent_name]
+        if team_config.role:
+            status_parts.append(f"👥 {team_config.role[:100]}")  # Limit length
+        status_parts.append(f"🤝 Team: {', '.join(team_config.agents[:5])}")  # Show first 5 agents
+    elif agent_name in config.agents:
+        agent_config = config.agents[agent_name]
+        if agent_config.role:
+            status_parts.append(f"💼 {agent_config.role[:100]}")  # Limit length
+        # Add tool count
+        if agent_config.tools:
+            status_parts.append(f"🔧 {len(agent_config.tools)} tools available")
+
+    # Join all parts with separators
+    return " | ".join(status_parts)
+
+
+async def is_user_online(
+    client: nio.AsyncClient,
+    user_id: str,
+) -> bool:
+    """Check if a Matrix user is currently online.
+
+    Args:
+        client: The Matrix client to use for the presence check
+        user_id: The Matrix user ID string (e.g., "@user:example.com")
+
+    Returns:
+        True if the user is online or unavailable (active but busy),
+        False if offline or presence check fails
+
+    """
+    try:
+        response = await client.get_presence(user_id)
+
+        # Check if we got an error response
+        if isinstance(response, nio.PresenceGetError):
+            logger.warning(
+                "Presence API error",
+                user_id=user_id,
+                error=response.message,
+            )
+            return False
+
+        # Presence states: "online", "unavailable" (busy/idle), "offline"
+        # We consider both "online" and "unavailable" as "online" for streaming purposes
+        # since "unavailable" usually means the user is idle but still has the client open
+        is_online = response.presence in ("online", "unavailable")
+
+        logger.debug(
+            "User presence check",
+            user_id=user_id,
+            presence=response.presence,
+            is_online=is_online,
+            last_active_ago=response.last_active_ago,
+        )
+
+        return is_online  # noqa: TRY300
+
+    except Exception:
+        logger.exception(
+            "Error checking user presence",
+            user_id=user_id,
+        )
+        # Default to non-streaming on error (safer)
+        return False
+
+
+async def should_use_streaming(
+    client: nio.AsyncClient,
+    room_id: str,
+    requester_user_id: str | None = None,
+) -> bool:
+    """Determine if streaming should be used based on user presence.
+
+    This checks if the human user who sent the message is online.
+    If they are online, we use streaming (message editing) for real-time updates.
+    If they are offline, we send the complete message at once to save API calls.
+
+    Args:
+        client: The Matrix client
+        room_id: The room where the interaction is happening
+        requester_user_id: The user who sent the message (optional)
+
+    Returns:
+        True if streaming should be used, False otherwise
+
+    """
+    # Check if streaming is globally disabled
+    if not ENABLE_STREAMING:
+        return False
+
+    # If no requester specified, we can't check presence, default to streaming
+    if not requester_user_id:
+        logger.debug("No requester specified, defaulting to streaming")
+        return True
+
+    # Check if the requester is online
+    is_online = await is_user_online(client, requester_user_id)
+
+    logger.info(
+        "Streaming decision",
+        room_id=room_id,
+        requester=requester_user_id,
+        is_online=is_online,
+        use_streaming=is_online,
+    )
+
+    return is_online