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.6 KB
Raw Blame
"""Following the conversation: when a message that mentions nobody is for an agent.

Addressing (`delivery/addressing.py`) answers "did this message ask this agent
for something?" from the message alone: a name, an alias, a role, a direct
chat. A person in a conversation does not repeat a name on every message, so
three rules extend it, each decided from the room's history:

- **Thread follow-up.** A reply in a thread reaches the agent that owns it:
  of the agents in the thread, the one that spoke most recently, or that a
  person tagged most recently (all of them, when one message tagged several,
  until one answers).
- **Channel follow-up.** A top-level message reaches the agent the sender is
  in an unbroken exchange with: the sender addressed the agent, the agent has
  answered since, nobody else has posted in between, the agent's last answer
  is within the window, and no gap between messages is longer than it. A
  message the decision service gave an agent doesn't count as addressing it,
  so the next untagged message in a room routing by decision is decided again.
- **Main agent.** In a room whose main agent is set (`!assign-agent`), every
  message reaches it.

A room can turn the two follow-up rules off with `!follow-ups off`; the main
agent rule is separate and unaffected. A room with automatic routing on
(`!auto-route on`, `delivery/decision.py`) skips the thread follow-up: the
decision service, which sees the whole thread, decides thread replies instead.
These settings live in the room's `metadata` (`db/stores/room_store.py`).

The rules only ever consider a person's message that has no `@` in it at
all: a mention always wins, and a message from an agent, an app or Switch
itself never reaches anyone by these rules, so agents cannot set each other
off. A post of files counts as one message, read from its first file, which
carries the post's text and thread. Permissions are not decided here; the caller applies the agent's policy
afterwards, as it does for a mention.

The router (`delivery/router.py`) asks these rules about a message that no
explicit rule named anyone in, before the message is written. What they read
about the room (the thread, the channel's latest messages, the handles that
reach an agent) is read once for the message and shared by every agent in
the room (`RoomConversation`), so the cost does not grow with the number of
agents. Every delivery, and every one the agent's policy refused, is logged
at INFO with the rule and the reason, so each route can be followed in the
server's log; an agent no rule chose is logged at DEBUG.
"""

from __future__ import annotations

import re
from collections.abc import Mapping
from dataclasses import dataclass
from datetime import datetime
from enum import StrEnum
from typing import TYPE_CHECKING

from switch_core.clients.admin_messages import (
    ADMIN_MARKER,
    AUTO_REPLY_FLAG,
    PLATFORM_MARKER,
    SENDER_IS_APP_MARKER,
)
from switch_core.clients.mentions import mention_tokens
from switch_core.delivery.addressing import IncomingMessage

if TYPE_CHECKING:
    from sqlalchemy.ext.asyncio import AsyncSession

    from switch_core.config import SwitchConfig
    from switch_core.db.models import Agent, Message
    from switch_core.db.stores.agent_store import AgentStore
    from switch_core.db.stores.message_store import MessageStore
    from switch_core.db.stores.room_role_store import RoomRoleStore
    from switch_core.db.stores.room_store import RoomStore
    from switch_core.delivery.addressing import AddressingResolver


# How many of a thread's most recent messages are read when looking for the
# agent that spoke or was tagged last.
THREAD_LOOKBACK = 200

# How many of the channel's earlier top-level messages one walk reads. An
# exchange longer than this still continues: see `_channel_follow_up`.
CHANNEL_LOOKBACK = 20

# Thanks and praise: they close an exchange rather than continue it, so they
# never wake an agent through a follow-up. Answers are deliberately absent:
# "yes", "ok", "+1" or a thumbs-up may be the reply to an agent's question.
_SMALL_TALK = frozenset(
    {
        "thanks",
        "thank you",
        "thanks a lot",
        "thank you very much",
        "many thanks",
        "thx",
        "ty",
        "cheers",
        "great",
        "nice",
        "cool",
        "perfect",
        "awesome",
        "brilliant",
    }
)

_TRAILING_PUNCTUATION = re.compile(r"[\s.!?,;:]+$")


def is_small_talk(body: str) -> bool:
    """True for thanks or praise ("thanks!", "great"), which ends an exchange
    rather than continuing it."""
    return _TRAILING_PUNCTUATION.sub("", body.strip().lower()) in _SMALL_TALK


def mentioned_names(body: str) -> set[str]:
    """The names @-mentioned in the text, lowercased."""
    return {name.lower() for name in mention_tokens(body)}


def mentions_anyone(body: str) -> bool:
    """Whether the text @-mentions anyone, by the same token rule mentions use.
    A mention always wins, so the rules stand aside."""
    return bool(mention_tokens(body))


