Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

21.7 KB
Raw Blame
"""Whether a message addresses a given agent, and whether it is allowed to.

Two separate questions, deliberately kept apart:

- **Addressed** is about intent. Did this message ask this agent for something
  — by name, by the alias it goes under in this room, by a role it holds, or
  by being the only agent in a direct chat (`auto_addressed_room`)?
- **Permitted** is about authority. An agent may carry a scoped addressing
  policy saying who is allowed to ask it for things at all.

A message can be addressed and not permitted, and the caller demotes it to
ordinary room chatter when so. Nothing here sends anything; deciding is all it
does, and the refusal wording travels back with the decision so the caller does
not have to re-derive why.

This used to live on the agent client, where every answer was reached through
a live Matrix client. It takes a message as data instead (a sender, a body, a
content dict), so the same rules decide for a message read out of the log as
for one that arrived on the bus, and for every agent in a room at once. That equivalence is the point: two code paths
answering "is this for me?" differently would be a security bug waiting for a
rewrite to expose it.
"""

from __future__ import annotations

import logging
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, NamedTuple

from switch_core.addressing import (
    SenderKind,
    allows_on_behalf_of,
    can_address,
    parse_policy,
)
from switch_core.chats import MEMBER_CLIENT_TYPE
from switch_core.clients.admin_messages import (
    ADMIN_MARKER,
    PLATFORM_MARKER,
    platform_on_behalf_of,
)
from switch_core.clients.mentions import mention_regex, strip_emphasis

if TYPE_CHECKING:
    from collections.abc import Callable

    from sqlalchemy.ext.asyncio import AsyncSession

    from switch_core.db.models import Agent
    from switch_core.db.stores.agent_store import AgentStore
    from switch_core.db.stores.client_store import ClientStore
    from switch_core.db.stores.external_user_store import ExternalUserStore
    from switch_core.db.stores.room_role_store import RoomRoleStore
    from switch_core.db.stores.room_store import RoomStore

logger = logging.getLogger(__name__)


def named_agents(
    names: Mapping[str, str], aliases: Mapping[str, str], body: str
) -> list[str]:
    """The ids of the agents `body` names by `@name` or room `@alias`, sorted.

    For display only: it reads no pill, role or room type, so it says who a
    message visibly names rather than who it addresses.
    """
    text = strip_emphasis(body)
    named = {
        agent_id
        for agent_id, name in names.items()
        if mention_regex(name).search(text) is not None
    }
    named.update(
        agent_id
        for agent_id, alias in aliases.items()
        if agent_id in names and mention_regex(alias).search(text) is not None
    )
    return sorted(named)


# Posted (once, guarded by an auto-reply flag) when a sender tags an agent but
# the agent's scoped addressing policy does not permit that sender to address
# it there. The message is demoted to unaddressed room chatter; this reply is
# the sender's only feedback that the attempt was rejected.
ADDRESSING_DENIED_MESSAGE = (
    "You're not permitted to direct messages to me in this room — my operator "
    "has restricted who can address me here."
)


# The same refusal, for the case worth telling apart: the agent answers only to
# its owner, and the sender's chat account is not linked to any Switch user, so
# it cannot be recognised as the owner even if it is. Without this the owner
# gets refused by their own agent with no idea why.
ADDRESSING_UNCLAIMED_MESSAGE = (
    "I only take instructions from my owner, and this chat account isn't "
    "linked to a Switch user yet — so I can't tell whether that's you. If it "
    "is, link this account to your Switch user in Switch Console, post the "
    "code it shows you from this account, and try again."
)


@dataclass(frozen=True)
class IncomingMessage:
    """What addressing needs to know about a message, and nothing else.

    `formatted_body` is where a rendered mention pill goes,
    which is the one addressing signal that has no plain-text equivalent. It is
    absent on media events and on anything read back from the log that never
    had one, so it is never the only thing consulted.
    """

    sender: str
    body: str
    formatted_body: str | None = None
    content: dict = field(default_factory=dict)

    @property
    def addressable_body(self) -> str:
        return addressable_text(self.body, self.content)


# Written by a Switch Console send: the people it names (`user_ids`), and the
# `@name` spans that name them (`person_names`), which no agent's name, alias
# or role may then match. A person sharing an agent's name would otherwise
# wake the agent; the content can only take addressing away, never add it.
MENTIONS_KEY = "com.switch.mentions"


