Skip to content

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

102 KB
Raw Blame
"""A gateway user in Switch rooms as themselves: membership, chats and sends.

Membership is the only read authority. A person sees a room when their
`member` client has a `client_rooms` row for it and they still hold a role in
the tenant; a room's visibility and any claimed platform account do not count.
Membership is granted by creating a chat, by a room manager (the room's owner
or a tenant admin) adding a tenant member, or by a manager adding themselves.
With the `agent_chats` feature flag on, it is also granted to a person in each
chat they started that holds an agent they own, for as long as it does:
`sync_owned_rooms` puts them in and takes back what was held only for that.
Other people's chats and rooms set up elsewhere never gain an agent's owner.

Requests a person may retry carry a request id, recorded in `chat_operations`
per user. The same id with the same payload answers what the first attempt
did; with a different payload it is refused.
"""

from __future__ import annotations

import asyncio
import hashlib
import json
import logging
import re
import uuid
import weakref
from collections.abc import AsyncIterator, Callable
from contextlib import asynccontextmanager
from dataclasses import dataclass
from datetime import UTC, datetime
from typing import TYPE_CHECKING, Literal

import markdown
from sqlalchemy import (
    ColumnElement,
    and_,
    delete,
    exists,
    false,
    func,
    or_,
    select,
    update,
)
from sqlalchemy.dialects.postgresql import insert as pg_insert
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

from switch_core.addressing import allows_on_behalf_of, parse_policy
from switch_core.authz import ORGANIZATION_ADMIN_ROLE, administers_tenant
from switch_core.bridges.agent.protocol.agent_connections import AgentConnectionRegistry
from switch_core.bridges.agent.registration_bootstrap import is_bootstrap_owner
from switch_core.chats import MEMBER_CLIENT_TYPE
from switch_core.chats.views import (
    COMMAND_EVENT_TYPE,
    MESSAGE_EVENT_TYPE,
    SHOWN_EVENT_TYPES,
    ChatMention,
)
from switch_core.clients.mentions import mention_regex, strip_emphasis
from switch_core.db.models import (
    Agent,
    AgentSessionActivityItem,
    ApprovalRequest,
    ChatHidden,
    ChatOperation,
    ChatOwnerGrant,
    ChatRead,
    Client,
    ClientRoom,
    CollaborationBridge,
    MediaBlob,
    Message,
    MessageAttachment,
    Room,
    TenantMember,
    UsageMetric,
    User,
    require_tenant_id,
    room_agents,
)
from switch_core.db.session_scope import tenant_session
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.media_store import MediaStore
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.db.stores.session_activity_store import (
    RETRYABLE_TURN_STATUSES,
    AgentSessionActivityStore,
    ApprovalRequestStore,
)
from switch_core.db.stores.usage_store import UsageStore
from switch_core.db.stores.user_store import UserStore
from switch_core.delivery.addressing import MENTIONS_KEY, AddressingResolver
from switch_core.messages.notify import MessageListener
from switch_core.messages.row import attachments_in, message_row, new_event_id
from switch_core.observability.catalogue import MESSAGES_SENT
from switch_core.observability.metrics import metrics
from switch_core.provisioning import Provisioning
from switch_core.room_service import RoomCreateConfig, RoomService
from switch_core.session_activity.listener import AgentSessionActivityListener
from switch_core.session_activity.maintenance import ACTIVITY_RETENTION
from switch_core.sessions.attachments import normalise_mime_type
from switch_core.tenant_context import tenant_scope
from switch_core.transport.content import media_content, message_content
from switch_core.transport.types import MessageFormat
from switch_core.trust.attachments import AttachmentsVerdict, check_attachments
from switch_core.trust.client import (
    TrustCheckResult,
    TrustClient,
    check_message,
    trust_annotation,
    trust_is_active,
)

if TYPE_CHECKING:
    from switch_core.chats.signals import ChatSignals
    from switch_core.delivery.router import MessageRouter, Routed

logger = logging.getLogger(__name__)

# Told the rooms whose part in a person's chats changed, or None for any.
MembershipWatcher = Callable[[list[str] | None], None]

# Fixed so the ids derived from it are stable across processes and releases.
_CHATS_NAMESPACE = uuid.UUID("6f1d3c2e-8a4b-4f5e-9c7d-2b1a0e9f8d7c")


class ChatError(Exception):
    """A refusal the gateway reports as `{"detail": {"code", "message"}}`."""

    def __init__(self, status: int, code: str, message: str) -> None:
        super().__init__(message)
        self.status = status
        self.code = code
        self.message = message


@dataclass(frozen=True)
class StagedUpload:
    upload_id: str
    uri: str
    filename: str
    mimetype: str
    size: int


RemovalReason = Literal["access", "unlisted"]

# Long enough for a welcome with tips; a greeting is not a document.
GREETING_MAX_CHARS = 4000
RoomControl = Literal["interrupt", "reset", "compact", "retry"]


def _hash(payload: dict[str, object]) -> str:
    return hashlib.sha256(
        json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
    ).hexdigest()


def _upload_key(upload_id: str) -> str:
    # Uploads share the per-user key space with requests; the prefix keeps a
    # client's upload id from ever colliding with one of its request ids.
    return f"upload:{upload_id}"