NOT_TAKING_PART = "the agent is not taking part in this thread"
# A thread belongs to the agent that spoke or was tagged most recently in it.
ANOTHER_AGENT_SPOKE = "another agent spoke more recently in this thread"
ANOTHER_AGENT_TAGGED = "another agent was tagged more recently in this thread"


class ConversationRoute(StrEnum):
    THREAD_FOLLOW_UP = "thread_follow_up"
    CHANNEL_FOLLOW_UP = "channel_follow_up"
    MAIN_AGENT = "main_agent"


@dataclass(frozen=True)
class ConversationDecision:
    """Which rule, if any, delivers the message to the agent, and why."""

    route: ConversationRoute | None
    reason: str


@dataclass(frozen=True)
class ConversationSettings:
    """The deployment's settings for the rules, parsed once at startup."""

    enabled: bool
    window_seconds: int

    @classmethod
    def from_config(cls, config: SwitchConfig) -> ConversationSettings:
        return cls(
            enabled=config.follow_the_conversation_enabled,
            window_seconds=config.follow_the_conversation_window_seconds,
        )


@dataclass(frozen=True)
class ConversationMessage:
    """The message being decided: what addressing knows, plus where it sits
    and when it was sent. It is decided before it is written, so `sent_at` is
    the time it is being written, not a time read back from its row."""

    event_id: str
    sender: str
    body: str
    content: Mapping[str, object]
    thread_root_id: str | None
    sent_at: datetime
    # Set for a message whose rows were written a while before it is decided
    # (a multi-file post): the rules then read only rows written before it,
    # not what was written in the room while it waited.
    before_seq: int | None = None


def may_follow(
    settings: ConversationSettings,
    *,
    channel_type: str | None,
    message: ConversationMessage,
) -> bool:
    """The checks that need no database read. False means no rule can apply.

    Most room chatter is settled here, before a pool slot is taken.
    """
    if not settings.enabled:
        return False
    if channel_type == "direct":
        return False
    if mentions_anyone(message.body):
        return False
    content = message.content
    return not any(
        marker in content
        for marker in (
            ADMIN_MARKER,
            AUTO_REPLY_FLAG,
            PLATFORM_MARKER,
            SENDER_IS_APP_MARKER,
        )
    )


def _as_incoming(row: Message) -> IncomingMessage:
    return IncomingMessage(
        sender=row.sender_id,
        body=row.body or "",
        formatted_body=row.formatted_body,
        content=dict(row.content or {}),
    )


def is_automatic(row: Message) -> bool:
    """Switch's own notices and the automatic replies an agent's client posts
    ("Starting a session…"): neither is anyone taking part."""
    content = row.content or {}
    return AUTO_REPLY_FLAG in content or ADMIN_MARKER in content


class ConversationRules:
    """The rules, one per process. `for_message` gives one message's view of
    its room, which decides the message for each agent in turn."""

    def __init__(
        self,
        *,
        settings: ConversationSettings,
        message_store: MessageStore,
        room_store: RoomStore,
        agent_store: AgentStore,
        room_role_store: RoomRoleStore,
    ) -> None:
        self._settings = settings
        self.message_store = message_store
        self.room_store = room_store
        self.agent_store = agent_store
        self.room_role_store = room_role_store

    @property
    def settings(self) -> ConversationSettings:
        return self._settings

    def for_message(
        self,
        *,
        addressing: AddressingResolver,
        room_id: str,
        channel_type: str | None,
        follow_ups_enabled: bool,
        main_agent_id: str | None,
        auto_route_on: bool,
        message: ConversationMessage,
    ) -> RoomConversation:
        """`message`'s room as the rules see it, for a message that has passed
        `may_follow`. `follow_ups_enabled` and `main_agent_id` are the room's
        settings, read with the room; `auto_route_on` is whether automatic
        routing is on in it, and can act on this server."""
        return RoomConversation(
            rules=self,
            addressing=addressing,
            room_id=room_id,
            channel_type=channel_type,
            follow_ups_enabled=follow_ups_enabled,
            main_agent_id=main_agent_id,
            auto_route_on=auto_route_on,
            message=message,
        )


