Skip to content

netresearch/matrix-skill / skills/matrix-communication

matrix-communication

Flagged

Use when communicating via Matrix chat, notifying teams, or managing E2EE. Triggers on #room:server references, Matrix URLs, and chat requests.

FileKindSize
README.mdmarkdown2.9 KB
SKILL.mdskill md6.7 KB
evals/evals.jsonconfig12.6 KB
references/agent-governance.mdmarkdown2.0 KB
references/api-reference.mdmarkdown7.3 KB
references/command-reference.mdmarkdown8.9 KB
references/e2ee-guide.mdmarkdown17.2 KB
references/hookshot-integration.mdmarkdown10.7 KB
references/messaging-guide.mdmarkdown13.8 KB
references/no-editorializing.mdmarkdown331 B
references/setup-guide.mdmarkdown11.1 KB
references/troubleshooting.mdmarkdown7.8 KB
scripts/_lib/__init__.pyscript3.6 KB
scripts/_lib/backup_mac.pyscript1.2 KB
scripts/_lib/config.pyscript4.6 KB
scripts/_lib/daemon_client.pyscript3.0 KB
scripts/_lib/deps.pyscript1.9 KB
scripts/_lib/downloads.pyscript1.1 KB
scripts/_lib/e2ee.pyscript13.2 KB
scripts/_lib/formatting.pyscript14.4 KB
scripts/_lib/http.pyscript4.8 KB
scripts/_lib/reactions.pyscript2.9 KB
scripts/_lib/roomlog.pyscript13.7 KB
scripts/_lib/rooms.pyscript15.5 KB
scripts/_lib/secret_input.pyscript2.0 KB
scripts/_lib/test_backup_mac.pyscript1.5 KB
scripts/_lib/test_config.pyscript7.1 KB
scripts/_lib/test_daemon_client.pyscript5.9 KB
scripts/_lib/test_downloads.pyscript2.3 KB
scripts/_lib/test_e2ee.pyscript14.3 KB
scripts/_lib/test_formatting.pyscript15.5 KB
scripts/_lib/test_http.pyscript4.1 KB
scripts/_lib/test_reactions.pyscript15.2 KB
scripts/_lib/test_roomlog.pyscript20.2 KB
scripts/_lib/test_rooms.pyscript13.7 KB
scripts/_lib/test_secret_input.pyscript2.2 KB
scripts/_lib/test_trust.pyscript8.3 KB
scripts/_lib/trust.pyscript5.3 KB
scripts/_lib/utils.pyscript1.7 KB
scripts/matrix-create-room.pyexecutablescript4.7 KB
scripts/matrix-doctor.pyexecutablescript22.2 KB
scripts/matrix-download-e2ee.pyexecutablescript7.7 KB
scripts/matrix-e2ee-setup.pyexecutablescript9.2 KB
scripts/matrix-e2ee-verify.pyexecutablescript29.2 KB
scripts/matrix-edit-e2ee.pyexecutablescript7.9 KB
scripts/matrix-edit.pyexecutablescript5.3 KB
scripts/matrix-fetch-keys.pyexecutablescript9.1 KB
scripts/matrix-invite.pyexecutablescript3.0 KB
scripts/matrix-key-backup.pyexecutablescript21.3 KB
scripts/matrix-power-level.pyexecutablescript7.0 KB
scripts/matrix-react.pyexecutablescript14.1 KB
scripts/matrix-read-e2ee.pyexecutablescript12.8 KB
scripts/matrix-read.pyexecutablescript4.7 KB
scripts/matrix-redact.pyexecutablescript5.0 KB
scripts/matrix-resolve.pyexecutablescript1.7 KB
scripts/matrix-rooms.pyexecutablescript3.8 KB
scripts/matrix-send-e2ee.pyexecutablescript19.4 KB
scripts/matrix-send.pyexecutablescript9.4 KB
scripts/matrix-watch.pyexecutablescript5.3 KB
scripts/matrix-watchd.pyexecutablescript23.5 KB
scripts/test_matrix_doctor.pyscript14.2 KB
scripts/test_matrix_read_e2ee.pyscript2.7 KB

scripts/_lib/rooms.py

View on GitHub
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH

"""Room operations for Matrix scripts.

All functions use ONLY stdlib.
"""

import json
import sys
import urllib.parse
from collections import Counter

from _lib.formatting import MATRIX_TO
from _lib.http import matrix_request, path_segment

# nio's MatrixRoom.group_name() lists at most this many members by name.
GROUP_NAME_HEROES = 5