class ChatService:
    def __init__(
        self,
        *,
        session_factory: async_sessionmaker[AsyncSession],
        room_service: RoomService,
        provisioning: Provisioning,
        listener: MessageListener,
        activity_listener: AgentSessionActivityListener,
        room_store: RoomStore,
        agent_store: AgentStore,
        user_store: UserStore,
        message_store: MessageStore,
        router: MessageRouter,
        media_store: MediaStore,
        usage_store: UsageStore,
        id_server_name: str,
        media_max_bytes: int,
        agent_chats_enabled: bool,
        group_chats_enabled: bool,
        buddy_slack_handoff_enabled: bool,
        connections: AgentConnectionRegistry,
        trust_client: TrustClient,
    ) -> None:
        self.session_factory = session_factory
        self._trust_client = trust_client
        self._connections = connections
        self.agent_chats_enabled = agent_chats_enabled
        self.group_chats_enabled = group_chats_enabled
        self.buddy_slack_handoff_enabled = buddy_slack_handoff_enabled
        self.listener = listener
        self.activity_listener = activity_listener
        self._activity_store = AgentSessionActivityStore()
        self._approval_store = ApprovalRequestStore()
        self._room_service = room_service
        self._provisioning = provisioning
        self._room_store = room_store
        self._agent_store = agent_store
        self._user_store = user_store
        self._message_store = message_store
        self._router = router
        self._media_store = media_store
        self._usage_store = usage_store
        self._id_server_name = id_server_name
        self._media_max_bytes = media_max_bytes
        self._locks: weakref.WeakValueDictionary[tuple[str, ...], asyncio.Lock] = (
            weakref.WeakValueDictionary()
        )
        self._membership_watchers: dict[tuple[str, str], set[MembershipWatcher]] = {}
        self._agent_room_listeners: tuple[Callable[[str, list[str]], None], ...] = ()
        self._tasks: set[asyncio.Task[None]] = set()
        # Where a change to people's chats made here is announced to the
        # other processes, once wired (`use_signals`).
        self._signals: ChatSignals | None = None
        self._addressing = AddressingResolver(
            room_store=room_store,
            room_role_store=RoomRoleStore(),
            client_store=ClientStore(),
            agent_store=agent_store,
            external_user_store=ExternalUserStore(),
            # Only role mentions consult liveness; a permission check never does.
            live_connection_ids=set,
        )

    # ── Membership signals ───────────────────────────────────────────────────

    def use_signals(self, signals: ChatSignals) -> None:
        """Where a change to people's chats made here is announced, so every
        other process wakes the streams it holds for them (`signals.py`)."""
        self._signals = signals

    def watch_memberships(
        self, tenant_id: str, user_id: str, callback: MembershipWatcher
    ) -> None:
        """Call `callback` whenever the user's chats change: at once when this
        process changed them, and once told when another process did. It is
        given the rooms that changed, or None when any may have."""
        self._membership_watchers.setdefault((tenant_id, user_id), set()).add(callback)

    def unwatch_memberships(
        self, tenant_id: str, user_id: str, callback: MembershipWatcher
    ) -> None:
        watchers = self._membership_watchers.get((tenant_id, user_id))
        if watchers is None:
            return
        watchers.discard(callback)
        if not watchers:
            del self._membership_watchers[(tenant_id, user_id)]

    def wake_membership_watchers(
        self, tenant_id: str, user_ids: list[str], room_ids: list[str] | None
    ) -> None:
        """Call every callback watching these users' chats in this process,
        with the rooms that changed (None: any)."""
        for user_id in user_ids:
            for callback in list(
                self._membership_watchers.get((tenant_id, user_id), ())
            ):
                callback(room_ids)

    def wake_all_membership_watchers(self) -> None:
        """Call every callback watching anyone's chats in this process, once,
        with any room in question."""
        for watchers in list(self._membership_watchers.values()):
            for callback in list(watchers):
                callback(None)

    def _memberships_changed(
        self, tenant_id: str, user_ids: list[str], room_ids: list[str]
    ) -> None:
        """The users' part in chats `room_ids` changed through this process
        (joined, left, or what their summaries show), and the change has
        committed: the streams here are woken at once, and the other
        processes are told to wake theirs. A stream re-reads which chats its
        person has on every wake, and re-summarises only these."""
        self.wake_membership_watchers(tenant_id, user_ids, room_ids)
        if self._signals is not None:
            self._signals.memberships_changed(tenant_id, user_ids, room_ids)

    def _require_group_chats(self) -> None:
        """Refuse a group-only request while `group_chats` is off, so a fleet
        that turned it off (or never on) says so rather than half-serving it."""
        if not self.group_chats_enabled:
            raise ChatError(
                409, "GROUP_CHATS_OFF", "Group chats are not turned on here."
            )

    def _lock(self, *key: str) -> asyncio.Lock:
        lock = self._locks.get(key)
        if lock is None:
            lock = asyncio.Lock()
            self._locks[key] = lock
        return lock

    # ── Identity and access ──────────────────────────────────────────────────

    async def member_client(self, session: AsyncSession, user_id: str) -> Client | None:
        return (
            await session.execute(
                select(Client).where(
                    Client.tenant_id == require_tenant_id(),
                    Client.user_id == user_id,
                    Client.type == MEMBER_CLIENT_TYPE,
                )
            )
        ).scalar_one_or_none()

    async def member_actor(self, tenant_id: str, user: User) -> Client:
        """The user's member client in the tenant, created on first use."""
        async with self._lock("member", tenant_id, user.id):
            async with tenant_session(self.session_factory, tenant_id) as session:
                client = await self.member_client(session, user.id)
                if client is not None:
                    return client
                # Another process may be creating the same one: the first
                # insert wins, and this one reads what it wrote.
                created = await session.scalar(
                    pg_insert(Client)
                    .values(
                        id=str(uuid.uuid4()),
                        tenant_id=tenant_id,
                        transport_user_id=f"@switch-member-{user.id}:{self._id_server_name}",
                        display_name=user.name,
                        type=MEMBER_CLIENT_TYPE,
                        user_id=user.id,
                    )
                    .on_conflict_do_nothing()
                    .returning(Client.id)
                )
                await session.commit()
                if created is not None:
                    logger.info(
                        "Created member client %s for user %s", created, user.id
                    )
                client = await self.member_client(session, user.id)
                if client is None:
                    raise RuntimeError(
                        f"No member client for user {user.id} after creating one"
                    )
                return client

    async def has_tenant_role(
        self, session: AsyncSession, tenant_id: str, user_id: str
    ) -> bool:
        """Whether `user_id` stands in `tenant_id`: a membership row, or
        `org_admin` of its organization, read only when there is no row. Asked
        on every chat read and write."""
        if await self._user_store.tenant_role(session, tenant_id, user_id) is not None:
            return True
        return (
            await self._user_store.organization_role(session, tenant_id, user_id)
            == ORGANIZATION_ADMIN_ROLE
        )

    async def _room(self, session: AsyncSession, tenant_id: str, room_id: str) -> Room:
        room = await self._room_store.get(session, room_id)
        if room is None or room.tenant_id != tenant_id:
            raise ChatError(404, "ROOM_NOT_FOUND", "Room not found.")
        return room

    async def _is_in_room(
        self, session: AsyncSession, client_id: str, room_id: str
    ) -> bool:
        return bool(
            await session.scalar(
                select(
                    exists().where(
                        ClientRoom.client_id == client_id, ClientRoom.room_id == room_id
                    )
                )
            )
        )

    async def require_member(
        self, session: AsyncSession, tenant_id: str, user: User, room_id: str
    ) -> tuple[Room, Client]:
        """The room and the caller's member client, or a refusal.

        Checked on every read and write, and again when a retried request
        resumes, so removal from the room or the tenant takes effect at once.
        """
        room = await self._room(session, tenant_id, room_id)
        refusal = ChatError(403, "NOT_A_MEMBER", "You are not a member of this chat.")
        if not await self.has_tenant_role(session, tenant_id, user.id):
            raise refusal
        client = await self.member_client(session, user.id)
        if client is not None and await self._is_in_room(session, client.id, room.id):
            return room, client
        if room.archived_at is None and await self.joins_as_owner(
            session, user.id, room.id
        ):
            await self.sync_owned_rooms(tenant_id, user.id)
            client = await self.member_client(session, user.id)
            if client is not None and await self._is_in_room(
                session, client.id, room.id
            ):
                return room, client
        raise refusal

    async def can_manage(
        self, session: AsyncSession, tenant_id: str, user: User, room: Room
    ) -> bool:
        if room.owner_id is not None and room.owner_id == user.id:
            return True
        return await self.administers(session, tenant_id, user)

    async def administers(
        self, session: AsyncSession, tenant_id: str, user: User
    ) -> bool:
        """Whether the user manages every room in the tenant (`can_manage`)."""
        return administers_tenant(
            is_operator=user.role == "admin",
            tenant_role=await self._user_store.tenant_role(session, tenant_id, user.id),
            organization_role=await self._user_store.organization_role(
                session, tenant_id, user.id
            ),
        )

    async def head_seqs(
        self, session: AsyncSession, room_ids: list[str]
    ) -> dict[str, int]:
        return await self._message_store.head_seqs(session, room_ids)

    async def _require_manager(
        self, session: AsyncSession, tenant_id: str, user: User, room: Room
    ) -> None:
        if not await self.can_manage(session, tenant_id, user, room):
            raise ChatError(
                403,
                "NOT_A_MANAGER",
                "Only the room's owner or a workspace admin can do that.",
            )

    # ── Agent owners ─────────────────────────────────────────────────────────

    async def joins_as_owner(
        self, session: AsyncSession, user_id: str, room_id: str
    ) -> bool:
        """True when `sync_owned_rooms` keeps the user in this room."""
        if not self.agent_chats_enabled:
            return False
        return bool(
            await session.scalar(
                select(exists().where(Room.id == room_id, _owner_joins(user_id)))
            )
        )

    async def sync_owned_rooms(self, tenant_id: str, user_id: str) -> None:
        """Put the user in every live chat they started that holds an agent
        they own, and take back each membership held only for that once it no
        longer satisfies that rule. With `agent_chats` off nothing satisfies
        it: no one joins, and every such membership is taken back.

        Such a membership is marked by a `ChatOwnerGrant`; being invited,
        creating the chat or joining as a manager removes the mark, and the
        membership then stays when the agent goes. Cheap when nothing changed:
        two queries.
        """
        kept = _owner_joins(user_id) if self.agent_chats_enabled else false()
        async with self._lock("owned", tenant_id, user_id):
            async with tenant_session(self.session_factory, tenant_id) as session:
                if not await self.has_tenant_role(session, tenant_id, user_id):
                    return
                client = await self.member_client(session, user_id)
                joined: ColumnElement[bool] = (
                    exists().where(
                        ClientRoom.client_id == client.id,
                        ClientRoom.room_id == Room.id,
                    )
                    if client is not None
                    else false()
                )
                to_join = list(
                    (
                        await session.execute(
                            select(Room)
                            .where(
                                Room.tenant_id == tenant_id,
                                Room.archived_at.is_(None),
                                kept,
                                ~joined,
                            )
                            .order_by(Room.created_at)
                        )
                    )
                    .scalars()
                    .all()
                )
                to_drop = list(
                    (
                        await session.execute(
                            select(Room)
                            .join(ChatOwnerGrant, ChatOwnerGrant.room_id == Room.id)
                            .where(
                                ChatOwnerGrant.user_id == user_id,
                                # A room with no creator makes `kept` NULL, not false.
                                ~func.coalesce(kept, false()),
                            )
                        )
                    )
                    .scalars()
                    .all()
                )
                if not to_join and not to_drop:
                    return
                user = await self._user_store.get(session, user_id)
                assert user is not None
                if to_join:
                    # Marked before joining: a join cut short leaves a mark
                    # the next pass completes or clears, never a membership
                    # that would outlive the agent unmarked.
                    await session.execute(
                        pg_insert(ChatOwnerGrant)
                        .values(
                            [
                                {
                                    "tenant_id": tenant_id,
                                    "user_id": user_id,
                                    "room_id": room.id,
                                }
                                for room in to_join
                            ]
                        )
                        .on_conflict_do_nothing(
                            index_elements=["tenant_id", "user_id", "room_id"]
                        )
                    )
                    await session.commit()
            if client is None:
                client = await self.member_actor(tenant_id, user)
            for room in to_join:
                await self._join(tenant_id, room, client)
            for room in to_drop:
                with tenant_scope(tenant_id):
                    await self._provisioning.kick_user(
                        room.transport_room_id, client.transport_user_id
                    )
            if to_drop:
                async with tenant_session(self.session_factory, tenant_id) as session:
                    await session.execute(
                        delete(ChatOwnerGrant).where(
                            ChatOwnerGrant.user_id == user_id,
                            ChatOwnerGrant.room_id.in_([room.id for room in to_drop]),
                        )
                    )
                    await session.commit()
            logger.info(
                "Agent owner %s: joined %d room(s), left %d",
                user_id,
                len(to_join),
                len(to_drop),
            )
        self._memberships_changed(
            tenant_id, [user_id], [room.id for room in [*to_join, *to_drop]]
        )

    async def sync_room(self, tenant_id: str, room_id: str) -> None:
        """`sync_owned_rooms` for everyone a change to this room's agents may
        concern: the owners of its agents and the holders of owner grants.
        The room's other members are told too, as gaining or losing its
        agents can move it into or out of their list. Does nothing with
        `agent_chats` off."""
        if not self.agent_chats_enabled:
            return
        async with tenant_session(self.session_factory, tenant_id) as session:
            owners = set(
                (
                    await session.execute(
                        select(Agent.owner_id)
                        .join(room_agents, room_agents.c.agent_id == Agent.id)
                        .where(
                            room_agents.c.room_id == room_id,
                            Agent.owner_id.is_not(None),
                        )
                    )
                ).scalars()
            )
            holders = set(
                (
                    await session.execute(
                        select(ChatOwnerGrant.user_id).where(
                            ChatOwnerGrant.room_id == room_id
                        )
                    )
                ).scalars()
            )
            members = set(
                (
                    await session.execute(
                        select(Client.user_id)
                        .join(ClientRoom, ClientRoom.client_id == Client.id)
                        .where(
                            ClientRoom.room_id == room_id,
                            Client.type == MEMBER_CLIENT_TYPE,
                            Client.user_id.is_not(None),
                        )
                    )
                ).scalars()
            )
        for user_id in sorted(
            user_id for user_id in owners | holders if user_id is not None
        ):
            await self.sync_owned_rooms(tenant_id, user_id)
        self._memberships_changed(
            tenant_id,
            sorted(user_id for user_id in members if user_id is not None),
            [room_id],
        )

    def on_agent_room_changed(self, listener: Callable[[str, list[str]], None]) -> None:
        """Call `listener(tenant_id, room_ids)` with every room an agent is in
        when its name, display name or icon changes (`room_changes`), so
        whoever shows those rooms reads them again. It must not block."""
        self._agent_room_listeners = (*self._agent_room_listeners, listener)

    def room_changed(self, tenant_id: str, room_id: str, client_ids: list[str]) -> None:
        """A room's own details changed (its name, say): wake the streams of
        the people in it, from a task of its own, so they re-send its summary."""
        task = asyncio.create_task(self._room_details_changed(tenant_id, room_id))
        self._tasks.add(task)
        task.add_done_callback(self._task_done)

    def _task_done(self, task: asyncio.Task[None]) -> None:
        self._tasks.discard(task)
        if not task.cancelled() and task.exception() is not None:
            logger.error(
                "Could not wake the streams of a changed room's people; they "
                "re-read it on their next recheck",
                exc_info=task.exception(),
            )

    async def _room_details_changed(self, tenant_id: str, room_id: str) -> None:
        async with tenant_session(self.session_factory, tenant_id) as session:
            user_ids = (
                await session.execute(
                    select(Client.user_id)
                    .join(ClientRoom, ClientRoom.client_id == Client.id)
                    .where(
                        ClientRoom.room_id == room_id,
                        Client.type == MEMBER_CLIENT_TYPE,
                        Client.user_id.is_not(None),
                    )
                )
            ).scalars()
            members = sorted(user_id for user_id in user_ids if user_id is not None)
        self._memberships_changed(tenant_id, members, [room_id])

    async def agent_changed(self, tenant_id: str, agent_id: str) -> None:
        """Tell everyone who sees a room with this agent that it changed, and
        with `agent_chats` on, wake the streams of everyone in a chat with it
        so they re-send its summaries."""
        async with tenant_session(self.session_factory, tenant_id) as session:
            room_ids = list(
                (
                    await session.execute(
                        select(room_agents.c.room_id).where(
                            room_agents.c.agent_id == agent_id
                        )
                    )
                ).scalars()
            )
        for listener in self._agent_room_listeners:
            try:
                listener(tenant_id, room_ids)
            except Exception:
                logger.exception("Agent room listener failed for agent %s", agent_id)
        if not self.agent_chats_enabled:
            return
        async with tenant_session(self.session_factory, tenant_id) as session:
            members = (
                await session.execute(
                    select(Client.user_id)
                    .distinct()
                    .join(ClientRoom, ClientRoom.client_id == Client.id)
                    .join(room_agents, room_agents.c.room_id == ClientRoom.room_id)
                    .where(
                        room_agents.c.agent_id == agent_id,
                        Client.type == MEMBER_CLIENT_TYPE,
                        Client.user_id.is_not(None),
                    )
                )
            ).scalars()
            user_ids = sorted(user_id for user_id in members if user_id is not None)
        self._memberships_changed(tenant_id, user_ids, room_ids)

    async def _make_lasting(self, tenant_id: str, user_id: str, room_id: str) -> None:
        async with tenant_session(self.session_factory, tenant_id) as session:
            await session.execute(
                delete(ChatOwnerGrant).where(
                    ChatOwnerGrant.user_id == user_id, ChatOwnerGrant.room_id == room_id
                )
            )
            await session.commit()

    # ── Listing ──────────────────────────────────────────────────────────────

    async def readable_rooms(self, session: AsyncSession, user_id: str) -> list[Room]:
        """All rooms the caller can read: member of, unarchived, tenant role."""
        client = await self.member_client(session, user_id)
        if client is None:
            return []
        result = await session.execute(
            select(Room)
            .join(ClientRoom, ClientRoom.room_id == Room.id)
            .where(
                ClientRoom.client_id == client.id,
                Room.archived_at.is_(None),
            )
            .order_by(Room.created_at)
        )
        return list(result.scalars().all())

    async def stream_rooms(self, session: AsyncSession, user_id: str) -> list[Room]:
        """The caller's member rooms that are chats: unarchived, and either
        holding an agent or started in Switch Console (which may have none)."""
        return [
            room
            for room, listed in await self.readable_and_listed(session, user_id)
            if listed
        ]

    async def readable_and_listed(
        self, session: AsyncSession, user_id: str
    ) -> list[tuple[Room, bool]]:
        """The caller's member rooms, archived ones included, each with whether
        it is one of `stream_rooms`, in one query."""
        return [
            (room, is_chat and room.archived_at is None)
            for room, is_chat in await self._member_rooms(session, user_id)
        ]

    async def archived_chats(self, session: AsyncSession, user_id: str) -> list[Room]:
        """The caller's member rooms that would be in `stream_rooms` but for
        being archived."""
        return [
            room
            for room, is_chat in await self._member_rooms(session, user_id)
            if is_chat and room.archived_at is not None
        ]

    async def _member_rooms(
        self, session: AsyncSession, user_id: str
    ) -> list[tuple[Room, bool]]:
        """Every room the caller's member client is in, each with whether it
        is a chat: holding an agent or started in Switch Console."""
        client = await self.member_client(session, user_id)
        if client is None:
            return []
        is_chat = or_(
            exists().where(room_agents.c.room_id == Room.id),
            Room.metadata_.has_key("chat_operation_id"),
        )
        result = await session.execute(
            select(Room, is_chat)
            .join(ClientRoom, ClientRoom.room_id == Room.id)
            .where(ClientRoom.client_id == client.id)
            .order_by(Room.created_at)
        )
        return [(room, bool(chat)) for room, chat in result.all()]

    async def moved_rooms(
        self, session: AsyncSession, cursors: dict[str, int]
    ) -> set[str]:
        """Of the rooms in `cursors`, those with a row past their cursor."""
        return await self._message_store.rooms_past(session, cursors)

    async def room_activity(
        self, session: AsyncSession, room_id: str
    ) -> tuple[list[AgentSessionActivityItem], list[ApprovalRequest]]:
        """The room's turn steps and approval requests (every state) within retention."""
        since = datetime.now(UTC) - ACTIVITY_RETENTION
        return (
            await self._activity_store.for_room(session, room_id, since),
            await self._approval_store.for_room(session, room_id, since),
        )

    async def turn_items(
        self, session: AsyncSession, agent_id: str, session_id: str, turn_id: str
    ) -> list[AgentSessionActivityItem]:
        return await self._activity_store.turn(session, agent_id, session_id, turn_id)

    async def turn_item(
        self,
        session: AsyncSession,
        agent_id: str,
        session_id: str,
        turn_id: str,
        item_id: str,
    ) -> AgentSessionActivityItem | None:
        return await session.get(
            AgentSessionActivityItem,
            (require_tenant_id(), agent_id, session_id, turn_id, item_id),
        )

    async def reads_room(
        self, session: AsyncSession, tenant_id: str, user_id: str, room_id: str | None
    ) -> tuple[bool, bool]:
        """Whether the user still holds a role in the tenant, and whether they
        may read `room_id` now (`readable_rooms`, for that one room), in one
        query. A step outside any room is read by nobody here."""
        member = exists().where(
            TenantMember.tenant_id == tenant_id, TenantMember.user_id == user_id
        )
        reads = (
            exists().where(
                ClientRoom.room_id == room_id,
                ClientRoom.client_id == Client.id,
                Client.user_id == user_id,
                Client.type == MEMBER_CLIENT_TYPE,
                Room.id == room_id,
                Room.archived_at.is_(None),
            )
            if room_id is not None
            else false()
        )
        row = (await session.execute(select(member, reads))).one()
        return bool(row[0]), bool(row[0] and row[1])

    async def approval(
        self, session: AsyncSession, agent_id: str, session_id: str, request_id: str
    ) -> ApprovalRequest | None:
        return await self._approval_store.get(
            session, agent_id, session_id, request_id, for_update=False
        )

    async def removal_reason(
        self, session: AsyncSession, user_id: str, room_id: str
    ) -> RemovalReason:
        """Why a room left `stream_rooms`: the caller lost it ("access") or is
        still a member of a live room that no longer qualifies ("unlisted")."""
        room = await self._room_store.get(session, room_id)
        if room is None or room.archived_at is not None:
            return "access"
        client = await self.member_client(session, user_id)
        if client is None or not await self._is_in_room(session, client.id, room_id):
            return "access"
        return "unlisted"

    async def list_chats(self, session: AsyncSession, user_id: str) -> list[Room]:
        """`stream_rooms` less the ones the caller hid with nothing said since."""
        rooms = await self.stream_rooms(session, user_id)
        hidden = {
            row.room_id: row.hidden_through_seq
            for row in (
                await session.execute(
                    select(ChatHidden).where(ChatHidden.user_id == user_id)
                )
            ).scalars()
        }
        shown: list[Room] = []
        for room in rooms:
            through = hidden.get(room.id)
            if (
                through is not None
                and await self._last_message_seq(session, room.id) <= through
            ):
                continue
            shown.append(room)
        return shown

    async def _last_message_seq(self, session: AsyncSession, room_id: str) -> int:
        seq = await session.scalar(
            select(Message.seq)
            .where(
                Message.room_id == room_id, Message.event_type.in_(SHOWN_EVENT_TYPES)
            )
            .order_by(Message.seq.desc())
            .limit(1)
        )
        return seq if seq is not None else 0

    async def page(
        self, session: AsyncSession, room_id: str, before_seq: int | None, limit: int
    ) -> tuple[list[Message], int, bool]:
        """Messages before `before_seq` (newest first, returned oldest first),
        the room's head position, and whether older messages remain."""
        return await self._paged(
            session, room_id, Message.room_id == room_id, before_seq, limit
        )

    async def _paged(
        self,
        session: AsyncSession,
        room_id: str,
        where: ColumnElement[bool],
        before_seq: int | None,
        limit: int,
    ) -> tuple[list[Message], int, bool]:
        query = select(Message).where(where, Message.event_type.in_(SHOWN_EVENT_TYPES))
        if before_seq is not None:
            query = query.where(Message.seq < before_seq)
        rows = list(
            (await session.execute(query.order_by(Message.seq.desc()).limit(limit + 1)))
            .scalars()
            .all()
        )
        has_more = len(rows) > limit
        rows = rows[:limit]
        rows.reverse()
        return rows, await self._message_store.head_seq(session, room_id), has_more

    async def thread_page(
        self,
        session: AsyncSession,
        room: Room,
        root_id: str,
        before_seq: int | None,
        limit: int,
    ) -> tuple[list[Message], int, bool]:
        """`page` for the replies in one thread of this room, the root not
        among them. A reply's id names its thread's root."""
        found = await self._message_store.list_by_transport_event_ids(
            session, room.id, [root_id]
        )
        if not found:
            raise ChatError(
                404, "THREAD_NOT_FOUND", "That message is not in this chat."
            )
        root = found[0].thread_root_event_id or found[0].transport_event_id
        return await self._paged(
            session,
            room.id,
            and_(Message.room_id == room.id, Message.thread_root_event_id == root),
            before_seq,
            limit,
        )

    async def read_position(
        self, session: AsyncSession, user_id: str, room_id: str
    ) -> int:
        """How far the user has read the room (set to its head as they joined),
        or its head when nothing is recorded."""
        seq = await session.scalar(
            select(ChatRead.read_through_seq).where(
                ChatRead.user_id == user_id, ChatRead.room_id == room_id
            )
        )
        return seq if seq is not None else await self.head_seq(session, room_id)

    async def head_seq(self, session: AsyncSession, room_id: str) -> int:
        return await self._message_store.head_seq(session, room_id)

    async def messages_after(
        self, session: AsyncSession, room_id: str, after_seq: int, limit: int
    ) -> list[Message]:
        """Every row after `after_seq`, conversation or not, oldest first."""
        return await self._message_store.list_for_room(
            session, room_id, after_seq=after_seq, limit=limit
        )

    async def members(
        self, session: AsyncSession, room: Room
    ) -> list[tuple[User, bool]]:
        result = await session.execute(
            select(User)
            .join(Client, Client.user_id == User.id)
            .join(ClientRoom, ClientRoom.client_id == Client.id)
            .where(
                ClientRoom.room_id == room.id,
                Client.type == MEMBER_CLIENT_TYPE,
                Client.tenant_id == room.tenant_id,
            )
            .order_by(User.name)
        )
        return [(user, user.id == room.owner_id) for user in result.scalars().all()]

    async def media(self, session: AsyncSession, room: Room, uri: str) -> MediaBlob:
        """The bytes behind `uri`, only when a message in this room carries it."""
        carried = await session.scalar(
            select(
                exists().where(
                    MessageAttachment.uri == uri,
                    MessageAttachment.message_id == Message.id,
                    Message.room_id == room.id,
                )
            )
        )
        blob = await self._media_store.get(session, uri) if carried else None
        if blob is None:
            raise ChatError(404, "MEDIA_NOT_FOUND", "No such file in this chat.")
        return blob

    # ── Joining and leaving ──────────────────────────────────────────────────

    async def _join(self, tenant_id: str, room: Room, client: Client) -> None:
        """Put the member client in the room; already in is success."""
        with tenant_scope(tenant_id):
            await self._provisioning.invite_to_room(
                room.transport_room_id, client.transport_user_id
            )

    async def _require_tenant_member(
        self, session: AsyncSession, tenant_id: str, user_id: str
    ) -> User:
        user = await self._user_store.get(session, user_id)
        if user is None or not await self.has_tenant_role(session, tenant_id, user_id):
            raise ChatError(
                422,
                "NOT_A_TENANT_MEMBER",
                "That person is not a member of this workspace.",
            )
        if is_bootstrap_owner(user):
            raise ChatError(422, "NOT_A_PERSON", "That account can't join chats.")
        return user

    async def require_can_join(self, tenant_id: str, user_id: str) -> None:
        """Raise the ChatError `add_member` would refuse this person with, for
        a caller that must know before it makes the room."""
        async with tenant_session(self.session_factory, tenant_id) as session:
            await self._require_tenant_member(session, tenant_id, user_id)

    async def _make_group(self, session: AsyncSession, room: Room) -> None:
        """Turn a Switch Console direct chat into a group, for good.

        Written in the transaction that adds the person or agent, with the
        room row locked, so no message routes as direct once the room has
        them and a failed add leaves the chat as it was. A bridged room's
        type is its platform's and is never touched.
        """
        if room.channel_type != "direct" or "chat_operation_id" not in (
            room.metadata_ or {}
        ):
            return
        await session.execute(
            update(Room)
            .where(Room.id == room.id, Room.channel_type == "direct")
            .values(channel_type="channel_private")
        )
        room.channel_type = "channel_private"

    async def add_member(
        self, tenant_id: str, actor: User, room_id: str, target_user_id: str
    ) -> Room:
        async with tenant_session(self.session_factory, tenant_id) as session:
            room = await self._room(session, tenant_id, room_id)
            await self._require_manager(session, tenant_id, actor, room)
            target = await self._require_tenant_member(
                session, tenant_id, target_user_id
            )
        client = await self.member_actor(tenant_id, target)
        async with tenant_session(self.session_factory, tenant_id) as session:
            room = await self._locked_room(session, room.id)
            # The creator is the direct chat's own person; anyone else makes a group.
            if target_user_id not in (room.created_by, room.owner_id):
                await self._make_group(session, room)
            with tenant_scope(tenant_id):
                joined = await self._provisioning.record_join(
                    session, room.transport_room_id, client.transport_user_id
                )
            await self._start_reading(session, room.id, [target_user_id])
            await session.commit()
        joined()
        await self._make_lasting(tenant_id, target_user_id, room.id)
        async with tenant_session(self.session_factory, tenant_id) as session:
            member_ids = [member.id for member, _ in await self.members(session, room)]
        self._memberships_changed(tenant_id, member_ids, [room.id])
        return room

    async def remove_member(
        self, tenant_id: str, actor: User, room_id: str, target_user_id: str
    ) -> None:
        async with tenant_session(self.session_factory, tenant_id) as session:
            if actor.id == target_user_id:
                room, client = await self.require_member(
                    session, tenant_id, actor, room_id
                )
            else:
                room = await self._room(session, tenant_id, room_id)
                await self._require_manager(session, tenant_id, actor, room)
                found = await self.member_client(session, target_user_id)
                if found is None or not await self._is_in_room(
                    session, found.id, room.id
                ):
                    return
                client = found
            if await self.joins_as_owner(session, target_user_id, room.id):
                raise ChatError(
                    409,
                    "AGENT_OWNER",
                    (
                        "You own an agent in this chat, so you stay in it while "
                        "the agent does. You can remove it from your list instead."
                    )
                    if actor.id == target_user_id
                    else (
                        "They own an agent in this chat, so they stay in it "
                        "while the agent does."
                    ),
                )
        with tenant_scope(tenant_id):
            await self._provisioning.kick_user(
                room.transport_room_id, client.transport_user_id
            )
        await self._make_lasting(tenant_id, target_user_id, room.id)
        async with tenant_session(self.session_factory, tenant_id) as session:
            member_ids = [member.id for member, _ in await self.members(session, room)]
        self._memberships_changed(tenant_id, [target_user_id, *member_ids], [room.id])

    async def add_agent(
        self, tenant_id: str, actor: User, room_id: str, agent_id: str
    ) -> Room:
        """Manager only, and only an agent the manager may use in this room.
        Already in is success. A second agent makes a direct chat a group."""
        self._require_group_chats()
        async with tenant_session(self.session_factory, tenant_id) as session:
            room = await self._room(session, tenant_id, room_id)
            await self._require_manager(session, tenant_id, actor, room)
            await self._require_may_use_agent(
                session,
                tenant_id,
                actor,
                agent_id,
                room_id=room.id,
                group_id=room.group_id,
            )
            if agent_id in await self._room_store.get_agent_ids(session, room.id):
                return room
        await self._room_service.add_agents_to_room(
            room.id,
            agent_ids=[agent_id],
            with_agents=lambda session: self._group_if_several_agents(session, room),
        )
        async with tenant_session(self.session_factory, tenant_id) as session:
            return await self._room(session, tenant_id, room_id)

    async def _locked_room(self, session: AsyncSession, room_id: str) -> Room:
        """The room row, locked against another membership change until this
        transaction ends. `FOR NO KEY UPDATE`, which the key-share lock an
        insert referencing the room takes does not conflict with."""
        locked = await session.scalar(
            select(Room)
            .where(Room.id == room_id)
            .with_for_update(key_share=True)
            .execution_options(populate_existing=True)
        )
        assert locked is not None
        return locked

    async def _group_if_several_agents(self, session: AsyncSession, room: Room) -> None:
        """`_make_group` once the room holds more than one agent, in the
        transaction that added the agent. The room row is locked before counting, so a
        concurrent add counts this one's agent once this one commits."""
        locked = await self._locked_room(session, room.id)
        if len(await self._room_store.get_agent_ids(session, room.id)) > 1:
            await self._make_group(session, locked)

    async def remove_agent(
        self, tenant_id: str, actor: User, room_id: str, agent_id: str
    ) -> None:
        """Manager only, with no check on using the agent, so an unwanted
        agent can always be taken out. Already gone is success."""
        self._require_group_chats()
        async with tenant_session(self.session_factory, tenant_id) as session:
            room = await self._room(session, tenant_id, room_id)
            await self._require_manager(session, tenant_id, actor, room)
            if agent_id not in await self._room_store.get_agent_ids(session, room.id):
                return
        await self._room_service.remove_agents_from_room(room.id, [agent_id])

    async def archive(self, tenant_id: str, user: User, room_id: str) -> None:
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, _ = await self.require_member(session, tenant_id, user, room_id)
            await self._require_manager(session, tenant_id, user, room)
            member_ids = [member.id for member, _ in await self.members(session, room)]
        await self._room_service.set_room_archived(room.id, True)
        self._memberships_changed(tenant_id, member_ids, [room.id])

    async def unarchive(self, tenant_id: str, user: User, room_id: str) -> None:
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, _ = await self.require_member(session, tenant_id, user, room_id)
            await self._require_manager(session, tenant_id, user, room)
            member_ids = [member.id for member, _ in await self.members(session, room)]
        await self._room_service.set_room_archived(room.id, False)
        self._memberships_changed(tenant_id, member_ids, [room.id])

    async def _start_reading(
        self, session: AsyncSession, room_id: str, user_ids: list[str]
    ) -> None:
        """Mark the room read up to its head for people joining it, so what
        was said before they arrived is not unread to them."""
        await self._read_through(
            session,
            room_id,
            user_ids,
            await self._message_store.head_seq(session, room_id),
        )

    async def _read_through(
        self, session: AsyncSession, room_id: str, user_ids: list[str], seq: int
    ) -> None:
        if not user_ids:
            return
        insert = pg_insert(ChatRead).values(
            [
                {
                    "tenant_id": require_tenant_id(),
                    "user_id": user_id,
                    "room_id": room_id,
                    "read_through_seq": seq,
                }
                for user_id in user_ids
            ]
        )
        await session.execute(
            insert.on_conflict_do_update(
                index_elements=["tenant_id", "user_id", "room_id"],
                set_={
                    "read_through_seq": func.greatest(
                        ChatRead.read_through_seq, insert.excluded.read_through_seq
                    ),
                    "updated_at": func.now(),
                },
            )
        )

    async def mark_read(
        self, tenant_id: str, user: User, room_id: str, seq: int
    ) -> None:
        """The caller has been shown the room up to `seq`. Never moves their
        place back; a position past the room's head is refused."""
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, _ = await self.require_member(session, tenant_id, user, room_id)
            if seq < 0 or seq > await self._message_store.head_seq(session, room.id):
                raise ChatError(
                    422, "SEQ_OUT_OF_RANGE", "That position is not in this chat."
                )
            await self._read_through(session, room.id, [user.id], seq)
            await session.commit()
        self._memberships_changed(tenant_id, [user.id], [room.id])

    async def set_hidden(
        self, tenant_id: str, user: User, room_id: str, hidden: bool
    ) -> None:
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, _ = await self.require_member(session, tenant_id, user, room_id)
            if hidden:
                through = await self._message_store.head_seq(session, room.id)
                await session.execute(
                    pg_insert(ChatHidden)
                    .values(
                        tenant_id=tenant_id,
                        user_id=user.id,
                        room_id=room.id,
                        hidden_through_seq=through,
                    )
                    .on_conflict_do_update(
                        index_elements=["tenant_id", "user_id", "room_id"],
                        set_={"hidden_through_seq": through},
                    )
                )
            else:
                await session.execute(
                    delete(ChatHidden).where(
                        ChatHidden.user_id == user.id, ChatHidden.room_id == room.id
                    )
                )
            await session.commit()

    # ── Operations ───────────────────────────────────────────────────────────

    async def _operation(
        self, session: AsyncSession, user_id: str, request_id: str
    ) -> ChatOperation | None:
        return await session.get(
            ChatOperation, (require_tenant_id(), user_id, request_id)
        )

    @staticmethod
    def _require_same(operation: ChatOperation, kind: str, payload_hash: str) -> None:
        if operation.kind != kind or operation.payload_hash != payload_hash:
            raise ChatError(
                409,
                "REQUEST_REUSED",
                "This request id was already used for a different request.",
            )

    async def _claim(
        self,
        session: AsyncSession,
        *,
        tenant_id: str,
        user_id: str,
        request_id: str,
        kind: str,
        payload_hash: str,
        state: str,
        room_id: str | None,
    ) -> bool:
        """Insert the operation row; False when one already holds the key.

        A concurrent attempt with the same key waits here for the first to
        commit or roll back, so at most one of them goes on to act.
        """
        claimed = await session.scalar(
            pg_insert(ChatOperation)
            .values(
                tenant_id=tenant_id,
                user_id=user_id,
                request_id=request_id,
                kind=kind,
                payload_hash=payload_hash,
                state=state,
                room_id=room_id,
            )
            .on_conflict_do_nothing(
                index_elements=["tenant_id", "user_id", "request_id"]
            )
            .returning(ChatOperation.request_id)
        )
        return claimed is not None

    async def _require_may_use_agent(
        self,
        session: AsyncSession,
        tenant_id: str,
        user: User,
        agent_id: str,
        *,
        room_id: str,
        group_id: str | None,
    ) -> Agent:
        """The agent, if the user may address it themselves in `room_id`.

        The rule the platform applies when it speaks for a person. Asked
        before a new room exists, `room_id` is "": a rule naming particular
        rooms admits nobody into a new one. No claimed platform account is
        consulted.
        """
        agent = await self._agent_store.get(session, agent_id)
        if agent is None or agent.tenant_id != tenant_id:
            raise ChatError(404, "AGENT_NOT_FOUND", "Agent not found.")
        if not _may_use(agent, user, room_id=room_id, group_id=group_id):
            raise ChatError(
                403, "AGENT_NOT_ALLOWED", "You may not chat with this agent here."
            )
        return agent

    async def agent_candidates(
        self, session: AsyncSession, tenant_id: str, user: User, room_id: str | None
    ) -> list[str]:
        """The ids of the agents the user could add: to a new chat when
        `room_id` is None, else to that room, which they must manage, less
        the agents already in it. The rule `_require_may_use_agent` applies."""
        self._require_group_chats()
        target_room_id, group_id, present = "", None, set[str]()
        if room_id is not None:
            room = await self._room(session, tenant_id, room_id)
            await self._require_manager(session, tenant_id, user, room)
            target_room_id, group_id = room.id, room.group_id
            present = set(await self._room_store.get_agent_ids(session, room.id))
        agents = (
            await session.execute(
                select(Agent).where(Agent.tenant_id == tenant_id).order_by(Agent.name)
            )
        ).scalars()
        return [
            agent.id
            for agent in agents
            if agent.id not in present
            and _may_use(agent, user, room_id=target_room_id, group_id=group_id)
        ]

    def _operation_id(self, tenant_id: str, user_id: str, request_id: str) -> str:
        return str(uuid.uuid5(_CHATS_NAMESPACE, f"{tenant_id}:{user_id}:{request_id}"))

    async def create_chat(
        self,
        tenant_id: str,
        user: User,
        *,
        agent_ids: list[str],
        member_user_ids: list[str],
        name: str | None,
        request_id: str,
        greeting: str | None,
        kind: Literal["group"] | None,
        bridge_id: str | None,
        resume_only: bool,
    ) -> Room:
        """A private room with the agents and members, owned by and joined by
        the user.

        One agent and no other member makes a direct room, which addresses
        the agent without a mention, unless `kind` asks for a group. Anything
        else is a group (a private channel), where a message names the agents
        it is for. Every agent must
        be one the user may address; every member a member of the workspace.

        Retrying with the same request id finishes whatever an earlier attempt
        left undone: the room is found by the operation id stamped on it, and
        the agents' and the user's memberships are re-applied.

        `greeting` is what the agent says as it joins, in place of its usual
        one-liner: its first words, written for it (switch-buddy's welcome).
        Only for a direct chat with one of the user's own agents.

        `bridge_id` makes the direct chat a private channel on that bridge
        between the user's own linked account there and the agent.

        `resume_only` only finishes a create this request id already started;
        when it started none, nothing is made and the chat is 404.
        """
        member_user_ids = sorted(set(member_user_ids) - {user.id})
        direct = kind != "group" and len(agent_ids) == 1 and not member_user_ids
        if bridge_id is not None and not self.buddy_slack_handoff_enabled:
            raise ChatError(
                409,
                "BUDDY_SLACK_HANDOFF_OFF",
                "Chats on a messaging app are not turned on here.",
            )
        if bridge_id is not None and not direct:
            raise ChatError(
                422,
                "BRIDGED_CHAT_NEEDS_ONE_AGENT",
                "A chat on a bridge is a direct chat with one agent and nobody else.",
            )
        if member_user_ids or kind == "group" or not agent_ids:
            self._require_group_chats()
        if greeting is not None:
            if len(agent_ids) != 1 or kind == "group":
                raise ChatError(
                    422,
                    "GREETING_NEEDS_ONE_AGENT",
                    "Only a direct chat with one agent opens with its greeting.",
                )
            if not greeting.strip():
                raise ChatError(422, "EMPTY_MESSAGE", "The greeting is empty.")
            if len(greeting) > GREETING_MAX_CHARS:
                raise ChatError(
                    422,
                    "GREETING_TOO_LONG",
                    f"A greeting is at most {GREETING_MAX_CHARS} characters.",
                )
        request: dict[str, object] = (
            {"agentId": agent_ids[0], "name": name}
            if len(agent_ids) == 1 and greeting is None
            else {"agentId": agent_ids[0], "name": name, "greeting": greeting}
            if len(agent_ids) == 1
            else {"agentIds": agent_ids, "name": name}
        )
        if member_user_ids:
            request["memberUserIds"] = member_user_ids
        # Only when given, so a request without it hashes as it always has.
        if kind is not None:
            request["kind"] = kind
        if bridge_id is not None:
            # The greeting's text changes between app versions; a retry must
            # still match the request it repeats.
            request.pop("greeting", None)
            request["bridgeId"] = bridge_id
        payload_hash = _hash(request)
        async with self._lock("create", tenant_id, user.id):
            async with tenant_session(self.session_factory, tenant_id) as session:
                operation = await self._operation(session, user.id, request_id)
                if operation is None and resume_only:
                    raise ChatError(
                        404,
                        "NO_SUCH_OPERATION",
                        "No chat was started with this request id, so there is none to resume.",
                    )
                if operation is not None:
                    self._require_same(operation, "create_chat", payload_hash)
                    if operation.state == "done" and operation.room_id is not None:
                        room, _ = await self.require_member(
                            session, tenant_id, user, operation.room_id
                        )
                        return room
                agents = [
                    await self._require_may_use_agent(
                        session, tenant_id, user, agent_id, room_id="", group_id=None
                    )
                    for agent_id in agent_ids
                ]
                members = [
                    await self._require_tenant_member(session, tenant_id, member_id)
                    for member_id in member_user_ids
                ]
                if greeting is not None and agents[0].owner_id != user.id:
                    raise ChatError(
                        403,
                        "NOT_AGENT_OWNER",
                        "Only the agent's owner can give it a greeting.",
                    )
                linked = (
                    await self._linked_account(session, user.id, bridge_id)
                    if bridge_id is not None
                    else None
                )
                if bridge_id is not None and name is None:
                    bridge = await session.get(CollaborationBridge, bridge_id)
                    assert bridge is not None  # _linked_account found it
                    name = f"{agents[0].display_name or agents[0].name} · {bridge.display_name}"
                if operation is None:
                    claimed = await self._claim(
                        session,
                        tenant_id=tenant_id,
                        user_id=user.id,
                        request_id=request_id,
                        kind="create_chat",
                        payload_hash=payload_hash,
                        state="pending",
                        room_id=None,
                    )
                    await session.commit()
                    if not claimed:
                        # The same request id, claimed first elsewhere: it has to
                        # be the same request before anything is done for it.
                        operation = await self._operation(session, user.id, request_id)
                        assert operation is not None
                        self._require_same(operation, "create_chat", payload_hash)
                        if operation.state == "done" and operation.room_id is not None:
                            room, _ = await self.require_member(
                                session, tenant_id, user, operation.room_id
                            )
                            return room
            operation_id = self._operation_id(tenant_id, user.id, request_id)
            async with self._provisioning_one_at_a_time(tenant_id, operation_id):
                async with tenant_session(self.session_factory, tenant_id) as session:
                    found = await self._room_of_operation(session, operation_id)
                if found is None:
                    names = ", ".join(
                        [agent.name for agent in agents]
                        + [member.name for member in members]
                    )
                    try:
                        # shortcut: a crash or lost Slack response after the channel exists but before the room is saved leaves an orphan channel and a retry makes a second one; add adoption if this shows up.
                        created = await self._room_service.create_room(
                            RoomCreateConfig(
                                name=name or "New Chat",
                                description=(
                                    f"Switch Console chat with {names}"
                                    if names
                                    else "Switch Console chat"
                                ),
                                agent_ids=[agent.id for agent in agents],
                                channel_type="direct" if direct else "channel_private",
                                internal_only=bridge_id is None,
                                bridge_id=bridge_id,
                                user_names=[linked[0]] if linked else None,
                                user_external_id=linked[1] if linked else None,
                                created_by=user.id,
                                owner_id=user.id,
                                read_visibility="private",
                                write_visibility="private",
                                acting_user_id=user.id,
                                created_by_kind="user",
                                chat_operation_id=operation_id,
                                agent_greeting=(
                                    {"agent_id": agents[0].id, "body": greeting}
                                    if greeting is not None
                                    else None
                                ),
                            )
                        )
                    except ValueError as exc:
                        raise ChatError(422, "CHAT_NOT_CREATED", str(exc)) from exc
                    room = created.room
                else:
                    room = found
                    opened_for = (room.metadata_ or {}).get("user_external_id")
                    if linked and opened_for is not None and opened_for != linked[1]:
                        raise ChatError(
                            409,
                            "LINKED_ACCOUNT_CHANGED",
                            "This chat was started with a different linked "
                            "account than the one now linked. Start a new chat.",
                        )
                    await self._room_service.reconcile_room(
                        room, [linked[1]] if linked else []
                    )
            for joiner in [user, *members]:
                client = await self.member_actor(tenant_id, joiner)
                await self._join(tenant_id, room, client)
                await self._make_lasting(tenant_id, joiner.id, room.id)
            async with tenant_session(self.session_factory, tenant_id) as session:
                await self._start_reading(
                    session, room.id, [joiner.id for joiner in [user, *members]]
                )
                await session.execute(
                    update(ChatOperation)
                    .where(
                        ChatOperation.tenant_id == tenant_id,
                        ChatOperation.user_id == user.id,
                        ChatOperation.request_id == request_id,
                    )
                    .values(state="done", room_id=room.id, result={"roomId": room.id})
                )
                await session.commit()
        self._memberships_changed(tenant_id, [user.id, *member_user_ids], [room.id])
        if len(agents) == 1:
            self._start_session(agents[0].id, room.id)
        return room

    @asynccontextmanager
    async def _provisioning_one_at_a_time(
        self, tenant_id: str, operation_id: str
    ) -> AsyncIterator[None]:
        """At most one attempt at an operation's room at once, across every
        server process: a session-level advisory lock, released with the
        connection if the process dies."""
        key = func.hashtext(f"chat-create:{operation_id}")
        async with tenant_session(self.session_factory, tenant_id) as session:
            await session.execute(select(func.pg_advisory_lock(key)))
            try:
                yield
            finally:
                await session.execute(select(func.pg_advisory_unlock(key)))

    @staticmethod
    async def _linked_account(
        session: AsyncSession, user_id: str, bridge_id: str
    ) -> tuple[str, str]:
        """The user's own account on the bridge as (username, external user
        id), from the identity they linked there; never one the client names."""
        bridge = await session.get(CollaborationBridge, bridge_id)
        if bridge is None or bridge.tenant_id != require_tenant_id():
            raise ChatError(404, "BRIDGE_NOT_FOUND", "No such bridge.")
        linked = [
            external
            for external in await ExternalUserStore().get_by_user(session, user_id)
            if external.bridge_id == bridge_id
        ]
        if not linked:
            raise ChatError(
                422,
                "ACCOUNT_NOT_LINKED",
                f"Your Switch account is not linked to an account on "
                f"{bridge.display_name}. Link it in your Switch settings, then "
                "try again.",
            )
        if len(linked) > 1:
            # Which one opens the DM must not depend on row order, here or on a retry.
            raise ChatError(
                409,
                "ACCOUNTS_AMBIGUOUS",
                f"Your Switch account is linked to {len(linked)} accounts on "
                f"{bridge.display_name}. Unlink the ones you no longer use in "
                "your Switch settings, then try again.",
            )
        return linked[0].external_username, linked[0].external_user_id

    async def _room_of_operation(
        self, session: AsyncSession, operation_id: str
    ) -> Room | None:
        return (
            await session.execute(
                select(Room).where(
                    Room.metadata_["chat_operation_id"].astext == operation_id
                )
            )
        ).scalar_one_or_none()

    async def stage_upload(
        self,
        tenant_id: str,
        user: User,
        room_id: str,
        *,
        upload_id: str,
        data: bytes,
        filename: str,
        mimetype: str,
    ) -> StagedUpload:
        """Store a file for a later send, keyed by the caller's upload id."""
        mimetype = normalise_mime_type(mimetype) or "application/octet-stream"
        if not data:
            raise ChatError(422, "ATTACHMENT_REFUSED", f"'{filename}' is empty.")
        if len(data) > self._media_max_bytes:
            raise ChatError(
                422,
                "ATTACHMENT_REFUSED",
                f"'{filename}' is {len(data)} bytes, over the "
                f"{self._media_max_bytes}-byte limit.",
            )
        key = _upload_key(upload_id)
        payload_hash = _hash(
            {
                "roomId": room_id,
                "filename": filename,
                "mimetype": mimetype,
                "sha256": hashlib.sha256(data).hexdigest(),
            }
        )
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, _ = await self.require_member(session, tenant_id, user, room_id)
            if await self._claim(
                session,
                tenant_id=tenant_id,
                user_id=user.id,
                request_id=key,
                kind="upload",
                payload_hash=payload_hash,
                state="done",
                room_id=room.id,
            ):
                uri = f"switch-media://{uuid.uuid4().hex}"
                await self._media_store.put(
                    session,
                    MediaBlob(
                        uri=uri,
                        content_type=mimetype,
                        filename=filename,
                        size=len(data),
                        data=data,
                    ),
                )
                staged = StagedUpload(upload_id, uri, filename, mimetype, len(data))
                await session.execute(
                    update(ChatOperation)
                    .where(
                        ChatOperation.tenant_id == tenant_id,
                        ChatOperation.user_id == user.id,
                        ChatOperation.request_id == key,
                    )
                    .values(result=_staged_result(staged))
                )
                await session.commit()
                return staged
            operation = await self._operation(session, user.id, key)
            assert operation is not None
            self._require_same(operation, "upload", payload_hash)
            return _staged(upload_id, operation)

    async def send(
        self,
        tenant_id: str,
        user: User,
        room_id: str,
        *,
        request_id: str,
        body: str,
        thread_root_id: str | None,
        upload_ids: list[str],
        mention_agent_id: str | None,
        mention_agent_ids: list[str],
        mention_user_ids: list[str],
        mention_spans: list[ChatMention],
    ) -> tuple[Room, list[Message]]:
        """Post the user's message, every part of it in one transaction.

        Files are staged first (`stage_upload`), so all that is left here is
        writing rows: each part, and the operation marked done, commit
        together or not at all. A retry after a failure before the commit
        posts it once; one after the commit answers the parts already posted.

        The agents the message is for are `mention_agent_ids` together with
        `mention_agent_id`, the one earlier clients send, as a set. The people
        it names, `mention_user_ids`, address no agent (`MENTIONS_KEY`).
        `mention_spans` say where in `body` each mention is written (UTF-16
        offsets, as the Console's strings count); an agent's span is for it as
        `mention_agent_ids` is, a person's addresses no agent.

        Switch Trust checks the text and each file first, as it does a
        message from any other platform, and a refusal of either raises
        ChatError TRUST_BLOCKED with nothing posted.
        """
        mentions = sorted(set(mention_agent_ids))
        people = sorted(set(mention_user_ids))
        if people or mention_spans:
            self._require_group_chats()
        typed = _span_texts(body, mention_spans)
        request: dict[str, object] = {
            "roomId": room_id,
            "body": body,
            "threadRootId": thread_root_id,
            "uploadIds": upload_ids,
            "mentionAgentId": mention_agent_id,
        }
        if mentions:
            request["mentionAgentIds"] = mentions
        if people:
            request["mentionUserIds"] = people
        if mention_spans:
            request["mentionSpans"] = [span.model_dump() for span in mention_spans]
        payload_hash = _hash(request)
        if mention_agent_id is not None:
            mentions = sorted({*mentions, mention_agent_id})
        mentions = sorted(
            {*mentions, *(span.id for span in mention_spans if span.kind == "agent")}
        )
        people = sorted(
            {*people, *(span.id for span in mention_spans if span.kind == "user")}
        )
        body = await self._checked_by_trust(
            tenant_id,
            user,
            room_id,
            request_id=request_id,
            body=body,
            upload_ids=upload_ids,
        )
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, client = await self.require_member(session, tenant_id, user, room_id)
            operation = await self._operation(session, user.id, request_id)
            if operation is not None:
                self._require_same(operation, "send", payload_hash)
                return room, await self._posted(session, room, operation)

            unarchive = room.archived_at is not None
            if unarchive and not await self.can_manage(session, tenant_id, user, room):
                raise ChatError(
                    403,
                    "NOT_A_MANAGER",
                    "This chat is archived. Only its owner or a workspace admin "
                    "can bring it back by writing in it.",
                )
            if not body.strip() and not upload_ids:
                raise ChatError(422, "EMPTY_MESSAGE", "There is nothing to send.")
            uploads = [
                await self._staged_upload(session, user.id, room.id, upload_id)
                for upload_id in upload_ids
            ]
            root = await self._thread_root(session, room, thread_root_id)
            shift = 0
            if mentions:
                written = body
                body = await self._with_mentions(session, room, mentions, body)
                if body != written:
                    shift = _utf16_len(body) - _utf16_len(written)
            named_people = await self._named_people(
                session,
                room,
                people,
                mentions,
                [
                    text[1:]
                    for text, span in zip(typed, mention_spans, strict=True)
                    if span.kind == "user"
                ],
                [
                    {**span.model_dump(), "offset": span.offset + shift}
                    for span in mention_spans
                ],
            )

            if not await self._claim(
                session,
                tenant_id=tenant_id,
                user_id=user.id,
                request_id=request_id,
                kind="send",
                payload_hash=payload_hash,
                state="done",
                room_id=room.id,
            ):
                operation = await self._operation(session, user.id, request_id)
                assert operation is not None
                self._require_same(operation, "send", payload_hash)
                return room, await self._posted(session, room, operation)

            contents = _parts(
                body,
                uploads,
                sender_name=user.name,
                thread_root_id=root,
                group_id=str(
                    uuid.uuid5(
                        _CHATS_NAMESPACE,
                        f"{tenant_id}:{client.id}:{room.id}:{request_id}",
                    )
                ),
            )
            if named_people is not None:
                contents[0][MENTIONS_KEY] = named_people
            posted: list[Message] = []
            routed: list[Routed] = []
            for index, content in enumerate(contents):
                message = message_row(
                    room_id=room.id,
                    event_id=new_event_id(),
                    sender_id=client.transport_user_id,
                    sender_client_id=client.id,
                    sender_name=user.name,
                    event_type=MESSAGE_EVENT_TYPE,
                    content=content,
                    client_txn_id=f"{request_id}:{index}",
                )
                routed.append(
                    await self._router.store(
                        session,
                        tenant_id=tenant_id,
                        room_id=room.id,
                        transport_room_id=room.transport_room_id,
                        message=message,
                        attachments=attachments_in(content),
                    )
                )
                posted.append(message)
            await self._usage_store.record(
                session,
                tenant_id=tenant_id,
                metric=UsageMetric.MESSAGES,
                client_id=client.id,
                model="",
                amount=len(posted),
            )
            await session.execute(
                update(ChatOperation)
                .where(
                    ChatOperation.tenant_id == tenant_id,
                    ChatOperation.user_id == user.id,
                    ChatOperation.request_id == request_id,
                )
                .values(result={"messageIds": [m.transport_event_id for m in posted]})
            )
            if unarchive:
                await self._room_store.set_archived(session, room.id, False)
            await session.commit()
        if unarchive:
            self._room_service.room_changed(tenant_id, room.id)
        for each in routed:
            each.committed()
        for content in contents:
            metrics().increment(
                MESSAGES_SENT,
                {"kind": "media" if "url" in content else "message", "actor": "human"},
            )
        return room, posted

    async def control(
        self,
        tenant_id: str,
        user: User,
        room_id: str,
        *,
        request_id: str,
        agent_id: str,
        command: RoomControl,
        message_id: str | None,
    ) -> str:
        """Post `!<command> @agent` as the user; the command's event id.

        `retry` names the room message whose turn to run again (`message_id`):
        one the agent took a turn for, sent by the caller or in a room the
        caller manages. It is posted as `!retry @agent <message id>`.

        Written as the `com.switch.command` event a platform bridge writes for
        a typed `!interrupt`, so the agents' own command handling, addressing
        gate and in-room acknowledgement apply unchanged. The addressing check
        here only turns a refusal into an answer instead of a room message.
        """
        if (command == "retry") != (message_id is not None):
            raise ChatError(
                422,
                "INVALID_CONTROL",
                "A retry names the message to run again, and only a retry does.",
            )
        payload_hash = _hash(
            {
                "roomId": room_id,
                "agentId": agent_id,
                "command": command,
                **({"messageId": message_id} if message_id is not None else {}),
            }
        )
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, client = await self.require_member(session, tenant_id, user, room_id)
            operation = await self._operation(session, user.id, request_id)
            if operation is not None:
                self._require_same(operation, "control", payload_hash)
                return str((operation.result or {})["commandId"])

            if agent_id not in await self._room_store.get_agent_ids(session, room.id):
                raise ChatError(
                    422, "AGENT_NOT_IN_CHAT", "That agent is not in this chat."
                )
            agent = await self._agent_store.get(session, agent_id)
            assert agent is not None
            decision = await self._addressing.permitted(
                session, agent=agent, room_id=room.id, sender=client.transport_user_id
            )
            if not decision.allowed:
                raise ChatError(403, "AGENT_NOT_ALLOWED", decision.refusal)
            if command == "retry":
                assert message_id is not None
                await self._require_retryable(
                    session, tenant_id, user, room, client, agent, message_id
                )
            # `!interrupt` stops the agent's running turn wherever it runs; this check can race a turn change.
            if command == "interrupt":
                turn = await self._activity_store.newest_running_turn(session, agent.id)
                if turn is None or turn.room_id != room.id:
                    raise ChatError(
                        409,
                        "NOTHING_RUNNING_HERE",
                        f"{agent.name}'s current turn is not in this chat.",
                    )

            if not await self._claim(
                session,
                tenant_id=tenant_id,
                user_id=user.id,
                request_id=request_id,
                kind="control",
                payload_hash=payload_hash,
                state="done",
                room_id=room.id,
            ):
                operation = await self._operation(session, user.id, request_id)
                assert operation is not None
                self._require_same(operation, "control", payload_hash)
                return str((operation.result or {})["commandId"])

            command_id = new_event_id()
            routed = await self._router.store(
                session,
                tenant_id=tenant_id,
                room_id=room.id,
                transport_room_id=room.transport_room_id,
                message=message_row(
                    room_id=room.id,
                    event_id=command_id,
                    sender_id=client.transport_user_id,
                    sender_client_id=client.id,
                    sender_name=user.name,
                    event_type=COMMAND_EVENT_TYPE,
                    content={
                        "command": command,
                        "args": f"@{agent.name}"
                        + (f" {message_id}" if message_id is not None else ""),
                        "user_id": client.transport_user_id,
                        "user_name": user.name,
                    },
                    client_txn_id=request_id,
                ),
                attachments=[],
            )
            await session.execute(
                update(ChatOperation)
                .where(
                    ChatOperation.tenant_id == tenant_id,
                    ChatOperation.user_id == user.id,
                    ChatOperation.request_id == request_id,
                )
                .values(result={"commandId": command_id})
            )
            await session.commit()
        routed.committed()
        return command_id

    async def _require_retryable(
        self,
        session: AsyncSession,
        tenant_id: str,
        user: User,
        room: Room,
        client: Client,
        agent: Agent,
        message_id: str,
    ) -> None:
        """Refuse a retry of anything but a message of this room the agent took a
        turn for, asked by whoever sent it or someone who manages the room."""
        message = (
            await session.execute(
                select(Message).where(
                    Message.room_id == room.id,
                    Message.transport_event_id == message_id,
                )
            )
        ).scalar_one_or_none()
        if message is None:
            raise ChatError(
                404, "MESSAGE_NOT_FOUND", "That message is not in this chat."
            )
        if message.sender_client_id != client.id and not await self.can_manage(
            session, tenant_id, user, room
        ):
            raise ChatError(
                403,
                "NOT_YOUR_MESSAGE",
                "Only whoever sent that message, or someone who manages the chat, can retry it.",
            )
        turn = await self._activity_store.turn_for_message(
            session, agent.id, room.id, message_id
        )
        if turn is None:
            raise ChatError(
                409,
                "NOTHING_TO_RETRY",
                f"{agent.name} took no turn for that message, so there is nothing to retry.",
            )
        if turn.status not in RETRYABLE_TURN_STATUSES:
            raise ChatError(
                409,
                "NOTHING_TO_RETRY",
                f"{agent.name}'s turn for that message did not fail and was not "
                "interrupted, so there is nothing to retry.",
            )

    async def warm(
        self, tenant_id: str, user: User, room_id: str, *, agent_id: str
    ) -> None:
        """Ask the controller of the user's own agent to start its session for
        this chat before the first message. A hint: nothing waits for it, and
        an agent no controller hosts is not warmed. The controller is asked
        through whichever process holds its socket
        (`AgentConnectionRegistry.relay_warm`)."""
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, client = await self.require_member(session, tenant_id, user, room_id)
            if agent_id not in await self._room_store.get_agent_ids(session, room.id):
                raise ChatError(
                    422, "AGENT_NOT_IN_CHAT", "That agent is not in this chat."
                )
            agent = await self._agent_store.get(session, agent_id)
            assert agent is not None
            decision = await self._addressing.permitted(
                session, agent=agent, room_id=room.id, sender=client.transport_user_id
            )
            if not decision.allowed:
                raise ChatError(403, "AGENT_NOT_ALLOWED", decision.refusal)
        self._start_session(agent_id, room.id)

    def _start_session(self, agent_id: str, room_id: str) -> None:
        """A hint to a controller-hosted agent: nothing waits for it. An agent
        no controller hosts is started by the Console that runs it."""
        if not self._connections.controllers.is_bound(agent_id):
            return
        if not self._connections.relay_warm(agent_id, room_id):
            logger.warning(
                "Could not start agent %s's session for room %s: its controller is not connected or it is stopped",
                agent_id,
                room_id,
            )

    async def _posted(
        self, session: AsyncSession, room: Room, operation: ChatOperation
    ) -> list[Message]:
        ids = (operation.result or {}).get("messageIds", [])
        rows = await self._message_store.list_by_transport_event_ids(
            session, room.id, ids
        )
        return sorted(rows, key=lambda m: m.seq)

    async def _checked_by_trust(
        self,
        tenant_id: str,
        user: User,
        room_id: str,
        *,
        request_id: str,
        body: str,
        upload_ids: list[str],
    ) -> str:
        """The body to post once Switch Trust has checked it and the files
        (`trust/attachments.py`): redacted if it redacted the text, with a
        note for anything flagged or not checked. Runs before the send's own
        transaction, so no database work waits on Switch Trust."""
        if not await trust_is_active(self._trust_client):
            return body
        async with tenant_session(self.session_factory, tenant_id) as session:
            room, _ = await self.require_member(session, tenant_id, user, room_id)
            if await self._operation(session, user.id, request_id) is not None:
                # A retry: `send` answers it with what was posted the first time.
                return body
            files: list[tuple[bytes, str, str]] = []
            for upload_id in upload_ids:
                upload = await self._staged_upload(session, user.id, room.id, upload_id)
                blob = await self._media_store.get(session, upload.uri)
                if blob is None:
                    raise ChatError(
                        422,
                        "UPLOAD_NOT_FOUND",
                        f"No file was uploaded to this chat as {upload_id}.",
                    )
                files.append((blob.data, upload.filename, upload.mimetype))

        text_check: TrustCheckResult | None = None
        files_check = AttachmentsVerdict()
        if body.strip() and files:
            text_check, files_check = await asyncio.gather(
                check_message(
                    self._trust_client, role="user", content=body, room_id=room.id
                ),
                check_attachments(
                    self._trust_client, role="user", files=files, room_id=room.id
                ),
            )
        elif body.strip():
            text_check = await check_message(
                self._trust_client, role="user", content=body, room_id=room.id
            )
        elif files:
            files_check = await check_attachments(
                self._trust_client, role="user", files=files, room_id=room.id
            )

        if text_check is not None and (
            text_check.blocked
            or (
                text_check.outcome == "redacted" and text_check.redacted_content is None
            )
        ):
            categories = (
                ", ".join(sorted({f.category for f in text_check.findings}))
                or "policy violation"
            )
            logger.warning(
                "Chat message from user %s in room %s not posted: Switch Trust "
                "outcome=%s (%s)",
                user.id,
                room.id,
                text_check.outcome,
                categories,
            )
            raise ChatError(
                422,
                "TRUST_BLOCKED",
                f"Switch Trust blocked this message ({categories}). Nothing was sent.",
            )
        if files_check.blocked:
            reasons = "; ".join(files_check.block_reasons)
            logger.warning(
                "Chat message from user %s in room %s not posted: Switch Trust "
                "blocked its files: %s",
                user.id,
                room.id,
                reasons,
            )
            raise ChatError(
                422,
                "TRUST_BLOCKED",
                f"Switch Trust blocked this message: {reasons}. Nothing was sent.",
            )
        if text_check is not None and text_check.redacted_content is not None:
            body = text_check.redacted_content
        annotation = trust_annotation(text_check) if text_check is not None else None
        notes = [*([annotation] if annotation is not None else []), *files_check.notes]
        if notes:
            notes_text = "\n".join(notes)
            body = f"{body}\n\n{notes_text}" if body.strip() else notes_text
        return body

    async def _staged_upload(
        self, session: AsyncSession, user_id: str, room_id: str, upload_id: str
    ) -> StagedUpload:
        operation = await self._operation(session, user_id, _upload_key(upload_id))
        if (
            operation is None
            or operation.kind != "upload"
            or operation.room_id != room_id
        ):
            raise ChatError(
                422,
                "UPLOAD_NOT_FOUND",
                f"No file was uploaded to this chat as {upload_id}.",
            )
        return _staged(upload_id, operation)

    async def _thread_root(
        self, session: AsyncSession, room: Room, thread_root_id: str | None
    ) -> str | None:
        """The thread a reply goes in: a mid-thread message names its root."""
        if thread_root_id is None:
            return None
        found = await self._message_store.list_by_transport_event_ids(
            session, room.id, [thread_root_id]
        )
        if not found:
            raise ChatError(
                422, "THREAD_NOT_FOUND", "The message to reply to is not in this chat."
            )
        return found[0].thread_root_event_id or found[0].transport_event_id

    async def _named_people(
        self,
        session: AsyncSession,
        room: Room,
        user_ids: list[str],
        agent_ids: list[str],
        typed_names: list[str],
        spans: list[dict[str, object]],
    ) -> dict[str, object] | None:
        """What a send records of the mentions it makes (`MENTIONS_KEY`): the
        people's ids, the names whose `@` spans address no agent (the people's
        names and what their spans say), and where each mention is written.
        A name an agent named in the same send also answers to stays the
        agent's."""
        if not user_ids and not spans:
            return None
        names: dict[str, str] = {
            user_id: name
            for user_id, name in (
                await session.execute(
                    select(User.id, User.name)
                    .join(Client, Client.user_id == User.id)
                    .join(ClientRoom, ClientRoom.client_id == Client.id)
                    .where(
                        ClientRoom.room_id == room.id,
                        Client.type == MEMBER_CLIENT_TYPE,
                        User.id.in_(user_ids),
                    )
                )
            ).all()
        }
        if len(names) != len(user_ids):
            raise ChatError(422, "USER_NOT_IN_CHAT", "That person is not in this chat.")
        aliases = await self._room_store.list_aliases(session, room.id)
        spoken: set[str] = set()
        for agent_id in agent_ids:
            agent = await self._agent_store.get(session, agent_id)
            assert agent is not None
            spoken.add(agent.name.lower())
            if agent_id in aliases:
                spoken.add(aliases[agent_id].lower())
        return {
            "user_ids": user_ids,
            "person_names": sorted(
                {
                    name
                    for name in [*names.values(), *typed_names]
                    if name and name.lower() not in spoken
                }
            ),
            "spans": spans,
        }

    async def _with_mentions(
        self, session: AsyncSession, room: Room, agent_ids: list[str], body: str
    ) -> str:
        """`body` led by an `@name` for each agent it does not already name by
        name or room alias, so every agent decides it was addressed by the
        same rule a typed mention meets."""
        in_room = set(await self._room_store.get_agent_ids(session, room.id))
        if any(agent_id not in in_room for agent_id in agent_ids):
            raise ChatError(422, "AGENT_NOT_IN_CHAT", "That agent is not in this chat.")
        aliases = await self._room_store.list_aliases(session, room.id)
        text = strip_emphasis(body)
        missing: list[str] = []
        for agent_id in agent_ids:
            agent = await self._agent_store.get(session, agent_id)
            assert agent is not None
            spoken = [agent.name, *([aliases[agent_id]] if agent_id in aliases else [])]
            if all(mention_regex(name).search(text) is None for name in spoken):
                missing.append(agent.name)
        prefix = " ".join(f"@{name}" for name in sorted(missing))
        if not prefix:
            return body
        return f"{prefix} {body}" if body else prefix