class RoomConversation:
    """One message's room, as the rules read it: read the first time an
    agent's decision asks, and kept for the other agents in the room.

    The message itself may already be a row (a test writes it first); it is
    left out of everything read, so the rules see only what came before it.
    """

    def __init__(
        self,
        *,
        rules: ConversationRules,
        addressing: AddressingResolver,
        room_id: str,
        channel_type: str | None,
        follow_ups_enabled: bool,
        main_agent_id: str | None,
        auto_route_on: bool,
        message: ConversationMessage,
    ) -> None:
        self._rules = rules
        self._settings = rules.settings
        self._addressing = addressing
        self._room_id = room_id
        self._channel_type = channel_type
        self._follow_ups_enabled = follow_ups_enabled
        self._main_agent_id = main_agent_id
        self._auto_route_on = auto_route_on
        self._message = message
        self._sent_by_person: bool | None = None
        self._sender_kinds: dict[str, str | None] = {}
        self._thread_rows: list[Message] | None = None
        self._channel_rows: list[Message] | None = None
        self._agent_names: set[str] | None = None

    @property
    def auto_route_on(self) -> bool:
        """Whether the room routes by decision: the decision service is asked
        about a message these rules deliver to nobody."""
        return self._auto_route_on

    async def decide(
        self, session: AsyncSession, *, agent: Agent, agent_user_id: str
    ) -> ConversationDecision:
        """Which rule delivers the message to `agent`, if any."""
        message = self._message
        is_main_agent = self._main_agent_id == agent.id
        if not self._follow_ups_enabled and not is_main_agent:
            # Settled from the room's settings alone: nothing to read.
            return ConversationDecision(
                None, "follow-ups are switched off in this room"
            )
        if not await self.from_a_person(session):
            return ConversationDecision(None, "not sent by a person")

        follow_up: ConversationDecision
        if not self._follow_ups_enabled:
            follow_up = ConversationDecision(
                None, "follow-ups are switched off in this room"
            )
        elif is_small_talk(message.body):
            follow_up = ConversationDecision(None, "small talk")
        elif message.thread_root_id is not None and self._auto_route_on:
            follow_up = ConversationDecision(
                None, "thread follow-ups are off while automatic routing is on"
            )
        elif message.thread_root_id is not None:
            follow_up = await self._thread_follow_up(
                session,
                agent=agent,
                agent_user_id=agent_user_id,
                thread_root_id=message.thread_root_id,
            )
        else:
            follow_up = await self._channel_follow_up(
                session, agent=agent, agent_user_id=agent_user_id
            )
        if follow_up.route is not None:
            return follow_up
        if is_main_agent:
            return ConversationDecision(
                ConversationRoute.MAIN_AGENT, "the room's main agent"
            )
        return follow_up

    @property
    def message(self) -> ConversationMessage:
        return self._message

    async def from_a_person(self, session: AsyncSession) -> bool:
        """Whether the message was sent by a person, rather than an agent, an
        app or Switch itself."""
        if self._sent_by_person is None:
            message = self._message
            principal = await self._addressing.resolve_sender(
                session, message.sender, message.content
            )
            self._sent_by_person = principal is not None and principal.kind == "user"
        return self._sent_by_person

    async def sender_kind(self, session: AsyncSession, row: Message) -> str | None:
        """The kind of principal that sent `row` (`SenderPrincipal.kind`)."""
        if row.sender_id not in self._sender_kinds:
            principal = await self._addressing.resolve_sender(
                session, row.sender_id, row.content or {}
            )
            self._sender_kinds[row.sender_id] = principal.kind if principal else None
        return self._sender_kinds[row.sender_id]

    async def thread(self, session: AsyncSession) -> list[Message]:
        """The messages of the thread the message replies in, newest first and
        up to `THREAD_LOOKBACK`; none for a top-level message."""
        thread_root_id = self._message.thread_root_id
        if thread_root_id is None:
            return []
        return await self._thread(session, thread_root_id)

    async def channel(self, session: AsyncSession) -> list[Message]:
        """The room's latest top-level messages, newest first and up to
        `CHANNEL_LOOKBACK`."""
        return await self._channel(session)

    def _before_message(self, rows: list[Message], limit: int) -> list[Message]:
        event_id = self._message.event_id
        return [row for row in rows if row.transport_event_id != event_id][:limit]

    async def _thread(
        self, session: AsyncSession, thread_root_id: str
    ) -> list[Message]:
        if self._thread_rows is None:
            rows = await self._rules.message_store.list_thread_newest_first(
                session,
                self._room_id,
                thread_root_event_id=thread_root_id,
                limit=THREAD_LOOKBACK + 1,
                before_seq=self._message.before_seq,
            )
            self._thread_rows = self._before_message(rows, THREAD_LOOKBACK)
        return self._thread_rows

    async def _channel(self, session: AsyncSession) -> list[Message]:
        if self._channel_rows is None:
            rows = await self._rules.message_store.list_top_level_newest_first(
                session,
                self._room_id,
                limit=CHANNEL_LOOKBACK + 1,
                before_seq=self._message.before_seq,
            )
            self._channel_rows = self._before_message(rows, CHANNEL_LOOKBACK)
        return self._channel_rows

    async def _addressed_agent(
        self,
        session: AsyncSession,
        *,
        agent: Agent,
        agent_user_id: str,
        row: Message,
    ) -> bool:
        return await self._addressing.addresses(
            session,
            agent=agent,
            agent_user_id=agent_user_id,
            room_id=self._room_id,
            channel_type=self._channel_type,
            message=_as_incoming(row),
        )

    async def _thread_follow_up(
        self,
        session: AsyncSession,
        *,
        agent: Agent,
        agent_user_id: str,
        thread_root_id: str,
    ) -> ConversationDecision:
        """Whether this agent owns the thread: it spoke most recently, or a
        person tagged it most recently, of all the agents in the thread.

        Walks back from the reply, newest first, to the first message that is
        an agent's post or a person tagging an agent. A message tagging several
        agents gives the thread to all of them until one answers. A person
        tagging another person doesn't move it.
        """
        for row in await self._thread(session, thread_root_id):
            if is_automatic(row):
                continue
            if row.sender_id == agent_user_id:
                return ConversationDecision(
                    ConversationRoute.THREAD_FOLLOW_UP,
                    "the agent spoke most recently in this thread",
                )
            if await self.sender_kind(session, row) == "agent":
                return ConversationDecision(None, ANOTHER_AGENT_SPOKE)
            if await self._addressed_agent(
                session, agent=agent, agent_user_id=agent_user_id, row=row
            ):
                return ConversationDecision(
                    ConversationRoute.THREAD_FOLLOW_UP,
                    "the agent was tagged most recently in this thread",
                )
            names = mentioned_names(row.body or "")
            if names and names & await self._room_agent_names(session):
                return ConversationDecision(None, ANOTHER_AGENT_TAGGED)
        return ConversationDecision(None, NOT_TAKING_PART)

    async def _room_agent_names(self, session: AsyncSession) -> set[str]:
        """Every handle that reaches an agent in this room, lowercased: names,
        room aliases and room roles."""
        if self._agent_names is not None:
            return self._agent_names
        rules = self._rules
        names: set[str] = set()
        for agent_id in await rules.room_store.get_agent_ids(session, self._room_id):
            agent = await rules.agent_store.get(session, agent_id)
            if agent is not None:
                names.add(agent.name.lower())
        names.update(
            alias.lower()
            for alias in (
                await rules.room_store.list_aliases(session, self._room_id)
            ).values()
        )
        names.update(
            role.name.lower()
            for role in await rules.room_role_store.list_roles(session, self._room_id)
        )
        self._agent_names = names
        return names

    async def _channel_follow_up(
        self, session: AsyncSession, *, agent: Agent, agent_user_id: str
    ) -> ConversationDecision:
        """Walk back through the channel's top-level messages for an unbroken
        exchange between the sender and this agent.

        It must have started with the sender addressing the agent, unless it
        runs past the lookback: a run that long with only the two of them in
        it, each gap inside the window, can only be an exchange already under
        way. Anyone else posting ends it, and so does the sender turning to
        someone else with a mention.
        """
        message = self._message
        window = self._settings.window_seconds
        rows = await self._channel(session)
        later_sent_at = message.sent_at
        agent_answered = False
        for index, row in enumerate(rows):
            if is_automatic(row):
                continue
            gap = (later_sent_at - row.sent_at).total_seconds()  # type: ignore[operator]
            if gap > window:
                return ConversationDecision(None, "too long since the last message")
            later_sent_at = row.sent_at  # type: ignore[assignment]
            if row.sender_id == agent_user_id:
                if not agent_answered:
                    since_answer = (message.sent_at - row.sent_at).total_seconds()  # type: ignore[operator]
                    if since_answer > window:
                        return ConversationDecision(
                            None, "too long since the agent's last answer"
                        )
                agent_answered = True
                continue
            if row.sender_id != message.sender:
                if agent_answered or any(
                    earlier.sender_id == agent_user_id and not is_automatic(earlier)
                    for earlier in rows[index + 1 :]
                ):
                    return ConversationDecision(
                        None, "someone else posted after the agent's last answer"
                    )
                return ConversationDecision(None, "no recent exchange with this agent")
            if await self._addressed_agent(
                session, agent=agent, agent_user_id=agent_user_id, row=row
            ):
                if agent_answered:
                    return ConversationDecision(
                        ConversationRoute.CHANNEL_FOLLOW_UP,
                        "continues an exchange the agent has just answered",
                    )
                return ConversationDecision(None, "the agent has not answered yet")
            if mentions_anyone(row.body or ""):
                return ConversationDecision(
                    None, "the sender turned to someone else since"
                )
        if agent_answered and len(rows) == CHANNEL_LOOKBACK:
            return ConversationDecision(
                ConversationRoute.CHANNEL_FOLLOW_UP,
                "continues a long exchange the agent is answering",
            )
        return ConversationDecision(None, "no recent exchange with this agent")