def normalize_room_input(room_input: str) -> str:
    """Turn a matrix.to permalink into the room ID or alias it points at.

    Element's "Copy link" gives `https://matrix.to/#/!room:server?via=...`,
    `https://matrix.to/#/#alias:server`, or for a message
    `https://matrix.to/#/!room:server/$event?via=...`, sometimes
    percent-encoded. The room part is returned decoded; the event part and
    the query are dropped. Anything that is not such a link is returned
    unchanged.
    """
    if not room_input.startswith(MATRIX_TO):
        return room_input
    target = room_input[len(MATRIX_TO) :].split("?", 1)[0].split("/", 1)[0]
    return urllib.parse.unquote(target)


def group_name(names: list[str]) -> str:
    """Name a room without m.room.name or alias after its members.

    Same wording as matrix-nio's MatrixRoom.group_name(), so the HTTP path
    and the nio path give a direct chat the same name: the other person's
    display name, "A and B", "A, B and 3 others", or "Empty Room".
    """
    names = sorted(names, key=str.lower)
    shown = names[:GROUP_NAME_HEROES]
    others = len(names) - len(shown)
    if not shown:
        return "Empty Room"
    if others:
        return f"{', '.join(shown)} and {others} other{'' if others == 1 else 's'}"
    if len(shown) == 1:
        return shown[0]
    return f"{', '.join(shown[:-1])} and {shown[-1]}"


def get_room_members(config: dict, room_id: str) -> dict | None:
    """Return the joined and invited members of a room except this account.

    One request. Invited members count because a direct chat whose partner
    has not accepted yet is still the chat with that person - nio's
    room.users holds them too. A display name that two members share, this
    account included, becomes "Name (@user:server)", as nio's user_name()
    and the spec's room-name rules have it.

    Returns:
        Dict of user ID -> display name (the user ID when none is set),
        or None when the server refused the request
    """
    result = matrix_request(
        config,
        "GET",
        f"/rooms/{path_segment(room_id)}/members?not_membership=leave",
    )
    if "error" in result:
        return None
    display_names = {}
    for event in result.get("chunk", []):
        user_id = event.get("state_key")
        content = event.get("content", {})
        if not user_id or content.get("membership") not in ("join", "invite"):
            continue
        display_names[user_id] = content.get("displayname")
    taken = Counter(name or user_id for user_id, name in display_names.items())
    members = {}
    for user_id, name in display_names.items():
        if user_id == config.get("user_id"):
            continue
        if name and taken[name] > 1:
            name = f"{name} ({user_id})"
        members[user_id] = name or user_id
    return members


def room_matches(room: dict, search_lower: str, exact: bool = False) -> bool:
    """Whether a room dict from list_joined_rooms() matches a search term.

    Matches the room name, the alias, and - for a room named after its
    members - the members' user IDs, so `@jane:server` finds the direct
    chat with Jane. Named rooms carry no member list and match as before.
    """
    members = [m.lower() for m in room.get("members", [])]
    if exact:
        return room["name"].lower() == search_lower or search_lower in members
    return (
        search_lower in room["name"].lower()
        or search_lower in (room.get("alias") or "").lower()
        or any(search_lower in m for m in members)
    )


def resolve_room_alias(config: dict, alias: str) -> str:
    """Resolve a room alias to room ID.

    Args:
        config: Matrix config with homeserver and access_token
        alias: Room alias (e.g., #room:server)

    Returns:
        Room ID (e.g., !abc123:server)

    Raises:
        ValueError if alias cannot be resolved
    """
    encoded_alias = urllib.parse.quote(alias, safe="")
    result = matrix_request(config, "GET", f"/directory/room/{encoded_alias}")
    if "room_id" in result:
        return result["room_id"]
    raise ValueError(
        f"Could not resolve room alias: {result.get('error', 'Unknown error')}"
    )


def get_room_info(config: dict, room_id: str) -> dict:
    """Get the display name and canonical alias of a room.

    Args:
        config: Matrix config with homeserver and access_token
        room_id: Room ID to query

    Returns:
        Dict with 'name' and 'alias' keys (values may be None)
    """
    info = {"name": None, "alias": None}

    result = matrix_request(
        config, "GET", f"/rooms/{path_segment(room_id)}/state/m.room.name"
    )
    if "name" in result:
        info["name"] = result["name"]

    result = matrix_request(
        config, "GET", f"/rooms/{path_segment(room_id)}/state/m.room.canonical_alias"
    )
    if "alias" in result:
        info["alias"] = result["alias"]

    return info