def addressable_text(body: str, content: Mapping[str, object]) -> str:
    """`body` less the `@name` spans that name people (`MENTIONS_KEY`)."""
    text = strip_emphasis(body)
    mentions = content.get(MENTIONS_KEY)
    if not isinstance(mentions, dict):
        return text
    for name in mentions.get("person_names") or []:
        if isinstance(name, str) and name:
            text = mention_regex(name).sub("", text)
    return text


class AddressingDecision(NamedTuple):
    """Whether a sender may address an agent, and what to say if not."""

    allowed: bool
    refusal: str


class SenderPrincipal(NamedTuple):
    """Who a sender turned out to be, in the terms a policy is written in.

    `user_ids` and `owner_user_id` are the two ways a symbolic subject
    resolves, and are mutually exclusive: a human has claimants, an agent has
    an owner.
    """

    kind: SenderKind
    id: str
    user_ids: list[str]
    owner_user_id: str | None
    #: For a platform sender: the Switch user whose authority the message
    #: carries, read from the event's marker. None for the platform's own
    #: message and for every other kind.
    on_behalf_of: str | None = None


class AddressingResolver:
    """Answers "is this for that agent, and may it be?" from stores alone."""

    def __init__(
        self,
        *,
        room_store: RoomStore,
        room_role_store: RoomRoleStore,
        client_store: ClientStore,
        agent_store: AgentStore,
        external_user_store: ExternalUserStore,
        live_connection_ids: Callable[[], set[str]],
    ) -> None:
        self._room_store = room_store
        self._room_role_store = room_role_store
        self._client_store = client_store
        self._agent_store = agent_store
        self._external_user_store = external_user_store
        # A callable rather than a set: a role only routes while its holder is
        # live, and that changes between one message and the next.
        self._live_connection_ids = live_connection_ids

    # ── Addressed ─────────────────────────────────────────────────────────────

    def addressed_without_lookup(
        self,
        *,
        agent: Agent,
        agent_user_id: str,
        channel_type: str | None,
        agent_count: int | None,
        message: IncomingMessage,
    ) -> bool | None:
        """The addressing answer that needs no database read, or None when the
        room's aliases, role leases or (in a direct room whose `agent_count`
        the caller does not know) agent count have to be consulted.

        Callers use it to decide whether to take a pool slot at all: most room
        chatter carries no `@` and is answered here, and a room fans every
        message out to all of its agent clients at once.
        """
        if ADMIN_MARKER in message.content:
            return False
        if self.mentions_name(
            agent=agent, agent_user_id=agent_user_id, message=message
        ):
            return True
        if channel_type == "direct":
            if agent_count is None:
                return None
            if agent_count == 1:
                return True
        if "@" not in message.addressable_body:
            return False
        return None

    async def addresses(
        self,
        session: AsyncSession,
        *,
        agent: Agent,
        agent_user_id: str,
        room_id: str,
        channel_type: str | None,
        message: IncomingMessage,
    ) -> bool:
        """Whether this message asks this agent for something.

        **A system message never addresses anyone**, whatever the room type.
        Switch's own notices — a command's answer, "Added X to this room", the
        guidance shown when someone tags the app itself — are output, not a
        request for a reply. Two ways they were read as one: in a one-agent
        direct room every message addresses the agent, so running `/list-agents` in a 1:1
        chat had the agent start a session to respond to its own roster; and in
        any room, a notice that lists the agents present writes each `@name`,
        which tagged every one of them. The marker exists to say "generated by
        Switch"; this is it being honoured.
        """
        decided = self.addressed_without_lookup(
            agent=agent,
            agent_user_id=agent_user_id,
            channel_type=channel_type,
            agent_count=None,
            message=message,
        )
        if decided is not None:
            return decided
        if await self.auto_addressed_room(
            session, room_id=room_id, channel_type=channel_type
        ):
            return True
        if await self.mentions_alias(
            session, agent=agent, room_id=room_id, message=message
        ):
            return True
        return await self.mentions_role(
            session, agent=agent, room_id=room_id, message=message
        )

    async def auto_addressed_room(
        self, session: AsyncSession, *, room_id: str, channel_type: str | None
    ) -> bool:
        """Whether every message in this room is for its agent without naming it.

        Only a direct room with exactly one agent. A direct room that gained a
        second agent reads as a group: each message has to name the agents it
        is for, or it is a note for nobody. Public and private rooms never
        auto-address, whatever their agent count.
        """
        if channel_type != "direct":
            return False
        return len(await self._room_store.get_agent_ids(session, room_id)) == 1

    def mentions_name(
        self, *, agent: Agent, agent_user_id: str, message: IncomingMessage
    ) -> bool:
        """An `@name` at a token boundary, or a rendered mention pill.

        The pill is checked first because it is unambiguous. The plain-text
        scan is what catches everything else — media captions carry no
        formatted body, and neither does a bridged message.
        """
        if message.formatted_body and agent_user_id in message.formatted_body:
            return True
        return mention_regex(agent.name).search(message.addressable_body) is not None

    async def mentions_alias(
        self,
        session: AsyncSession,
        *,
        agent: Agent,
        room_id: str,
        message: IncomingMessage,
    ) -> bool:
        """An `@alias` for the name this agent goes under in this room.

        A room alias addresses the agent exactly like its real name. Looked up
        live, so a change takes effect on the next message with no per-client
        cache to invalidate.
        """
        if "@" not in message.addressable_body:
            return False
        alias = await self.alias_of(session, room_id, agent.id)
        if not alias:
            return False
        return mention_regex(alias).search(message.addressable_body) is not None

    async def mentions_role(
        self,
        session: AsyncSession,
        *,
        agent: Agent,
        room_id: str,
        message: IncomingMessage,
    ) -> bool:
        """An `@role` for a room-role this agent LIVE-holds.

        Tagging a role reaches whoever is doing that job, so an interchangeable
        agent can be addressed by responsibility rather than by name. Only a
        live lease counts, which makes "held" mean the same thing here as in
        `!roles`: a stale lease — session gone, role auto-released, shown free
        — does not route here. A holder whose session merely hopped to another
        room still matches, because liveness follows the holder rather than
        the room it is attending.
        """
        if "@" not in message.addressable_body:
            return False
        role_name = await self.role_of(session, room_id, agent.id)
        if not role_name:
            return False
        return mention_regex(role_name).search(message.addressable_body) is not None

    # ── What the rules read ───────────────────────────────────────────────────
    #
    # The rules above and below ask the database these few questions and
    # nothing else. Each is a method of its own so that a caller deciding one
    # message for every agent in a room at once (the router) can answer them
    # from reads it made once for the whole room, while every rule stays the
    # one written here.

    async def alias_of(
        self, session: AsyncSession, room_id: str, agent_id: str
    ) -> str | None:
        """The name the agent goes under in this room, if it has one."""
        return await self._room_store.get_alias(session, room_id, agent_id)

    async def role_of(
        self, session: AsyncSession, room_id: str, agent_id: str
    ) -> str | None:
        """The room role the agent live-holds in this room, if any."""
        return await self._room_role_store.agent_room_role(
            session, room_id, agent_id, self._live_connection_ids()
        )

    async def group_of(self, session: AsyncSession, room_id: str) -> str | None:
        """The room group the room belongs to, which a policy can name."""
        room = await self._room_store.get(session, room_id)
        return room.group_id if room is not None else None

    async def claimed_accounts(self, session: AsyncSession, user_id: str) -> list[str]:
        """The ids of the platform accounts a Switch user has claimed."""
        claimed = await self._external_user_store.get_by_user(session, user_id)
        return [ext.id for ext in claimed]

    # ── Permitted ─────────────────────────────────────────────────────────────

    async def permitted(
        self,
        session: AsyncSession,
        *,
        agent: Agent,
        room_id: str,
        sender: str,
        content: Mapping[str, object] | None = None,
    ) -> AddressingDecision:
        """Whether `sender` may address this agent in this room.

        An agent with no policy is open to anyone, so this answers without a
        database round-trip. With a policy set it is deny-by-default: a sender
        that resolves to nothing is refused rather than given the benefit of
        the doubt, because an identity nobody can name is exactly what a
        restricted agent is restricted against.

        `content` is the event's content. A platform-marked event is the one
        case an open policy does not settle up front: the platform's own
        message is denied unless a rule admits it, and a message it sends on
        a person's behalf is judged as that person. Checking the marker is a
        dict lookup, so the open-policy fast path stays free for everyone
        else.
        """
        policy = parse_policy(agent.addressing_policy)
        content = content or {}
        if policy.is_open() and PLATFORM_MARKER not in content:
            return AddressingDecision(allowed=True, refusal="")

        principal = await self.resolve_sender(session, sender, content)
        group_id = await self.group_of(session, room_id)

        if principal is None:
            if policy.is_open():
                # The marker was on an event from a sender that is not the
                # platform. It carries no authority, so the sender is treated
                # as anyone else the open policy already admits.
                return AddressingDecision(allowed=True, refusal="")
            logger.warning(
                "Addressing denied for %s: unresolvable sender %s in room %s",
                agent.name,
                sender,
                room_id,
            )
            return AddressingDecision(allowed=False, refusal=ADDRESSING_DENIED_MESSAGE)

        if principal.kind == "platform" and principal.on_behalf_of is not None:
            allowed = allows_on_behalf_of(
                policy,
                room_id=room_id,
                group_id=group_id,
                user_id=principal.on_behalf_of,
                external_user_ids=await self.claimed_accounts(
                    session, principal.on_behalf_of
                ),
                owner_user_id=agent.owner_id,
            )
        elif policy.is_open() and principal.kind != "platform":
            allowed = True
        else:
            allowed = can_address(
                policy,
                room_id=room_id,
                group_id=group_id,
                sender_kind=principal.kind,
                sender_id=principal.id,
                sender_user_ids=principal.user_ids,
                sender_owner_user_id=principal.owner_user_id,
                owner_user_id=agent.owner_id,
            )
        if allowed:
            return AddressingDecision(allowed=True, refusal="")

        # An owner-scoped rule cannot match a human nobody has claimed, so the
        # refusal says what to fix rather than implying a decision was made.
        unclaimed = (
            principal.kind == "user"
            and not principal.user_ids
            and policy.requires_owner_identity()
        )
        if unclaimed:
            logger.warning(
                "Addressing denied for %s: sender %s in room %s has not been "
                "claimed by any Switch user, so an owner-scoped rule cannot "
                "match them — the owner may need to link this identity",
                agent.name,
                principal.id,
                room_id,
            )
        else:
            logger.warning(
                "Addressing denied for %s: %s %s not permitted in room %s",
                agent.name,
                principal.kind,
                principal.id,
                room_id,
            )
        return AddressingDecision(
            allowed=False,
            refusal=(
                ADDRESSING_UNCLAIMED_MESSAGE if unclaimed else ADDRESSING_DENIED_MESSAGE
            ),
        )

    async def resolve_sender(
        self,
        session: AsyncSession,
        transport_user_id: str,
        content: Mapping[str, object] | None = None,
    ) -> SenderPrincipal | None:
        """Map a sender's mxid to the principal a policy is written about.

        Every participant is a Switch client, so the mxid resolves to a Client
        and from there to an Agent, an ExternalUser, a gateway user's member
        client, or the admin client (the platform). None means none of those,
        which a restricted agent should not trust.

        A member client is that gateway user speaking in person, so it
        resolves to them directly: `user_ids` is that one user, with no
        platform claims involved.

        `content` matters only for the admin client: its platform marker may
        name the person the message speaks for. The marker is read for no
        other sender, so a copy of it on an agent's or a human's message
        changes nothing.

        The two symbolic subjects come from different fields and only one
        applies to any sender: `user_ids` are the Switch users who have claimed
        a human's platform account — empty for an agent, which is never its own
        owner — and `owner_user_id` is who owns an agent sender, None for a
        human.
        """
        client = await self._client_store.get_by_transport_user_id(
            session, transport_user_id
        )
        if client is None:
            return None
        agent = await self._agent_store.get_by_client_id(session, client.id)
        if agent is not None:
            return SenderPrincipal("agent", agent.id, [], agent.owner_id)
        external_user = await self._external_user_store.get_by_client_id(
            session, client.id
        )
        if external_user is not None:
            claimants = await self._external_user_store.claimant_ids(
                session, external_user.id
            )
            return SenderPrincipal("user", external_user.id, claimants, None)
        if client.type == MEMBER_CLIENT_TYPE and client.user_id is not None:
            return SenderPrincipal("user", client.id, [client.user_id], None)
        if client.type == "admin":
            person = platform_on_behalf_of(content or {})
            if person is not None and person.agent_id is not None:
                # The message speaks for an agent, so the policy is asked what
                # it would say to that agent. An agent that no longer exists
                # leaves a bare platform message, which is denied by default.
                speaker = await self._agent_store.get(session, person.agent_id)
                if speaker is not None:
                    return SenderPrincipal("agent", speaker.id, [], speaker.owner_id)
                person = None
            return SenderPrincipal(
                "platform",
                client.id,
                [],
                None,
                on_behalf_of=person.user_id if person is not None else None,
            )
        return None