def _may_use(agent: Agent, user: User, *, room_id: str, group_id: str | None) -> bool:
    """Whether `user` may address `agent` themselves in `room_id` ("" for a
    room not made yet), with no claimed platform account consulted."""
    return allows_on_behalf_of(
        parse_policy(agent.addressing_policy),
        room_id=room_id,
        group_id=group_id,
        user_id=user.id,
        external_user_ids=[],
        owner_user_id=agent.owner_id,
    )


def _utf16_len(text: str) -> int:
    return len(text.encode("utf-16-le")) // 2


def _span_texts(body: str, spans: list[ChatMention]) -> list[str]:
    """What each span covers in `body`, in the spans' order, or a refusal for
    a span out of bounds, splitting a character, overlapping another, or not
    starting with `@`. Offsets and lengths count UTF-16 code units."""
    units = body.encode("utf-16-le")
    refusal = ChatError(422, "INVALID_MENTION", "A mention does not match the message.")
    end = 0
    for span in sorted(spans, key=lambda each: each.offset):
        if (
            span.offset < end
            or span.length < 1
            or span.offset + span.length > len(units) // 2
        ):
            raise refusal
        end = span.offset + span.length
    texts = []
    for span in spans:
        try:
            text = units[span.offset * 2 : (span.offset + span.length) * 2].decode(
                "utf-16-le"
            )
        except UnicodeDecodeError as exc:
            raise refusal from exc
        if not text.startswith("@"):
            raise refusal
        texts.append(text)
    return texts