def list_joined_rooms(config: dict) -> list:
    """List all joined rooms with names and aliases.

    A room with neither m.room.name nor an alias - a direct chat, usually -
    is named after its members the way Element and nio name it, which costs
    one more request for each such room.

    Args:
        config: Matrix config with homeserver and access_token

    Returns:
        List of dicts with room_id, name, and alias keys; a room named after
        its members also has `members`, the user IDs it was named from
    """
    result = matrix_request(config, "GET", "/joined_rooms")
    if "error" in result:
        return []

    rooms = []
    for room_id in result.get("joined_rooms", []):
        info = get_room_info(config, room_id)
        room = {
            "room_id": room_id,
            "name": info["name"] or info["alias"],
            "alias": info["alias"],
        }
        if not room["name"]:
            members = get_room_members(config, room_id)
            if members is None:
                # Members unreadable: keep the bare ID rather than call a
                # room with people in it "Empty Room".
                room["name"] = room_id
            else:
                room["name"] = group_name(list(members.values()))
                room["members"] = sorted(members)
        rooms.append(room)

    return rooms


def find_room_by_name(config: dict, search_term: str) -> tuple[str | None, list]:
    """Find a room by name or alias (case-insensitive).

    Match priority:
    1. Exact alias match (#room:server)
    2. Exact alias name match (without server part, e.g. "agent-work")
    3. Exact room name match (rooms with aliases preferred)
    4. Single partial match on name or alias

    When an exact name match has no alias but other rooms also have names
    containing the search term, all candidates are returned for disambiguation.

    Args:
        config: Matrix config with homeserver and access_token
        search_term: Search term to match against room names/aliases

    Returns:
        (room_id, matches) where:
        - room_id is the matched room ID (or None if no/ambiguous match)
        - matches is list of matching rooms (for error reporting)
    """
    rooms = list_joined_rooms(config)
    search_lower = search_term.lower()

    # Try exact alias match (most specific)
    for room in rooms:
        if room.get("alias") and room["alias"].lower() == search_lower:
            return room["room_id"], [room]

    # Try exact alias name match (without server part)
    for room in rooms:
        if room.get("alias"):
            alias_name = room["alias"].split(":")[0].lstrip("#")
            if alias_name.lower() == search_lower:
                return room["room_id"], [room]

    # Try exact name match (for a room named after its members, also a
    # member's user ID)
    name_matches = [r for r in rooms if room_matches(r, search_lower, exact=True)]
    if len(name_matches) == 1:
        room = name_matches[0]
        if room.get("alias"):
            # Room has an alias — well-identified, return directly
            return room["room_id"], name_matches
        # Room has no alias — check if other rooms have names containing
        # the search term, which suggests the user may want a different room.
        # Only names someone gave a room count here: a name made up from
        # members ("Jane Doe and Max") is not a competing room name, and
        # before such names existed these rooms never competed either.
        alternatives = [
            r
            for r in rooms
            if r not in name_matches
            and "members" not in r
            and search_lower in r["name"].lower()
        ]
        if alternatives:
            return None, name_matches + alternatives
        return room["room_id"], name_matches
    if len(name_matches) > 1:
        return None, name_matches

    # Try partial match
    matches = [r for r in rooms if room_matches(r, search_lower)]

    if len(matches) == 1:
        return matches[0]["room_id"], matches

    return None, matches


def find_room_in_nio_client(client_rooms: dict, search_term: str) -> str | None:
    """Find a room by name in a matrix-nio client.rooms dict (post-sync).

    This avoids the N+1 HTTP calls of find_room_by_name() by using
    room data already loaded by client.sync().

    Args:
        client_rooms: dict from AsyncClient.rooms (room_id -> MatrixRoom)
        search_term: Room name, alias, or ID to match

    Returns:
        room_id if found, None otherwise
    """
    search_lower = search_term.lower()

    def member_ids(room) -> list[str]:
        # Like list_joined_rooms(): only a room named after its members
        # matches on their user IDs; named rooms match as before.
        if room.name or room.canonical_alias:
            return []
        own = getattr(room, "own_user_id", None)
        return [u.lower() for u in room.users if u != own]

    # Exact alias match
    for room_id, room in client_rooms.items():
        if room.canonical_alias and room.canonical_alias.lower() == search_lower:
            return room_id

    # Alias name match (without server part)
    for room_id, room in client_rooms.items():
        if room.canonical_alias:
            alias_name = room.canonical_alias.split(":")[0].lstrip("#")
            if alias_name.lower() == search_lower:
                return room_id

    # Exact display name match (for a room named after its members, also a
    # member's user ID)
    exact_matches = [
        room_id
        for room_id, room in client_rooms.items()
        if (room.display_name and room.display_name.lower() == search_lower)
        or search_lower in member_ids(room)
    ]
    if len(exact_matches) == 1:
        return exact_matches[0]
    if len(exact_matches) > 1:
        return None  # Ambiguous exact match

    # Partial name match
    partial_matches = [
        room_id
        for room_id, room in client_rooms.items()
        if search_lower in (room.display_name or "").lower()
        or search_lower in (room.canonical_alias or "").lower()
        or any(search_lower in u for u in member_ids(room))
    ]
    if len(partial_matches) == 1:
        return partial_matches[0]

    return None