def _owns_agent_in_room(user_id: str) -> ColumnElement[bool]:
    """True for a `Room` row holding an agent `user_id` owns."""
    return exists().where(
        room_agents.c.room_id == Room.id,
        room_agents.c.agent_id == Agent.id,
        Agent.owner_id == user_id,
    )


def _owner_joins(user_id: str) -> ColumnElement[bool]:
    """True for a `Room` row `sync_owned_rooms` puts `user_id` in: a chat they
    started through the chats API that holds an agent they own."""
    return and_(
        Room.created_by == user_id,
        Room.metadata_.has_key("chat_operation_id"),
        _owns_agent_in_room(user_id),
    )


def _staged_result(staged: StagedUpload) -> dict[str, object]:
    return {
        "uri": staged.uri,
        "filename": staged.filename,
        "mimetype": staged.mimetype,
        "size": staged.size,
    }


def _staged(upload_id: str, operation: ChatOperation) -> StagedUpload:
    result = operation.result or {}
    return StagedUpload(
        upload_id=upload_id,
        uri=str(result["uri"]),
        filename=str(result["filename"]),
        mimetype=str(result["mimetype"]),
        size=int(str(result["size"])),
    )


_PARAGRAPH_TAG = re.compile(r"</?p>")
_HTML_TAG = re.compile(r"<[A-Za-z/!]")


def _format_of(body: str) -> MessageFormat:
    """Markdown only when rendering it adds more than paragraphs.

    A plain sentence stays plain text, so receivers do not get an HTML body
    that says nothing the text does not.
    """
    rendered = _PARAGRAPH_TAG.sub("", markdown.markdown(body))
    return "markdown" if _HTML_TAG.search(rendered) else "text"


def _parts(
    body: str,
    uploads: list[StagedUpload],
    *,
    sender_name: str,
    thread_root_id: str | None,
    group_id: str,
) -> list[dict[str, object]]:
    """The events a send is made of.

    Text alone is one message. With files, the text rides as the caption on
    the first and the rest are bare media events; more than one file shares
    a group so receivers can show them as one post.
    """
    if not uploads:
        return [
            message_content(
                body,
                sender_name=sender_name,
                format=_format_of(body),
                thread_root_id=thread_root_id,
            )
        ]
    total = len(uploads)
    return [
        media_content(
            upload.uri,
            upload.filename,
            upload.mimetype,
            upload.size,
            sender_name=sender_name,
            msgtype="m.image" if upload.mimetype.startswith("image/") else "m.file",
            caption=body if index == 0 and body.strip() else None,
            thread_root_id=thread_root_id,
            group=(
                {"id": group_id, "index": index, "total": total} if total > 1 else None
            ),
        )
        for index, upload in enumerate(uploads)
    ]