def find_direct_room(config: dict, user_id: str) -> str:
    """Find the direct-message room shared with `user_id`.

    A name search finds a direct chat by the other person's name, but not
    when the chat has a name of its own or when the person shares unnamed
    rooms with this account besides it. The account data `m.direct` maps
    each user to the rooms marked as direct with them; it still lists rooms
    either side has left. A room counts only when this account is joined to
    it and `user_id` is joined or invited. Nothing is created: no usable
    room is an error.

    Args:
        config: Matrix config with homeserver, user_id and access_token
        user_id: Full Matrix ID of the other person (@user:server)

    Returns:
        Room ID of the single usable direct room

    Raises:
        ValueError if there is no usable direct room, or more than one
    """
    direct = matrix_request(
        config,
        "GET",
        f"/user/{path_segment(config['user_id'])}/account_data/m.direct",
    )
    if "error" in direct and direct.get("errcode") != "M_NOT_FOUND":
        raise ValueError(f"Could not read m.direct: {direct['error']}")
    listed = direct.get(user_id, [])
    if not listed:
        raise ValueError(f"No direct chat with {user_id} in m.direct")

    joined_rooms = matrix_request(config, "GET", "/joined_rooms")
    if "error" in joined_rooms:
        raise ValueError(f"Could not list joined rooms: {joined_rooms['error']}")
    joined = set(joined_rooms.get("joined_rooms", []))

    usable = []
    for room_id in listed:
        if room_id not in joined:
            continue
        member = matrix_request(
            config,
            "GET",
            f"/rooms/{path_segment(room_id)}/state/m.room.member/"
            f"{path_segment(user_id)}",
        )
        if member.get("membership") in ("join", "invite"):
            usable.append(room_id)

    if len(usable) == 1:
        return usable[0]
    if not usable:
        raise ValueError(
            f"No usable direct chat with {user_id}: m.direct lists "
            f"{', '.join(listed)}, but you or they have left each of them"
        )
    raise ValueError(
        f"Several direct chats with {user_id}: {', '.join(usable)}. "
        "Pass the room ID instead of --to"
    )


def resolve_room_cli(
    config: dict, room_input: str, json_out: bool = False, debug: bool = False
) -> str:
    """Resolve a ROOM CLI argument (ID, alias, name, or matrix.to link).

    Shared by scripts that take a ROOM positional argument, so each script
    doesn't reimplement the same ID/alias/name resolution order and error
    formatting. Prints a JSON or human-readable error and exits 1 if the
    room cannot be resolved — callers can assume a valid room ID is
    returned or the process has already ended.
    """
    room_input = normalize_room_input(room_input)
    if room_input.startswith("!"):
        if debug:
            print(f"Using room ID directly: {room_input}", file=sys.stderr)
        return room_input

    if room_input.startswith("#"):
        try:
            room_id = resolve_room_alias(config, room_input)
            if debug:
                print(f"Resolved alias {room_input} -> {room_id}", file=sys.stderr)
            return room_id
        except ValueError as e:
            if json_out:
                print(json.dumps({"error": str(e)}))
            else:
                print(f"Error: {e}", file=sys.stderr)
            raise SystemExit(1) from None

    found_id, matches = find_room_by_name(config, room_input)
    if found_id:
        if debug:
            print(f"Found room: {found_id}", file=sys.stderr)
        return found_id

    error_msg = f"Could not find room '{room_input}'"
    if matches:
        error_msg += ". Multiple matches found:\n"
        for m in matches:
            alias_str = f" ({m['alias']})" if m.get("alias") else ""
            error_msg += f"  - {m['name']}{alias_str}: {m['room_id']}\n"
    else:
        error_msg += ". Use 'matrix-rooms.py' to list available rooms."
    if json_out:
        print(json.dumps({"error": error_msg}))
    else:
        print(f"Error: {error_msg}", file=sys.stderr)
    raise SystemExit(1)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall