Skip to content

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

Replace matrix with simple postgres + LISTEN / NOTIFY, keep matrix to the side (#363)

Louis Amaudruz3affb6539214
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml
index f61363a00..e67ba9c6d 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml
@@ -17,7 +17,7 @@
# docker compose -f standalone-docker-compose.yml -f standalone-docker-compose.build.yml up
#
# Profiles keep optional services opt-in:
-# (core, no profile) postgres, tuwunel, switch — always started
+# (core, no profile) postgres, tuwunel, backfill, switch — always started
# collab init-db, mattermost, setup — Mattermost bridge + seeder
# gateway gateway — operator dashboard
# Select them with `--profile collab --profile gateway` or COMPOSE_PROFILES.
@@ -149,6 +149,54 @@ services:
init-db:
condition: service_completed_successfully
+ # One-shot: reconstructs each room's history from the homeserver into the
+ # message log, then exits. switch waits for it to finish, so the copy is
+ # never racing the server that will serve it.
+ #
+ # It always exits 0, so a backfill that fails delays the stack rather than
+ # keeping it down. The trade is deliberate and it is a real one: a failure
+ # here is only visible in this service's log, and the stack above it will
+ # look healthy while missing history. Backfill is idempotent, so re-running
+ # it after fixing the cause costs nothing.
+ #
+ # It runs alembic first for ordering, not as a second migration owner: the
+ # rows it writes need the schema, and switch (which normally migrates on
+ # boot) is waiting on this. The upgrade is the same idempotent one.
+ #
+ # Rooms already walked to their start are skipped, so this is cheap on every
+ # boot after the first. Nothing to walk at all is success too — a fresh
+ # stack has no rooms and no admin client.
+ backfill:
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required, set it in .env, there is no default}
+ restart: "no"
+ environment:
+ DB_HOST: postgres
+ DB_PORT: "5432"
+ DB_USER: ${DB_USER}
+ DB_PASSWORD: ${DB_PASSWORD}
+ DB_NAME: ${DB_NAME}
+ MATRIX_SERVER: http://tuwunel:8008
+ MATRIX_SERVER_NAME: localhost
+ MATRIX_ADMIN_USER: ${MATRIX_ADMIN_USER}
+ MATRIX_ADMIN_PASSWORD: ${MATRIX_ADMIN_PASSWORD}
+ MATRIX_REGISTRATION_SHARED_SECRET: ${MATRIX_REGISTRATION_SHARED_SECRET}
+ AGENT_REGISTRATION_TOKEN: ${AGENT_REGISTRATION_TOKEN}
+ JWT_SECRET_KEY: ${JWT_SECRET_KEY}
+ GATEWAY_ADMIN_EMAIL: ${GATEWAY_ADMIN_EMAIL}
+ GATEWAY_ADMIN_PASSWORD: ${GATEWAY_ADMIN_PASSWORD}
+ entrypoint: >
+ sh -c "
+ alembic upgrade head &&
+ python -m switch_core.cli.backfill --allow-empty ||
+ echo 'backfill did not complete; starting anyway. Room history from
+ before this release may be missing until it is re-run.' >&2
+ "
+ depends_on:
+ postgres:
+ condition: service_healthy
+ tuwunel:
+ condition: service_started
+
switch:
image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required, set it in .env, there is no default}
ports:
@@ -175,6 +223,8 @@ services:
condition: service_healthy
tuwunel:
condition: service_started
+ backfill:
+ condition: service_completed_successfully
gateway:
image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:?required, set it in .env, there is no default}
diff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.py
index 0df3ad946..d0e7d84a1 100644
--- a/core/switch_core/bridges/agent/api/handlers.py
+++ b/core/switch_core/bridges/agent/api/handlers.py
@@ -101,8 +101,6 @@ logger = logging.getLogger(__name__)
router = APIRouter()
-MEDIATION_TIMEOUT_SECONDS = 10.0
-
def parse_timestamp_ms(iso: str) -> int:
dt = datetime.fromisoformat(iso)
@@ -1277,8 +1275,6 @@ async def pre_tool_call(
req.room_id,
req.tool_name,
req.arguments,
- req.request_id,
- MEDIATION_TIMEOUT_SECONDS,
)
except ValueError as e:
raise HTTPException(status_code=404, detail=str(e)) from e
@@ -1304,8 +1300,6 @@ async def pre_llm_request(
req.room_id,
req.model,
req.messages,
- req.request_id,
- MEDIATION_TIMEOUT_SECONDS,
)
except ValueError as e:
raise HTTPException(status_code=404, detail=str(e)) from e
@@ -1331,8 +1325,6 @@ async def post_tool_result(
req.room_id,
req.tool_name,
req.result,
- req.request_id,
- MEDIATION_TIMEOUT_SECONDS,
)
except ValueError as e:
raise HTTPException(status_code=404, detail=str(e)) from e
@@ -1358,8 +1350,6 @@ async def post_llm_response(
req.room_id,
req.model,
req.response,
- req.request_id,
- MEDIATION_TIMEOUT_SECONDS,
)
except ValueError as e:
raise HTTPException(status_code=404, detail=str(e)) from e
diff --git a/core/switch_core/bridges/agent/app.py b/core/switch_core/bridges/agent/app.py
index e744bbf93..ba60a27e9 100644
--- a/core/switch_core/bridges/agent/app.py
+++ b/core/switch_core/bridges/agent/app.py
@@ -17,12 +17,10 @@ from switch_core.bridges.agent.mcp import create_mcp_app
from switch_core.bridges.agent.protocol.connections import ConnectionRegistry
from switch_core.bridges.agent.protocol.event_buffer import EventBuffer
from switch_core.bridges.agent.protocol.service import ProtocolService
-from switch_core.bridges.agent.request_tracker import RequestTracker
from switch_core.bridges.collaboration.lifecycle_service import (
CollaborationBridgeLifecycleService,
)
from switch_core.bridges.resource.service import ResourceService
-from switch_core.bridges.resource.tracker import ResourceRequestTracker
from switch_core.clients.client_lifecycle_service import ClientLifecycleService
from switch_core.config import SwitchConfig
from switch_core.db.stores.agent_session_store import AgentSessionStore
@@ -47,8 +45,6 @@ def create_agent_bridge_app(
collab_lifecycle: CollaborationBridgeLifecycleService,
event_buffer: EventBuffer,
task_store: TaskStore,
- request_tracker: RequestTracker,
- resource_request_tracker: ResourceRequestTracker,
resource_service: ResourceService,
api_key_store: ApiKeyStore,
external_user_store: ExternalUserStore,
@@ -82,8 +78,6 @@ def create_agent_bridge_app(
event_buffer=event_buffer,
connections=connections,
task_store=task_store,
- request_tracker=request_tracker,
- resource_request_tracker=resource_request_tracker,
resource_service=resource_service,
api_key_store=api_key_store,
api_key_cache=api_key_cache,
@@ -103,8 +97,6 @@ def create_agent_bridge_app(
event_buffer=event_buffer,
connections=connections,
task_store=task_store,
- request_tracker=request_tracker,
- resource_request_tracker=resource_request_tracker,
resource_service=resource_service,
api_key_store=api_key_store,
api_key_cache=api_key_cache,
diff --git a/core/switch_core/bridges/agent/commands.py b/core/switch_core/bridges/agent/commands.py
index 2d4235718..65cbba170 100644
--- a/core/switch_core/bridges/agent/commands.py
+++ b/core/switch_core/bridges/agent/commands.py
@@ -6,8 +6,6 @@ from collections.abc import Awaitable, Callable
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Literal, cast
-from nio import MatrixRoom
-
from switch_core.agent_display_name import agent_label, agent_label_with_identifier
from switch_core.aliases import (
AliasError,
@@ -24,6 +22,7 @@ from switch_core.clients.mentions import mention_tokens as _mention_tokens
from switch_core.db.stores.agent_runtime_state_store import AgentRuntimeStateStore
from switch_core.events import CommandEvent
from switch_core.gateway.known_agents import known_agent_for
+from switch_core.transport import RoomRef
if TYPE_CHECKING:
from switch_core.clients.admin_client import AdminClient
@@ -45,9 +44,7 @@ AGENT_GREETINGS = [
"Hi there! Just @{name} me when you're ready.",
]
-CommandHandler = Callable[
- ["AgentClient", MatrixRoom, CommandEvent, bool], Awaitable[None]
-]
+CommandHandler = Callable[["AgentClient", RoomRef, CommandEvent, bool], Awaitable[None]]
# (client, args, room_id) -> whether THIS agent is addressed by the command.
# Targeting is a per-command policy (see Command.addressed) rather than a fixed
# rule in on_command, so a command like `run-cmd` can interpret its args its
@@ -58,7 +55,7 @@ CommandTargeting = Callable[["AgentClient", str, str], Awaitable[bool]]
# system message when the command is misused (bad/missing target) and does
# nothing when usage is valid; it never executes the command itself.
CommandAdminCheck = Callable[
- ["AdminClient", MatrixRoom, CommandEvent, "RoomMeta"], Awaitable[None]
+ ["AdminClient", RoomRef, CommandEvent, "RoomMeta"], Awaitable[None]
]
@@ -129,7 +126,7 @@ async def _first_token_is_me(client: AgentClient, first: str, room_id: str) -> b
async def _check_control_target(
- host: AdminClient, room: MatrixRoom, event: CommandEvent, meta: RoomMeta
+ host: AdminClient, room: RoomRef, event: CommandEvent, meta: RoomMeta
) -> None:
"""Admin-side usage feedback for a target-required control command.
@@ -238,7 +235,7 @@ class Command:
async def _reply(
client: AgentClient | AdminClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
body: str,
*,
@@ -261,7 +258,7 @@ async def _reply(
async def _cmd_help(
- client: AgentClient, room: MatrixRoom, event: CommandEvent, _is_direct: bool
+ client: AgentClient, room: RoomRef, event: CommandEvent, _is_direct: bool
) -> None:
lines = ["**Available commands:**"]
for cmd in COMMANDS:
@@ -273,7 +270,7 @@ async def _cmd_help(
async def _dispatch_control_command(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
command: str,
*,
@@ -367,7 +364,7 @@ async def _dispatch_control_command(
async def _cmd_reset(
- client: AgentClient, room: MatrixRoom, event: CommandEvent, _is_direct: bool
+ client: AgentClient, room: RoomRef, event: CommandEvent, _is_direct: bool
) -> None:
await _dispatch_control_command(
client,
@@ -388,7 +385,7 @@ async def _cmd_reset(
async def _cmd_compact(
- client: AgentClient, room: MatrixRoom, event: CommandEvent, _is_direct: bool
+ client: AgentClient, room: RoomRef, event: CommandEvent, _is_direct: bool
) -> None:
await _dispatch_control_command(
client,
@@ -408,7 +405,7 @@ async def _cmd_compact(
async def _cmd_interrupt(
- client: AgentClient, room: MatrixRoom, event: CommandEvent, _is_direct: bool
+ client: AgentClient, room: RoomRef, event: CommandEvent, _is_direct: bool
) -> None:
await _dispatch_control_command(
client,
@@ -429,7 +426,7 @@ async def _cmd_interrupt(
async def _cmd_list_room_agents(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -457,7 +454,7 @@ async def _cmd_list_room_agents(
async def _cmd_list_aliases(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -489,7 +486,7 @@ async def _cmd_list_aliases(
async def _cmd_set_alias(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -559,7 +556,7 @@ async def _cmd_set_alias(
async def _cmd_remove_alias(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -611,7 +608,7 @@ async def _cmd_remove_alias(
async def _cmd_invite(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -730,7 +727,7 @@ def _format_status_lines(
async def _cmd_status(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -772,7 +769,7 @@ async def _cmd_status(
async def _cmd_roles(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -810,7 +807,7 @@ async def _cmd_roles(
async def _cmd_list_documents(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -856,7 +853,7 @@ async def _cmd_list_documents(
async def _cmd_list_references(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -892,7 +889,7 @@ async def _cmd_list_references(
async def _cmd_room_url(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -919,7 +916,7 @@ async def _cmd_room_url(
async def _cmd_list_all_agents(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -951,7 +948,7 @@ def _role_arg(args: str) -> str | None:
async def _cmd_run_cmd(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
_is_direct: bool,
) -> None:
@@ -1012,7 +1009,7 @@ async def _cmd_run_cmd(
async def _cmd_agents_greet(
client: AgentClient,
- room: MatrixRoom,
+ room: RoomRef,
event: CommandEvent,
is_direct: bool,
) -> None:
@@ -1219,7 +1216,7 @@ COMMANDS_BY_NAME: dict[str, Command] = {cmd.name: cmd for cmd in COMMANDS}
async def dispatch_command(
- client: AgentClient, room: MatrixRoom, event: CommandEvent, is_direct: bool
+ client: AgentClient, room: RoomRef, event: CommandEvent, is_direct: bool
) -> bool:
"""Runs a command.
@@ -1244,7 +1241,7 @@ async def dispatch_command(
async def dispatch_admin_command(
- host: AdminClient, room: MatrixRoom, event: CommandEvent
+ host: AdminClient, room: RoomRef, event: CommandEvent
) -> None:
"""Run an admin-owned command on the admin client.
diff --git a/core/switch_core/bridges/agent/dependencies.py b/core/switch_core/bridges/agent/dependencies.py
index 1c5aedc0a..2a11d36c1 100644
--- a/core/switch_core/bridges/agent/dependencies.py
+++ b/core/switch_core/bridges/agent/dependencies.py
@@ -9,12 +9,10 @@ from switch_core.bridges.agent.api_key_cache import ApiKeyCache
from switch_core.bridges.agent.protocol.connections import ConnectionRegistry
from switch_core.bridges.agent.protocol.event_buffer import EventBuffer
from switch_core.bridges.agent.protocol.service import ProtocolService
-from switch_core.bridges.agent.request_tracker import RequestTracker
from switch_core.bridges.collaboration.lifecycle_service import (
CollaborationBridgeLifecycleService,
)
from switch_core.bridges.resource.service import ResourceService
-from switch_core.bridges.resource.tracker import ResourceRequestTracker
from switch_core.clients.client_lifecycle_service import ClientLifecycleService
from switch_core.config import SwitchConfig
from switch_core.db.stores.agent_session_store import AgentSessionStore
@@ -40,8 +38,6 @@ def init_dependencies(
event_buffer: EventBuffer,
connections: ConnectionRegistry,
task_store: TaskStore,
- request_tracker: RequestTracker,
- resource_request_tracker: ResourceRequestTracker,
resource_service: ResourceService,
api_key_store: ApiKeyStore,
api_key_cache: ApiKeyCache,
@@ -59,8 +55,6 @@ def init_dependencies(
_state["event_buffer"] = event_buffer
_state["connections"] = connections
_state["task_store"] = task_store
- _state["request_tracker"] = request_tracker
- _state["resource_request_tracker"] = resource_request_tracker
_state["resource_service"] = resource_service
_state["api_key_store"] = api_key_store
_state["api_key_cache"] = api_key_cache
@@ -79,8 +73,6 @@ def init_dependencies(
event_buffer=event_buffer,
connections=connections,
task_store=task_store,
- request_tracker=request_tracker,
- resource_request_tracker=resource_request_tracker,
resource_service=resource_service,
api_key_store=api_key_store,
api_key_cache=api_key_cache,
@@ -120,14 +112,6 @@ def get_task_store() -> TaskStore:
return _state["task_store"] # type: ignore[no-any-return]
-def get_request_tracker() -> RequestTracker:
- return _state["request_tracker"] # type: ignore[no-any-return]
-
-
-def get_resource_request_tracker() -> ResourceRequestTracker:
- return _state["resource_request_tracker"] # type: ignore[no-any-return]
-
-
def get_resource_service() -> ResourceService:
return _state["resource_service"] # type: ignore[no-any-return]
diff --git a/core/switch_core/bridges/agent/mediation.py b/core/switch_core/bridges/agent/mediation.py
new file mode 100644
index 000000000..485b3692d
--- /dev/null
+++ b/core/switch_core/bridges/agent/mediation.py
@@ -0,0 +1,71 @@
+"""Whether an agent may use the tool or model it is about to use.
+
+Two checks, both a lookup against what the agent has attached. They used to be
+reached by posting a Matrix event into a room and waiting up to ten seconds for
+an answer that was computed in the same process — see the commit that moved
+them here for why that was not doing anything a function call does not.
+
+Post-invocation mediation is not here, because there is nothing to decide: the
+`post_tool_result` and `post_llm_response` hooks exist as places to inspect
+what came back, and today they inspect nothing. Adding a check to them means
+adding it here.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NamedTuple
+
+if TYPE_CHECKING:
+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+ from switch_core.db.stores.agent_store import AgentStore
+
+# What a caller gets back. `proceed` is the only verdict that lets the call
+# happen; anything else carries a reason, because a refusal a user cannot act
+# on is barely better than a crash.
+PROCEED = "proceed"
+BLOCKED = "blocked"
+
+
+class Verdict(NamedTuple):
+ verdict: str
+ reason: str | None
+
+ @staticmethod
+ def proceed() -> Verdict:
+ return Verdict(PROCEED, None)
+
+ @staticmethod
+ def blocked(reason: str) -> Verdict:
+ return Verdict(BLOCKED, reason)
+
+
+class MediationService:
+ """Decides pre-invocation mediation from what the agent has attached."""
+
+ def __init__(
+ self,
+ *,
+ session_factory: async_sessionmaker[AsyncSession],
+ agent_store: AgentStore,
+ ) -> None:
+ self._session_factory = session_factory
+ self._agent_store = agent_store
+
+ async def tool_access(self, agent_id: str, tool_name: str) -> Verdict:
+ async with self._session_factory() as session:
+ tools = await self._agent_store.get_tools(session, agent_id)
+ if any(tool.name == tool_name for tool in tools):
+ return Verdict.proceed()
+ return Verdict.blocked(
+ f"Agent {agent_id} does not have tool '{tool_name}' attached"
+ )
+
+ async def model_access(self, agent_id: str, model_name: str) -> Verdict:
+ async with self._session_factory() as session:
+ models = await self._agent_store.get_models(session, agent_id)
+ if any(model.name == model_name for model in models):
+ return Verdict.proceed()
+ return Verdict.blocked(
+ f"Agent {agent_id} does not have model '{model_name}' attached"
+ )
diff --git a/core/switch_core/bridges/agent/operations/definitions.py b/core/switch_core/bridges/agent/operations/definitions.py
index 399a1913c..5fa5e72b1 100644
--- a/core/switch_core/bridges/agent/operations/definitions.py
+++ b/core/switch_core/bridges/agent/operations/definitions.py
@@ -402,22 +402,14 @@ async def load_internal_documents(ids: list[str]) -> list[dict[str, Any]]:
the requested ids. Raises an error if any id is not attached to the
current room.
- The load goes through the Switch resource manager as a Matrix event
- round-trip, mirroring how tool and LLM mediation works.
"""
- import uuid
-
agent_id = get_agent_id()
room_id = await require_connected_room()
protocol = get_protocol()
- await protocol.require_room_member(agent_id, room_id)
- request_id = str(uuid.uuid4())
return await protocol.request_document_load(
agent_id=agent_id,
room_id=room_id,
document_ids=ids,
- request_id=request_id,
- timeout=30.0,
)
@@ -446,17 +438,13 @@ async def create_room_document(
content: Full text content (max 1 MiB).
Returns:
- ``{"document_id": "..."}`` once the resource manager confirms creation.
+ ``{"document_id": "..."}``.
"""
- import uuid
-
if len(content.encode("utf-8")) > _ROOM_DOCUMENT_MAX_CONTENT_BYTES:
raise ValueError(f"content exceeds {_ROOM_DOCUMENT_MAX_CONTENT_BYTES} bytes")
agent_id = get_agent_id()
room_id = await require_connected_room()
protocol = get_protocol()
- await protocol.require_room_member(agent_id, room_id)
- request_id = str(uuid.uuid4())
document_id = await protocol.request_room_document_create(
agent_id=agent_id,
room_id=room_id,
@@ -464,8 +452,6 @@ async def create_room_document(
description=description,
instructions=instructions,
content=content,
- request_id=request_id,
- timeout=30.0,
)
return {"document_id": document_id}
@@ -483,8 +469,6 @@ async def update_room_document(
Only the agent that created the document can update it. Pass only the
fields you want to change; omit (or set to None) the others.
"""
- import uuid
-
if (
content is not None
and len(content.encode("utf-8")) > _ROOM_DOCUMENT_MAX_CONTENT_BYTES
@@ -493,8 +477,6 @@ async def update_room_document(
agent_id = get_agent_id()
room_id = await require_connected_room()
protocol = get_protocol()
- await protocol.require_room_member(agent_id, room_id)
- request_id = str(uuid.uuid4())
await protocol.request_room_document_update(
agent_id=agent_id,
room_id=room_id,
@@ -503,8 +485,6 @@ async def update_room_document(
description=description,
instructions=instructions,
content=content,
- request_id=request_id,
- timeout=30.0,
)
return {"document_id": document_id, "status": "ok"}
@@ -516,19 +496,13 @@ async def delete_room_document(document_id: str) -> dict[str, str]:
Only the agent that created the document can delete it via MCP. Users
can also delete from the room UI as an admin escape hatch.
"""
- import uuid
-
agent_id = get_agent_id()
room_id = await require_connected_room()
protocol = get_protocol()
- await protocol.require_room_member(agent_id, room_id)
- request_id = str(uuid.uuid4())
await protocol.request_room_document_delete(
agent_id=agent_id,
room_id=room_id,
document_id=document_id,
- request_id=request_id,
- timeout=30.0,
)
return {"document_id": document_id, "status": "ok"}
@@ -565,9 +539,8 @@ async def read_context(
`limit`, or page backwards with `before`, before concluding you have the
full picture. `oldest_timestamp` marks where to resume, but it is epoch
milliseconds while `before` is parsed as ISO-8601: convert it rather than
- passing it straight back. `truncated` is deliberately conservative: a read
- that ends exactly on `limit` reports truncated even if nothing older
- exists.
+ passing it straight back. `truncated` is exact: a read that ends exactly on
+ `limit` with nothing older behind it reports False.
`attachments` is a (usually empty) list of files on the message, each
{"filename", "mimetype", "size", "mxc", "msgtype"}. Any file type can
diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.py
index 8b168cf18..3bde439c8 100644
--- a/core/switch_core/bridges/agent/protocol/service.py
+++ b/core/switch_core/bridges/agent/protocol/service.py
@@ -8,16 +8,7 @@ import uuid
from collections.abc import Sequence
from datetime import UTC, datetime
from typing import TYPE_CHECKING, Any
-from urllib.parse import quote
-
-from nio import (
- DownloadError,
- RoomContextError,
- RoomGetEventError,
- RoomMemberEvent,
- RoomMessageMedia,
- RoomMessagesError,
-)
+
from sqlalchemy import func, select
from switch_core.addressing import (
@@ -29,8 +20,10 @@ from switch_core.addressing import (
from switch_core.agent_display_name import normalise_display_name
from switch_core.agent_icon import normalise_icon_url, validate_icon_url
from switch_core.aliases import check_alias_collisions, validate_alias_format
+from switch_core.attachments import parse_attachment_group
from switch_core.authz import Action, Principal, require, require_manage
from switch_core.bridges.agent.api_key_cache import ApiKeyCache
+from switch_core.bridges.agent.mediation import MediationService
from switch_core.bridges.agent.protocol.agent_detail import (
apply_agent_options,
assemble_agent_detail,
@@ -58,13 +51,13 @@ from switch_core.bridges.agent.protocol.types import (
ToolCallReport,
ToolSpec,
)
-from switch_core.bridges.agent.request_tracker import RequestTracker
from switch_core.bridges.resource.service import ResourceService
-from switch_core.bridges.resource.tracker import ResourceRequestTracker
from switch_core.crypto import encrypt_token
from switch_core.db.models import (
Agent,
ApiKey,
+ Message,
+ MessageAttachment,
Model,
Reference,
RoleLease,
@@ -81,6 +74,7 @@ from switch_core.db.stores.agent_runtime_state_store import (
from switch_core.db.stores.agent_runtime_state_store import (
AgentRuntimeStateStore,
)
+from switch_core.db.stores.message_store import MessageStore
from switch_core.db.stores.room_group_store import RoomGroupStore
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.user_store import UserStore
@@ -91,6 +85,10 @@ from switch_core.events import (
from switch_core.events import (
ToolCallReport as MatrixToolCallReport,
)
+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPE
+from switch_core.transport import (
+ TransportError,
+)
if TYPE_CHECKING:
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -119,17 +117,82 @@ logger = logging.getLogger(__name__)
# trailing newline, which would let an identifier carry a line break.
_VALID_NAME_RE = re.compile(r"\A[a-z0-9][a-z0-9._-]*\Z")
-# History pagination. The homeserver caps a /messages page regardless of what
-# we ask for, and state events consume it without ever reaching the caller, so
-# one page is never a reliable window. The page cap bounds a single read_context
-# call; hitting it is reported as `truncated` rather than passed off as the
-# whole story.
-HISTORY_PAGE_SIZE = 100
-HISTORY_MAX_PAGES = 20
-# Pages spent walking back to a `before` window, budgeted separately from the
-# pages spent reading inside it. Only used when the homeserver cannot answer
-# timestamp_to_event; a scan is the slow path, so it gets room to succeed.
-HISTORY_MAX_SEEK_PAGES = 100
+# A hard ceiling on one read_context call, whatever limit the caller asks for.
+# History comes from a single indexed query now, so the only thing this guards
+# is the size of the response.
+HISTORY_MAX_LIMIT = 500
+
+# The post-invocation hooks answer in a different vocabulary from the
+# pre-invocation ones: `ok` / `blocked` / `redacted` rather than `proceed` /
+# `blocked`. Nothing currently returns anything but this.
+POST_INVOCATION_OK = "ok"
+
+
+def _epoch_ms(when: Any) -> int | None:
+ """A stored timestamp as epoch milliseconds, which is what agents read."""
+ if not isinstance(when, datetime):
+ return None
+ return int(when.timestamp() * 1000)
+
+
+def _from_epoch_ms(when: int | None) -> datetime | None:
+ if when is None:
+ return None
+ return datetime.fromtimestamp(when / 1000, tz=UTC)
+
+
+def _coalesce_attachment_groups(
+ rows: list[Message], attachments: dict[str, list[MessageAttachment]]
+) -> tuple[list[Message], dict[str, list[MessageAttachment]]]:
+ """Put a multi-file message back together.
+
+ A message carrying several files is sent as one event per file sharing a
+ group marker, because the bus has no event that holds more than one. Each
+ of those events is recorded on its own row, so history has to reassemble
+ them the same way a live receiver does — otherwise a two-file post reads
+ back as two posts, the second captioned with a filename.
+
+ The lowest index present leads: it carries the caption and the id the
+ sender was handed, and it stays the lead when a later part is missing. A
+ group split by the window edge is coalesced from the parts inside it, so a
+ page can return fewer entries than rows it read.
+ """
+ members: dict[str, list[tuple[int, Message]]] = {}
+ for row in rows:
+ group = parse_attachment_group(row.content or {})
+ if group is not None:
+ members.setdefault(group[0], []).append((group[1], row))
+ if not members:
+ return rows, attachments
+
+ merged = dict(attachments)
+ absorbed: set[str] = set()
+ for parts in members.values():
+ parts.sort(key=lambda part: part[0])
+ lead = parts[0][1]
+ merged[lead.id] = [
+ attachment for _, row in parts for attachment in attachments.get(row.id, [])
+ ]
+ absorbed.update(row.id for _, row in parts[1:])
+ return [row for row in rows if row.id not in absorbed], merged
+
+
+def _elided_root(root_id: str) -> dict[str, Any]:
+ """A stand-in for a thread root with no recorded row.
+
+ Dropping the thread would lose its replies as well, so the root is named
+ and marked elided instead — visibly incomplete rather than quietly absent.
+ """
+ logger.warning("No recorded thread root %s; returning an elided stub", root_id)
+ return {
+ "id": root_id,
+ "kind": "message",
+ "sender": None,
+ "sender_name": None,
+ "body": None,
+ "timestamp": None,
+ "elided": True,
+ }
class AgentExistsError(Exception):
@@ -161,8 +224,6 @@ class ProtocolService:
event_buffer: EventBuffer,
connections: ConnectionRegistry,
task_store: TaskStore,
- request_tracker: RequestTracker,
- resource_request_tracker: ResourceRequestTracker,
resource_service: ResourceService,
api_key_store: ApiKeyStore,
api_key_cache: ApiKeyCache,
@@ -176,6 +237,7 @@ class ProtocolService:
self.agent_runtime_state_store = AgentRuntimeStateStore()
self.room_role_store = RoomRoleStore()
self.room_group_store = RoomGroupStore()
+ self.message_store = MessageStore()
self.user_store = UserStore()
self.room_store = room_store
self.room_service = room_service
@@ -188,9 +250,10 @@ class ProtocolService:
# connection set in two.
self.connections = connections
self.task_store = task_store
- self.request_tracker = request_tracker
- self.resource_request_tracker = resource_request_tracker
self.resource_service = resource_service
+ self.mediation = MediationService(
+ session_factory=session_factory, agent_store=agent_store
+ )
self.api_key_store = api_key_store
# Shared with the bearer-auth middleware for the same reason as
# `connections`: a key this service rotates must stop authenticating
@@ -911,17 +974,13 @@ class ProtocolService:
root. If the event does not exist in the room we fail loud rather than
post into a non-existent thread.
"""
- if client.nio_client is None:
+ if client.transport is None:
raise ValueError("Agent client not connected to Matrix")
- resp = await client.nio_client.room_get_event(matrix_room_id, thread_id)
- if isinstance(resp, RoomGetEventError):
+ event = await client.transport.get_event(matrix_room_id, thread_id)
+ if event is None:
raise ValueError(f"thread_id not found in room: {thread_id}")
- relates = resp.event.source.get("content", {}).get("m.relates_to") or {}
- if relates.get("rel_type") == "m.thread":
- root = relates.get("event_id")
- if root:
- return str(root)
- return thread_id
+ root = getattr(event, "thread_root_id", None)
+ return str(root) if root else thread_id
async def send_message(
self,
@@ -1415,12 +1474,12 @@ class ProtocolService:
anchor_event_id: str | None = None,
) -> None:
client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client is None or client.nio_client is None:
+ if client is None or client.transport is None:
logger.debug(
"No live client for agent %s; skipping runtime-state emit", agent_id
)
return
- await client.nio_client.room_send(
+ await client.send_event(
matrix_room_id,
"com.switch.agent.runtime_state",
{
@@ -1513,85 +1572,49 @@ class ProtocolService:
return here[0] if here else None
@staticmethod
- def _message_dict(event: Any) -> dict[str, Any]:
- """Build the agent-facing message dict from a nio event."""
- content = event.source.get("content", {}) if hasattr(event, "source") else {}
- sender_name = content.get("sender_name")
- if not sender_name:
- sender_name = event.sender
- body = getattr(event, "body", None)
-
- attachments: list[dict[str, Any]] = []
- if isinstance(event, RoomMessageMedia):
- info = content.get("info", {}) or {}
- attachments.append(
- {
- "filename": content.get("filename") or body,
- "mimetype": str(info.get("mimetype", "")),
- "size": int(info.get("size", 0) or 0),
- "mxc": str(event.url),
- "msgtype": str(content.get("msgtype", "")),
- }
- )
-
- return {
- "id": event.event_id,
- "kind": "message",
- "sender": event.sender,
- "sender_name": sender_name,
- "body": body,
- "timestamp": getattr(event, "server_timestamp", None),
- "attachments": attachments,
- }
-
- @staticmethod
- def _join_dict(event: RoomMemberEvent) -> dict[str, Any] | None:
- """Build a timeline entry for someone joining the room.
+ def _timeline_entry(
+ message: Message, attachments: list[MessageAttachment]
+ ) -> dict[str, Any]:
+ """Build the agent-facing entry for a recorded row.
- Only a transition *into* join counts: a display-name change or avatar
- update is also an m.room.member event with membership "join", and
- replaying those as arrivals would be a lie.
+ An arrival is stored with no body — how it reads is this function's to
+ decide, not the writer's — so the sentence is composed here and can be
+ changed without rewriting history.
"""
- if event.membership != "join" or event.prev_membership == "join":
- return None
- content = event.content or {}
- name = content.get("displayname") or event.state_key
+ name = message.sender_name or message.sender_matrix_id
+ if message.event_type == MEMBERSHIP_EVENT_TYPE:
+ return {
+ "id": message.transport_event_id,
+ "kind": "room_join",
+ "sender": message.sender_matrix_id,
+ "sender_name": name,
+ "body": f"{name} joined the room",
+ "timestamp": _epoch_ms(message.sent_at),
+ "attachments": [],
+ }
return {
- "id": event.event_id,
- "kind": "room_join",
- "sender": event.state_key,
+ "id": message.transport_event_id,
+ "kind": "message",
+ "sender": message.sender_matrix_id,
"sender_name": name,
- "body": f"{name} joined the room",
- "timestamp": getattr(event, "server_timestamp", None),
- "attachments": [],
+ "body": message.body,
+ "timestamp": _epoch_ms(message.sent_at),
+ "attachments": [
+ {
+ "filename": attachment.filename,
+ "mimetype": attachment.mimetype or "",
+ "size": attachment.size or 0,
+ "mxc": attachment.uri,
+ "msgtype": message.msgtype,
+ }
+ for attachment in attachments
+ ],
}
- def _timeline_entry(self, event: Any) -> dict[str, Any] | None:
- """Map a nio timeline event to an agent-facing entry, or None to skip.
-
- Messages and joins are the timeline; every other state event (leaves,
- topic changes, power levels) is noise an agent cannot act on.
- """
- if isinstance(event, RoomMemberEvent):
- return self._join_dict(event)
- if getattr(event, "body", None):
- return self._message_dict(event)
- return None
-
@staticmethod
- def _thread_root_id(event: Any) -> str:
- """Return the thread root id for an event.
-
- A message that carries an m.thread relation belongs to that root;
- anything else is its own root (a top-level message).
- """
- if hasattr(event, "source"):
- relates = event.source.get("content", {}).get("m.relates_to") or {}
- if relates.get("rel_type") == "m.thread":
- root = relates.get("event_id")
- if root:
- return str(root)
- return str(event.event_id)
+ def _thread_root_id(message: Message) -> str:
+ """A threaded reply belongs to its root; anything else is its own root."""
+ return message.thread_root_event_id or message.transport_event_id
async def read_context(
self,
@@ -1617,229 +1640,87 @@ class ProtocolService:
said and "room_join" for an arrival. Top-level entries are roots with
an empty replies list; replies are ordered oldest-first within a
thread. A root that falls outside the fetched window but has a reply
- inside it is fetched on demand; if it cannot be fetched it is returned
- as an elided stub so the reply is not lost.
+ inside it is fetched alongside; if no record of it exists it is
+ returned as an elided stub so the reply is not lost.
`truncated` is True when older history exists that this call did not
- reach — the caller asked for more than it got. It is deliberately
- conservative: a window that ends exactly on `limit` reports truncated
- even if nothing older happens to exist. A short history must never be
- mistaken for a complete one.
+ return. It is exact: the query asks for one row more than the caller
+ wanted, and the presence of that row is the answer.
"""
- room = await self.require_room_member(agent_id, room_id)
- client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client is None:
- raise ValueError("Agent client not running")
- if client.nio_client is None:
- raise ValueError("Agent client not connected to Matrix")
-
- # Walk backwards page by page until the window is satisfied. A single
- # page is not enough: the homeserver caps its size, and state events
- # that never reach the caller still consume it.
- #
- # Reaching a `before` window and reading inside it are budgeted
- # separately. Matrix has no timestamp cursor, so a `before` deep in a
- # busy room can only be reached by paging over everything newer — and
- # if those pages came out of the read budget, a far-enough-back window
- # would return empty no matter how small a `limit` the caller asked
- # for. Seeking is the cost of getting there, not part of the answer.
- groups: dict[str, dict[str, Any]] = {}
- collected = 0
- oldest_ts: int | None = None
- read_pages = 0
- seek_pages = 0
- exhausted = False
+ await self.require_room_member(agent_id, room_id)
+ limit = max(1, min(limit, HISTORY_MAX_LIMIT))
- start: str | None = None
- if before_ms is not None:
- start = await self._seek_before_token(
- client, room.matrix_room_id, before_ms
+ async with self.session_factory() as session:
+ # One more than asked for. Whether that row exists is precisely the
+ # question `truncated` answers, so there is nothing to estimate and
+ # no reason to be conservative about it.
+ rows = await self.message_store.list_timeline(
+ session,
+ room_id,
+ limit=limit + 1,
+ since=_from_epoch_ms(since_ms),
+ before=_from_epoch_ms(before_ms),
+ )
+ truncated = len(rows) > limit
+ rows = rows[:limit]
+
+ # Replies whose root is older than the window. Reading them costs
+ # one more query for the whole page rather than one per thread.
+ in_window = {row.transport_event_id for row in rows}
+ orphan_roots = {
+ row.thread_root_event_id
+ for row in rows
+ if row.thread_root_event_id
+ and row.thread_root_event_id not in in_window
+ }
+ roots = await self.message_store.list_by_transport_event_ids(
+ session, room_id, orphan_roots
+ )
+ attachments = await self.message_store.attachments_for(
+ session, [row.id for row in rows + roots]
)
- while collected < limit and read_pages < HISTORY_MAX_PAGES:
- if seek_pages >= HISTORY_MAX_SEEK_PAGES:
- logger.warning(
- "read_context gave up seeking back to %s in %s after "
- "%d pages; the window was never reached",
- before_ms,
- room.matrix_room_id,
- seek_pages,
- )
- break
- resp = await client.nio_client.room_messages(
- room.matrix_room_id, start=start, limit=HISTORY_PAGE_SIZE
- )
- if isinstance(resp, RoomMessagesError):
- raise ValueError(f"Failed to fetch room history: {resp.message}")
-
- chunk = list(resp.chunk)
- end = getattr(resp, "end", None)
- # A page that contributes nothing because everything on it is
- # newer than `before` is a seek, not a read.
- reached_window = before_ms is None or any(
- getattr(e, "server_timestamp", None) is not None
- and getattr(e, "server_timestamp") < before_ms
- for e in chunk
- )
- if reached_window:
- read_pages += 1
- else:
- seek_pages += 1
-
- for event in chunk:
- ts = getattr(event, "server_timestamp", None)
- # Newer than the window: keep walking back towards it.
- if before_ms is not None and ts is not None and ts >= before_ms:
- continue
- # Older than the window: pagination runs newest-first, so
- # everything beyond this point is older too.
- if since_ms is not None and ts is not None and ts < since_ms:
- exhausted = True
- break
-
- entry = self._timeline_entry(event)
- if entry is None:
- continue
+ rows, attachments = _coalesce_attachment_groups(rows, attachments)
- root_id = self._thread_root_id(event)
- group = groups.setdefault(
- root_id, {"root": None, "replies": [], "latest": 0}
- )
- if entry["id"] == root_id:
- group["root"] = entry
- else:
- group["replies"].append(entry)
- if ts is not None and ts > group["latest"]:
- group["latest"] = ts
- if ts is not None and (oldest_ts is None or ts < oldest_ts):
- oldest_ts = ts
-
- collected += 1
- if collected >= limit:
- break
+ entries = {
+ row.transport_event_id: self._timeline_entry(
+ row, attachments.get(row.id, [])
+ )
+ for row in rows + roots
+ }
- if exhausted:
- break
- # No continuation token, or the server stopped moving: this is the
- # start of the room.
- if not end or end == start:
- exhausted = True
- break
- start = end
+ groups: dict[str, dict[str, Any]] = {}
+ oldest_ts: int | None = None
+ for row in rows:
+ entry = entries[row.transport_event_id]
+ root_id = self._thread_root_id(row)
+ group = groups.setdefault(
+ root_id, {"root": None, "replies": [], "latest": 0}
+ )
+ if entry["id"] == root_id:
+ group["root"] = entry
+ else:
+ group["replies"].append(entry)
+ ts = entry["timestamp"]
+ if ts is not None:
+ group["latest"] = max(group["latest"], ts)
+ oldest_ts = ts if oldest_ts is None else min(oldest_ts, ts)
- # Resolve roots that fall outside the fetched window (orphan replies).
for root_id, group in groups.items():
if group["root"] is None:
- group["root"] = await self._fetch_root(
- client, room.matrix_room_id, root_id
- )
+ group["root"] = entries.get(root_id) or _elided_root(root_id)
- ordered = sorted(groups.values(), key=lambda g: g["latest"])
threads: list[dict[str, Any]] = []
- for group in ordered:
- group["replies"].reverse() # chunk was newest-first → oldest-first
+ for group in sorted(groups.values(), key=lambda g: g["latest"]):
+ group["replies"].reverse() # rows came newest-first
threads.append({"root": group["root"], "replies": group["replies"]})
- if not exhausted:
- logger.warning(
- "read_context truncated in %s: %d entries over %d read pages "
- "(%d spent seeking), older history not reached",
- room.matrix_room_id,
- collected,
- read_pages,
- seek_pages,
- )
-
return {
"threads": threads,
- "truncated": not exhausted,
+ "truncated": truncated,
"oldest_timestamp": oldest_ts,
}
- async def _seek_before_token(
- self, client: ClientBase[Any], matrix_room_id: str, before_ms: int
- ) -> str | None:
- """Get a pagination token positioned at `before_ms`, if the server can.
-
- `/messages` takes a token, not a timestamp, so reaching a `before` deep
- in a busy room otherwise means paging over everything newer just to
- arrive. `timestamp_to_event` (Matrix 1.6) jumps straight there.
-
- Returns None when the homeserver cannot answer — the caller then walks
- back the slow way. A failure here costs speed, not correctness, so it
- is logged and swallowed rather than raised.
- """
- nio_client = client.nio_client
- if nio_client is None:
- return None
- path = (
- f"/_matrix/client/v1/rooms/{quote(matrix_room_id, safe='')}"
- f"/timestamp_to_event?ts={before_ms}&dir=b"
- )
- try:
- resp = await nio_client.send(
- "GET",
- path,
- headers={"Authorization": f"Bearer {nio_client.access_token}"},
- )
- if resp.status != 200:
- logger.info(
- "timestamp_to_event unavailable in %s (HTTP %d); "
- "falling back to scanning back to the window",
- matrix_room_id,
- resp.status,
- )
- return None
- event_id = (await resp.json()).get("event_id")
- except Exception:
- logger.warning(
- "timestamp_to_event failed in %s; falling back to scanning",
- matrix_room_id,
- exc_info=True,
- )
- return None
- if not event_id:
- return None
-
- context = await nio_client.room_context(matrix_room_id, event_id, limit=1)
- if isinstance(context, RoomContextError):
- logger.info(
- "Could not anchor pagination at %s in %s; scanning instead",
- event_id,
- matrix_room_id,
- )
- return None
- start_token = context.start
- return str(start_token) if start_token else None
-
- async def _fetch_root(
- self, client: ClientBase[Any], matrix_room_id: str, root_id: str
- ) -> dict[str, Any]:
- """Fetch a thread-root event that fell outside the read window.
-
- Failure is degraded-but-functional: we return an elided stub (keeping
- the replies attached to a known id) rather than dropping the thread.
- """
- if client.nio_client is None:
- raise ValueError("Agent client not connected to Matrix")
- resp = await client.nio_client.room_get_event(matrix_room_id, root_id)
- if isinstance(resp, RoomGetEventError):
- logger.warning(
- "Could not fetch thread root %s in %s; returning elided stub",
- root_id,
- matrix_room_id,
- )
- return {
- "id": root_id,
- "kind": "message",
- "sender": None,
- "sender_name": None,
- "body": None,
- "timestamp": None,
- "elided": True,
- }
- return self._message_dict(resp.event)
-
async def download_media(
self, agent_id: str, room_id: str, mxc: str
) -> tuple[bytes, str, str | None]:
@@ -1852,13 +1733,14 @@ class ProtocolService:
client = self.client_lifecycle.get_by_agent_id(agent_id)
if client is None:
raise ValueError("Agent client not running")
- if client.nio_client is None:
+ if client.transport is None:
raise ValueError("Agent client not connected to Matrix")
- resp = await client.nio_client.download(mxc=mxc)
- if isinstance(resp, DownloadError):
- raise ValueError(f"Failed to download media {mxc}: {resp.message}")
- return resp.body, resp.content_type, resp.filename
+ try:
+ resp = await client.transport.download_media(mxc)
+ except TransportError as exc:
+ raise ValueError(f"Failed to download media {mxc}: {exc}") from exc
+ return resp.body, resp.content_type or "", resp.filename
# ── Events ───────────────────────────────────────────────────────────────
@@ -1921,7 +1803,7 @@ class ProtocolService:
client = self.client_lifecycle.get_by_agent_id(agent_id)
if client is None:
raise ValueError("Agent client not running")
- if client.nio_client is None:
+ if client.transport is None:
raise ValueError("Agent client not connected to Matrix")
for event in events:
@@ -1934,7 +1816,7 @@ class ProtocolService:
duration_ms=event.duration_ms,
cost=event.cost,
)
- await client.nio_client.room_send(
+ await client.send_event(
room.matrix_room_id,
"com.switch.report.tool_call",
tool_event.model_dump(exclude_none=True),
@@ -1949,7 +1831,7 @@ class ProtocolService:
duration_ms=event.duration_ms,
cost=event.cost,
)
- await client.nio_client.room_send(
+ await client.send_event(
room.matrix_room_id,
"com.switch.report.llm_call",
llm_event.model_dump(exclude_none=True),
@@ -2008,8 +1890,8 @@ class ProtocolService:
task_id = task.id
client = self.client_lifecycle.get_by_agent_id(requester_id)
- if client and client.nio_client:
- await client.nio_client.room_send(
+ if client and client.transport:
+ await client.send_event(
room.matrix_room_id,
"com.switch.task.delegate",
{
@@ -2043,8 +1925,8 @@ class ProtocolService:
await session.commit()
client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client and client.nio_client:
- await client.nio_client.room_send(
+ if client and client.transport:
+ await client.send_event(
room.matrix_room_id,
"com.switch.task.accept",
{
@@ -2076,8 +1958,8 @@ class ProtocolService:
await session.commit()
client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client and client.nio_client:
- await client.nio_client.room_send(
+ if client and client.transport:
+ await client.send_event(
room.matrix_room_id,
"com.switch.task.update",
{
@@ -2110,8 +1992,8 @@ class ProtocolService:
await session.commit()
client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client and client.nio_client:
- await client.nio_client.room_send(
+ if client and client.transport:
+ await client.send_event(
room.matrix_room_id,
"com.switch.task.finalise",
{
@@ -2140,8 +2022,8 @@ class ProtocolService:
await session.commit()
client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client and client.nio_client:
- await client.nio_client.room_send(
+ if client and client.transport:
+ await client.send_event(
room.matrix_room_id,
"com.switch.task.cancel",
{
@@ -3454,41 +3336,16 @@ class ProtocolService:
room_id: str,
tool_name: str,
arguments: dict[str, Any],
- request_id: str,
- timeout: float,
) -> dict[str, Any]:
- """Request mediation before tool call. Returns verdict and reason."""
- import asyncio
-
- room = await self.require_room_member(agent_id, room_id)
- client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client is None:
- raise ValueError("Agent client not running")
- if client.nio_client is None:
- raise ValueError("Agent client not connected")
+ """Whether this agent may call this tool. Verdict and reason.
- future = self.request_tracker.register(
- request_id, agent_id, room.matrix_room_id
- )
- await client.nio_client.room_send(
- room.matrix_room_id,
- "com.switch.mediation.tool_request",
- {
- "request_id": request_id,
- "agent_id": agent_id,
- "tool_id": tool_name,
- "args": arguments,
- "status": "pending",
- },
- )
-
- try:
- result = await asyncio.wait_for(future, timeout=timeout)
- except TimeoutError:
- self.request_tracker.cancel(request_id)
- raise ValueError("Mediation verdict timed out")
-
- return {"verdict": result.verdict, "reason": result.reason}
+ `arguments` is not inspected. It is accepted because a mediation
+ decision that looks at what is being passed is the obvious next thing
+ to want, and because the hook already sends it.
+ """
+ await self.require_room_member(agent_id, room_id)
+ verdict = await self.mediation.tool_access(agent_id, tool_name)
+ return {"verdict": verdict.verdict, "reason": verdict.reason}
async def pre_llm_request(
self,
@@ -3496,41 +3353,14 @@ class ProtocolService:
room_id: str,
model: str,
messages: list[dict[str, Any]],
- request_id: str,
- timeout: float,
) -> dict[str, Any]:
- """Request mediation before LLM request. Returns verdict and reason."""
- import asyncio
-
- room = await self.require_room_member(agent_id, room_id)
- client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client is None:
- raise ValueError("Agent client not running")
- if client.nio_client is None:
- raise ValueError("Agent client not connected")
+ """Whether this agent may call this model. Verdict and reason.
- future = self.request_tracker.register(
- request_id, agent_id, room.matrix_room_id
- )
- await client.nio_client.room_send(
- room.matrix_room_id,
- "com.switch.mediation.llm_request",
- {
- "request_id": request_id,
- "agent_id": agent_id,
- "model_id": model,
- "messages": messages,
- "status": "pending",
- },
- )
-
- try:
- result = await asyncio.wait_for(future, timeout=timeout)
- except TimeoutError:
- self.request_tracker.cancel(request_id)
- raise ValueError("Mediation verdict timed out")
-
- return {"verdict": result.verdict, "reason": result.reason}
+ `messages` is not inspected, for the same reason `arguments` is not.
+ """
+ await self.require_room_member(agent_id, room_id)
+ verdict = await self.mediation.model_access(agent_id, model)
+ return {"verdict": verdict.verdict, "reason": verdict.reason}
async def post_tool_result(
self,
@@ -3538,42 +3368,19 @@ class ProtocolService:
room_id: str,
tool_name: str,
result: Any,
- request_id: str,
- timeout: float,
) -> dict[str, Any]:
- """Request mediation after tool result. Returns verdict."""
- import asyncio
+ """The hook point after a tool returns. Nothing is decided here yet.
- room = await self.require_room_member(agent_id, room_id)
- rm_clients = self.client_lifecycle.get_by_type("resource_manager")
- if not rm_clients:
- raise ValueError("Resource manager client not running")
- rm = rm_clients[0]
- if rm.nio_client is None:
- raise ValueError("Resource manager client not connected")
-
- future = self.request_tracker.register(
- request_id, agent_id, room.matrix_room_id
- )
- await rm.nio_client.room_send(
- room.matrix_room_id,
- "com.switch.mediation.tool_result",
- {
- "request_id": request_id,
- "agent_id": agent_id,
- "tool_id": tool_name,
- "result": result,
- "status": "ok",
- },
- )
-
- try:
- med_result = await asyncio.wait_for(future, timeout=timeout)
- except TimeoutError:
- self.request_tracker.cancel(request_id)
- raise ValueError("Mediation verdict timed out")
+ It has always returned `ok` unconditionally — the verdict used to be
+ the literal string this method itself put on the wire and then read
+ back off it. Kept as the place a post-invocation check would go, and
+ as the membership check the caller is entitled to fail on.
- return {"verdict": med_result.verdict}
+ Note the vocabulary differs from the pre-invocation hooks: these
+ answer `ok` / `blocked` / `redacted`, not `proceed` / `blocked`.
+ """
+ await self.require_room_member(agent_id, room_id)
+ return {"verdict": POST_INVOCATION_OK}
async def list_room_resources(self, room_id: str) -> dict[str, Any]:
"""Return the {reference_types, references, documents} payload for a
@@ -3584,49 +3391,23 @@ class ProtocolService:
async def request_document_load(
self,
+ *,
agent_id: str,
room_id: str,
document_ids: list[str],
- request_id: str,
- timeout: float,
) -> list[dict[str, Any]]:
- """Dispatch a com.switch.resource.load_request as the agent and await
- the resource manager's response. Raises on error / timeout."""
- import asyncio
+ """Load documents attached to this room.
- room = await self.require_room_member(agent_id, room_id)
- client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client is None:
- raise ValueError("Agent client not running")
- if client.nio_client is None:
- raise ValueError("Agent client not connected")
-
- future = self.resource_request_tracker.register(
- request_id, agent_id, room.matrix_room_id
- )
- await client.nio_client.room_send(
- room.matrix_room_id,
- "com.switch.resource.load_request",
- {
- "request_id": request_id,
- "agent_id": agent_id,
- "document_ids": document_ids,
- },
- )
-
- from switch_core.bridges.resource.events import ResourceLoadResponse
-
- try:
- response = await asyncio.wait_for(future, timeout=timeout)
- except TimeoutError:
- self.resource_request_tracker.cancel(request_id)
- raise ValueError("Resource load timed out") from None
-
- if not isinstance(response, ResourceLoadResponse):
- raise ValueError(f"Unexpected response type: {type(response).__name__}")
- if response.status != "ok":
- raise ValueError(response.error or "Resource manager returned an error")
- return [d.model_dump(mode="json") for d in response.documents]
+ The service checks each id is attached here, which is what stops a
+ document being read across a room boundary. Membership is checked
+ first, so an agent that is not in the room never reaches it.
+ """
+ await self.require_room_member(agent_id, room_id)
+ async with self.session_factory() as session:
+ entries = await self.resource_service.load_documents(
+ session, room_id, document_ids
+ )
+ return [entry.model_dump(mode="json") for entry in entries]
async def request_room_document_create(
self,
@@ -3637,51 +3418,29 @@ class ProtocolService:
description: str,
instructions: str,
content: str,
- request_id: str,
- timeout: float,
) -> str:
- import asyncio
-
room = await self.require_room_member(agent_id, room_id)
- client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client is None or client.nio_client is None:
- raise ValueError("Agent client not connected")
-
- future = self.resource_request_tracker.register(
- request_id, agent_id, room.matrix_room_id
- )
- await client.nio_client.room_send(
- room.matrix_room_id,
- "com.switch.resource.room_document_create_request",
- {
- "request_id": request_id,
- "agent_id": agent_id,
- "name": name,
- "description": description,
- "instructions": instructions,
- "content": content,
- },
- )
-
- from switch_core.bridges.resource.events import RoomDocumentCreateResponse
+ async with self.session_factory() as session:
+ agent = await self.agent_store.get(session, agent_id)
+ document = await self.resource_service.create_room_document(
+ session,
+ room_id=room_id,
+ agent_id=agent_id,
+ owner_id=agent.owner_id if agent is not None else None,
+ name=name,
+ description=description,
+ instructions=instructions,
+ content=content,
+ )
+ document_id, document_name = document.id, document.name
+ await session.commit()
- try:
- response = await asyncio.wait_for(future, timeout=timeout)
- except TimeoutError:
- self.resource_request_tracker.cancel(request_id)
- raise ValueError("Room document create timed out") from None
-
- if not isinstance(response, RoomDocumentCreateResponse):
- raise ValueError(f"Unexpected response type: {type(response).__name__}")
- if response.status != "ok" or response.document_id is None:
- raise ValueError(response.error or "Resource manager returned an error")
-
- await self._post_agent_notice(
- client,
+ await self._announce_document(
+ agent_id,
room.matrix_room_id,
- f"📄 created room document “{response.document_name or name}”.",
+ f"\U0001f4c4 created room document \u201c{document_name}\u201d.",
)
- return response.document_id
+ return document_id
async def request_room_document_update(
self,
@@ -3693,50 +3452,26 @@ class ProtocolService:
description: str | None,
instructions: str | None,
content: str | None,
- request_id: str,
- timeout: float,
) -> None:
- import asyncio
-
room = await self.require_room_member(agent_id, room_id)
- client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client is None or client.nio_client is None:
- raise ValueError("Agent client not connected")
-
- future = self.resource_request_tracker.register(
- request_id, agent_id, room.matrix_room_id
- )
- await client.nio_client.room_send(
- room.matrix_room_id,
- "com.switch.resource.room_document_update_request",
- {
- "request_id": request_id,
- "agent_id": agent_id,
- "document_id": document_id,
- "name": name,
- "description": description,
- "instructions": instructions,
- "content": content,
- },
- )
-
- from switch_core.bridges.resource.events import RoomDocumentUpdateResponse
+ async with self.session_factory() as session:
+ document = await self.resource_service.update_room_document(
+ session,
+ room_id=room_id,
+ agent_id=agent_id,
+ document_id=document_id,
+ name=name,
+ description=description,
+ instructions=instructions,
+ content=content,
+ )
+ document_name = document.name
+ await session.commit()
- try:
- response = await asyncio.wait_for(future, timeout=timeout)
- except TimeoutError:
- self.resource_request_tracker.cancel(request_id)
- raise ValueError("Room document update timed out") from None
-
- if not isinstance(response, RoomDocumentUpdateResponse):
- raise ValueError(f"Unexpected response type: {type(response).__name__}")
- if response.status != "ok":
- raise ValueError(response.error or "Resource manager returned an error")
-
- await self._post_agent_notice(
- client,
+ await self._announce_document(
+ agent_id,
room.matrix_room_id,
- f"📄 updated room document “{response.document_name or document_id}”.",
+ f"\U0001f4c4 updated room document \u201c{document_name}\u201d.",
)
async def request_room_document_delete(
@@ -3745,47 +3480,49 @@ class ProtocolService:
agent_id: str,
room_id: str,
document_id: str,
- request_id: str,
- timeout: float,
) -> None:
- import asyncio
-
room = await self.require_room_member(agent_id, room_id)
- client = self.client_lifecycle.get_by_agent_id(agent_id)
- if client is None or client.nio_client is None:
- raise ValueError("Agent client not connected")
+ async with self.session_factory() as session:
+ # Read the name before deleting it: the notice says what went, and
+ # after the delete there is nothing left to ask.
+ document = await self.resource_service.get_room_scoped_document(
+ session, room_id, document_id
+ )
+ document_name = document.name
+ await self.resource_service.delete_room_document(
+ session,
+ room_id=room_id,
+ agent_id=agent_id,
+ document_id=document_id,
+ )
+ await session.commit()
- future = self.resource_request_tracker.register(
- request_id, agent_id, room.matrix_room_id
- )
- await client.nio_client.room_send(
+ await self._announce_document(
+ agent_id,
room.matrix_room_id,
- "com.switch.resource.room_document_delete_request",
- {
- "request_id": request_id,
- "agent_id": agent_id,
- "document_id": document_id,
- },
+ f"\U0001f5d1 deleted room document \u201c{document_name}\u201d.",
)
- from switch_core.bridges.resource.events import RoomDocumentDeleteResponse
+ async def _announce_document(
+ self, agent_id: str, matrix_room_id: str, body: str
+ ) -> None:
+ """Say in the room what the agent just did to a document.
- try:
- response = await asyncio.wait_for(future, timeout=timeout)
- except TimeoutError:
- self.resource_request_tracker.cancel(request_id)
- raise ValueError("Room document delete timed out") from None
-
- if not isinstance(response, RoomDocumentDeleteResponse):
- raise ValueError(f"Unexpected response type: {type(response).__name__}")
- if response.status != "ok":
- raise ValueError(response.error or "Resource manager returned an error")
-
- await self._post_agent_notice(
- client,
- room.matrix_room_id,
- f"🗑 deleted room document “{response.document_name or document_id}”.",
- )
+ Best-effort, and deliberately after the commit: the change has already
+ happened, and failing to narrate it must neither undo it nor fail the
+ call that made it. A missing client is worth a line in the log — the
+ room is now out of step with the database and nobody in it was told.
+ """
+ client = self.client_lifecycle.get_by_agent_id(agent_id)
+ if client is None or client.transport is None:
+ logger.warning(
+ "Agent %s has no connected client, so its document change in "
+ "%s was not announced in the room",
+ agent_id,
+ matrix_room_id,
+ )
+ return
+ await self._post_agent_notice(client, matrix_room_id, body)
async def post_llm_response(
self,
@@ -3793,39 +3530,11 @@ class ProtocolService:
room_id: str,
model: str,
response: Any,
- request_id: str,
- timeout: float,
) -> dict[str, Any]:
- """Request mediation after LLM response. Returns verdict."""
- import asyncio
+ """The hook point after a model answers. Nothing is decided here yet.
- room = await self.require_room_member(agent_id, room_id)
- rm_clients = self.client_lifecycle.get_by_type("resource_manager")
- if not rm_clients:
- raise ValueError("Resource manager client not running")
- rm = rm_clients[0]
- if rm.nio_client is None:
- raise ValueError("Resource manager client not connected")
-
- future = self.request_tracker.register(
- request_id, agent_id, room.matrix_room_id
- )
- await rm.nio_client.room_send(
- room.matrix_room_id,
- "com.switch.mediation.llm_response",
- {
- "request_id": request_id,
- "agent_id": agent_id,
- "model_id": model,
- "response": response,
- "status": "ok",
- },
- )
-
- try:
- med_result = await asyncio.wait_for(future, timeout=timeout)
- except TimeoutError:
- self.request_tracker.cancel(request_id)
- raise ValueError("Mediation verdict timed out")
-
- return {"verdict": med_result.verdict}
+ The counterpart to `post_tool_result`, and unconditional for the same
+ reason.
+ """
+ await self.require_room_member(agent_id, room_id)
+ return {"verdict": POST_INVOCATION_OK}
diff --git a/core/switch_core/bridges/agent/request_tracker.py b/core/switch_core/bridges/agent/request_tracker.py
deleted file mode 100644
index 807415010..000000000
--- a/core/switch_core/bridges/agent/request_tracker.py
+++ /dev/null
@@ -1,40 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import logging
-
-from switch_core.events import MediationResult
-
-logger = logging.getLogger(__name__)
-
-
-class RequestTracker:
- def __init__(self) -> None:
- self._pending: dict[str, tuple[str, str, asyncio.Future[MediationResult]]] = {}
-
- def register(
- self, request_id: str, agent_id: str, room_id: str
- ) -> asyncio.Future[MediationResult]:
- loop = asyncio.get_running_loop()
- future: asyncio.Future[MediationResult] = loop.create_future()
- self._pending[request_id] = (agent_id, room_id, future)
- return future
-
- def resolve(self, request_id: str, result: MediationResult) -> None:
- entry = self._pending.pop(request_id, None)
- if entry is None:
- logger.warning("Verdict for unknown request_id: %s", request_id)
- return
- _, _, future = entry
- if not future.done():
- future.set_result(result)
-
- def cancel(self, request_id: str) -> None:
- entry = self._pending.pop(request_id, None)
- if entry is not None:
- _, _, future = entry
- if not future.done():
- future.cancel()
-
- def is_pending(self, request_id: str) -> bool:
- return request_id in self._pending
diff --git a/core/switch_core/bridges/collaboration/bridge_core.py b/core/switch_core/bridges/collaboration/bridge_core.py
index 7165ffff9..f857ef94d 100644
--- a/core/switch_core/bridges/collaboration/bridge_core.py
+++ b/core/switch_core/bridges/collaboration/bridge_core.py
@@ -7,13 +7,6 @@ import uuid
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any
-from nio import (
- DownloadError,
- MatrixRoom,
- RoomMessageMedia,
- RoomMessageText,
- RoomSendError,
-)
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -42,8 +35,18 @@ from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.events import AgentRuntimeStateEvent
-from switch_core.matrix_admin import MatrixAdmin
+from switch_core.provisioning import Provisioning
from switch_core.room_service import RoomCreateConfig
+from switch_core.transport import (
+ InboundMedia as TransportMedia,
+)
+from switch_core.transport import (
+ InboundMessage as TransportMessage,
+)
+from switch_core.transport import (
+ RoomRef,
+ TransportError,
+)
if TYPE_CHECKING:
from switch_core.clients.client_lifecycle_service import ClientLifecycleService
@@ -116,7 +119,7 @@ class BridgeCore:
client_store: ClientStore,
room_service: RoomService,
client_lifecycle: ClientLifecycleService,
- matrix_admin: MatrixAdmin,
+ matrix_admin: Provisioning,
session_factory: async_sessionmaker[AsyncSession],
matrix_server_name: str,
bridge_client_matrix_user_id: str,
@@ -657,16 +660,16 @@ class BridgeCore:
"event_id": existing_matrix_root,
}
- resp = await puppet.client.room_send(
- matrix_room_id, "com.switch.command", content
- )
-
- if isinstance(resp, RoomSendError):
+ try:
+ event_id = await puppet.send_event(
+ matrix_room_id, "com.switch.command", content
+ )
+ except TransportError as exc:
logger.error(
"Failed to bridge command %s into %s: %s",
cmd.command,
matrix_room_id,
- resp.message,
+ exc,
)
return
@@ -678,15 +681,15 @@ class BridgeCore:
# Anchor in memory before the DB write: the write awaits a query that
# yields the loop, and a fast reply (e.g. !help) relayed in that gap
# would miss the row and land at the channel root. Popped on commit.
- self._prerecord_message_map(resp.event_id, thread_root_post)
+ self._prerecord_message_map(event_id, thread_root_post)
try:
await self._record_message_map(
external_channel_id=cmd.channel_id,
- matrix_event_id=resp.event_id,
+ matrix_event_id=event_id,
external_post_id=thread_root_post,
)
finally:
- self._pending_message_maps.pop(resp.event_id, None)
+ self._pending_message_maps.pop(event_id, None)
async def _handle_agent_joined_channel(self, join: InboundAgentJoin) -> None:
lock = self._channel_locks.setdefault(join.channel_id, asyncio.Lock())
@@ -1250,7 +1253,7 @@ class BridgeCore:
# ── Outbound (room → platform) ──────────────────────────────────────────
async def handle_outbound_message(
- self, room: MatrixRoom, event: RoomMessageText
+ self, room: RoomRef, event: TransportMessage
) -> None:
logger.debug(
"[BRIDGE-OUT] matrix event from=%s room=%s body=%s",
@@ -1270,9 +1273,9 @@ class BridgeCore:
logger.debug("[BRIDGE-OUT] no channel mapping for room %s", room.room_id)
return
- event_content = event.source.get("content", {}) or {}
+ event_content = event.content
admin_marker = event_content.get(ADMIN_MARKER)
- sender_name = event_content.get("sender_name")
+ sender_name = event.sender_name
# An admin/system message renders natively per bridge (admin_message)
# rather than on behalf of its Matrix sender, so it needs no sender_name.
if sender_name is None and admin_marker is None:
@@ -1351,8 +1354,8 @@ class BridgeCore:
async def handle_outbound_media(
self,
- room: MatrixRoom,
- event: RoomMessageMedia,
+ room: RoomRef,
+ event: TransportMedia,
client: ClientBase[Any],
) -> None:
"""Relay a Matrix media event (an agent-sent image/file) out to the
@@ -1386,8 +1389,8 @@ class BridgeCore:
logger.debug("[BRIDGE-OUT] no channel mapping for room %s", room.room_id)
return
- event_content = event.source.get("content", {}) or {}
- sender_name = event_content.get("sender_name")
+ event_content = event.content
+ sender_name = event.sender_name
if sender_name is None:
logger.error(
"No sender_name in media event from %s — skipping outbound",
@@ -1414,7 +1417,7 @@ class BridgeCore:
)
message_ref: str | None
- data = await self._download_matrix_media(client, event.url, filename)
+ data = await self._download_matrix_media(client, event.uri, filename)
if data is None or len(data) > self._max_attachment_bytes:
if data is not None:
logger.warning(
@@ -1570,18 +1573,17 @@ class BridgeCore:
if not mxc:
logger.error("[BRIDGE-OUT] media event for %s has no mxc URI", filename)
return None
- if client.nio_client is None:
+ if client.transport is None:
logger.error(
"[BRIDGE-OUT] bridge client not connected; cannot fetch %s", mxc
)
return None
- resp = await client.nio_client.download(mxc=mxc)
- if isinstance(resp, DownloadError):
- logger.error(
- "[BRIDGE-OUT] failed to download media %s: %s", mxc, resp.message
- )
+ try:
+ resp = await client.transport.download_media(mxc)
+ except TransportError as exc:
+ logger.error("[BRIDGE-OUT] failed to download media %s: %s", mxc, exc)
return None
- return resp.body # type: ignore[no-any-return]
+ return resp.body
async def handle_outbound_typing(
self, room_id: str, agent_name: str, is_typing: bool
@@ -1594,7 +1596,7 @@ class BridgeCore:
await self._adapter.send_typing(channel_id, agent_name, is_typing)
async def handle_agent_runtime_state(
- self, room: MatrixRoom, event: AgentRuntimeStateEvent
+ self, room: RoomRef, event: AgentRuntimeStateEvent
) -> None:
"""Resolve the channel and let the adapter surface the runtime state.
diff --git a/core/switch_core/bridges/collaboration/lifecycle_service.py b/core/switch_core/bridges/collaboration/lifecycle_service.py
index 83c9871ad..ab9b8bdc9 100644
--- a/core/switch_core/bridges/collaboration/lifecycle_service.py
+++ b/core/switch_core/bridges/collaboration/lifecycle_service.py
@@ -12,6 +12,7 @@ from switch_core.bridges.collaboration.adapter import CollaborationAdapter
from switch_core.bridges.collaboration.bridge_core import BridgeCore
from switch_core.bridges.collaboration.models import BridgeConnectionConfig
from switch_core.clients.bridge_client import BridgeClient, BridgeClientConfig
+from switch_core.clients.client_factory import ClientFactory
from switch_core.config import SwitchConfig
from switch_core.db.models import CollaborationBridge
from switch_core.db.stores.agent_store import AgentStore
@@ -20,7 +21,7 @@ from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore
from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.room_store import RoomStore
-from switch_core.matrix_admin import MatrixAdmin
+from switch_core.provisioning import Provisioning
if TYPE_CHECKING:
from switch_core.clients.client_lifecycle_service import ClientLifecycleService
@@ -60,9 +61,10 @@ class CollaborationBridgeLifecycleService:
client_store: ClientStore,
client_lifecycle: ClientLifecycleService,
room_service: RoomService,
- matrix_admin: MatrixAdmin,
+ matrix_admin: Provisioning,
session_factory: async_sessionmaker[AsyncSession],
config: SwitchConfig,
+ client_factory: ClientFactory,
) -> None:
self._bridge_store = bridge_store
self._external_user_store = external_user_store
@@ -75,6 +77,7 @@ class CollaborationBridgeLifecycleService:
self._matrix_admin = matrix_admin
self._session_factory = session_factory
self._config = config
+ self._client_factory = client_factory
self._adapter_registry: dict[str, type[CollaborationAdapter]] = {}
self._config_registry: dict[str, type[BridgeConnectionConfig]] = {}
@@ -417,8 +420,12 @@ class CollaborationBridgeLifecycleService:
session_factory=self._session_factory,
client_store=self._client_store,
config=BridgeClientConfig(bridge_id=bridge_id),
- device_id=bridge_client_record.device_id,
- access_token=bridge_client_record.access_token,
+ transport_factory=self._client_factory.transport_for,
+ message_recorder=self._client_factory.recorder(),
+ session_state={
+ "access_token": bridge_client_record.access_token,
+ "device_id": bridge_client_record.device_id,
+ },
next_batch_token=bridge_client_record.next_batch_token,
)
@@ -450,6 +457,36 @@ class CollaborationBridgeLifecycleService:
)
await session.commit()
+ async def _record_bridge_memberships(self, bridge_id: str, client_id: str) -> None:
+ """Make the bridge's rooms its recorded memberships before it starts.
+
+ A bridge belongs in every room it carries, and that was expressed by
+ inviting its client and letting the homeserver hold the membership —
+ so nothing wrote it down. Once `client_rooms` became what a client
+ reads its rooms from, a bridge that had never been re-invited was in
+ none of them: it still received from the platform, because inbound
+ posts into a room by id, and relayed nothing back out.
+
+ Run at every start rather than repaired once, because the rooms a
+ bridge carries change while it is stopped.
+ """
+ async with self._session_factory() as session:
+ rooms = await self._room_store.get_by_bridge(session, bridge_id)
+ added = 0
+ for room in rooms:
+ members = await self._room_store.get_client_ids(session, room.id)
+ if client_id in members:
+ continue
+ await self._room_store.add_client(session, client_id, room.id)
+ added += 1
+ await session.commit()
+ if added:
+ logger.info(
+ "Recorded bridge %s as a member of %d room(s) it carries",
+ bridge_id,
+ added,
+ )
+
async def _run_bridge(
self,
bridge_id: str,
@@ -457,6 +494,7 @@ class CollaborationBridgeLifecycleService:
bridge_client: BridgeClient,
) -> None:
try:
+ await self._record_bridge_memberships(bridge_id, bridge_client.client_id)
await bridge_core.start()
await bridge_client.start()
except Exception:
diff --git a/core/switch_core/bridges/resource/__init__.py b/core/switch_core/bridges/resource/__init__.py
index 8eefc24e7..e09607e4f 100644
--- a/core/switch_core/bridges/resource/__init__.py
+++ b/core/switch_core/bridges/resource/__init__.py
@@ -1,8 +1,4 @@
-from switch_core.bridges.resource.events import (
- ResourceLoadEntry,
- ResourceLoadRequest,
- ResourceLoadResponse,
-)
+from switch_core.bridges.resource.events import ResourceLoadEntry
from switch_core.bridges.resource.registry import (
BUILTIN_REFERENCE_TYPES,
ReferenceTypeSpec,
@@ -11,16 +7,12 @@ from switch_core.bridges.resource.registry import (
validate_reference_value,
)
from switch_core.bridges.resource.service import ResourceService
-from switch_core.bridges.resource.tracker import ResourceRequestTracker
__all__ = [
"BUILTIN_REFERENCE_TYPES",
"ReferenceTypeSpec",
"ReferenceValue",
"ResourceLoadEntry",
- "ResourceLoadRequest",
- "ResourceLoadResponse",
- "ResourceRequestTracker",
"ResourceService",
"is_builtin_type",
"validate_reference_value",
diff --git a/core/switch_core/bridges/resource/events.py b/core/switch_core/bridges/resource/events.py
index 3d2a43904..0706c962f 100644
--- a/core/switch_core/bridges/resource/events.py
+++ b/core/switch_core/bridges/resource/events.py
@@ -8,70 +8,3 @@ class ResourceLoadEntry(SwitchEvent):
name: str
description: str
content: str
-
-
-class ResourceLoadRequest(SwitchEvent):
- request_id: str
- agent_id: str
- document_ids: list[str]
-
-
-class ResourceLoadResponse(SwitchEvent):
- request_id: str
- agent_id: str
- status: str # "ok" | "error"
- documents: list[ResourceLoadEntry] = []
- error: str | None = None
-
-
-# ── Room-scoped document mutations (agent-created via MCP) ────────────────
-
-
-class RoomDocumentCreateRequest(SwitchEvent):
- request_id: str
- agent_id: str
- name: str
- description: str
- instructions: str
- content: str
-
-
-class RoomDocumentCreateResponse(SwitchEvent):
- request_id: str
- agent_id: str
- status: str # "ok" | "error"
- document_id: str | None = None
- document_name: str | None = None
- error: str | None = None
-
-
-class RoomDocumentUpdateRequest(SwitchEvent):
- request_id: str
- agent_id: str
- document_id: str
- name: str | None = None
- description: str | None = None
- instructions: str | None = None
- content: str | None = None
-
-
-class RoomDocumentUpdateResponse(SwitchEvent):
- request_id: str
- agent_id: str
- status: str
- document_name: str | None = None
- error: str | None = None
-
-
-class RoomDocumentDeleteRequest(SwitchEvent):
- request_id: str
- agent_id: str
- document_id: str
-
-
-class RoomDocumentDeleteResponse(SwitchEvent):
- request_id: str
- agent_id: str
- status: str
- document_name: str | None = None
- error: str | None = None
diff --git a/core/switch_core/bridges/resource/tracker.py b/core/switch_core/bridges/resource/tracker.py
deleted file mode 100644
index 0361ab7a2..000000000
--- a/core/switch_core/bridges/resource/tracker.py
+++ /dev/null
@@ -1,55 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import logging
-
-from switch_core.bridges.resource.events import (
- ResourceLoadResponse,
- RoomDocumentCreateResponse,
- RoomDocumentDeleteResponse,
- RoomDocumentUpdateResponse,
-)
-
-logger = logging.getLogger(__name__)
-
-ResourceResponse = (
- ResourceLoadResponse
- | RoomDocumentCreateResponse
- | RoomDocumentUpdateResponse
- | RoomDocumentDeleteResponse
-)
-
-
-class ResourceRequestTracker:
- """Tracks in-flight resource round-trips (loads + room-document mutations).
- Mirrors RequestTracker for the mediation flow."""
-
- def __init__(self) -> None:
- self._pending: dict[str, tuple[str, str, asyncio.Future[ResourceResponse]]] = {}
-
- def register(
- self, request_id: str, agent_id: str, room_id: str
- ) -> asyncio.Future[ResourceResponse]:
- loop = asyncio.get_running_loop()
- future: asyncio.Future[ResourceResponse] = loop.create_future()
- self._pending[request_id] = (agent_id, room_id, future)
- return future
-
- def resolve(self, request_id: str, response: ResourceResponse) -> None:
- entry = self._pending.pop(request_id, None)
- if entry is None:
- logger.warning("Resource response for unknown request_id: %s", request_id)
- return
- _, _, future = entry
- if not future.done():
- future.set_result(response)
-
- def cancel(self, request_id: str) -> None:
- entry = self._pending.pop(request_id, None)
- if entry is not None:
- _, _, future = entry
- if not future.done():
- future.cancel()
-
- def is_pending(self, request_id: str) -> bool:
- return request_id in self._pending
diff --git a/core/switch_core/cli/__init__.py b/core/switch_core/cli/__init__.py
new file mode 100644
index 000000000..ecf3a7887
--- /dev/null
+++ b/core/switch_core/cli/__init__.py
@@ -0,0 +1,8 @@
+"""Operator commands that ship inside the image.
+
+These live in the package rather than under `scripts/` because the deployed
+image contains only `switch_core` — a script outside it cannot be run by a
+Kubernetes Job or a Compose service, which is where the migration commands
+have to run. They reach the homeserver and the database directly, so they are
+invoked deliberately, never on every release.
+"""
diff --git a/core/switch_core/cli/backfill.py b/core/switch_core/cli/backfill.py
new file mode 100644
index 000000000..b7fc13d31
--- /dev/null
+++ b/core/switch_core/cli/backfill.py
@@ -0,0 +1,191 @@
+"""Reconstruct room history from the message bus into the message log.
+
+Rows exist from the moment the recorder was deployed. Everything older is on
+the homeserver and nowhere else, which stopped being harmless when the read
+path moved to Postgres: those messages are now invisible to every agent rather
+than merely unqueried.
+
+This walks each room to its start and writes the messages that have no row.
+Reconstructed rows are numbered below zero, so they order correctly against
+the live log without disturbing it, and no delivery cursor moves — nobody is
+sent last March's messages tonight.
+
+Safe to re-run. `transport_event_id` is unique and each page commits on its
+own, so a walk that fails halfway leaves what it finished and picks up from
+there.
+
+Run it against a real deployment. Start with `--dry-run` on one room.
+
+Usage:
+ just backfill-messages --dry-run
+ just backfill-messages --room <switch-room-uuid>
+ just backfill-messages
+
+In a deployment it is the same command inside the image:
+ python -m switch_core.cli.backfill --dry-run
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from sqlalchemy import select
+
+from switch_core.config import SwitchConfig
+from switch_core.db.engine import create_engine_from_config, create_session_factory
+from switch_core.db.models import Room
+from switch_core.db.stores.client_store import ClientStore
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.messages import backfill_room
+from switch_core.transport.matrix import MatrixTransport
+
+# The admin client is a member of every room by design, which is what makes it
+# the one identity that can read every room's history.
+READER_CLIENT_TYPE = "admin"
+
+
+def _parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--room",
+ help="A single Switch room id. Defaults to every non-archived room.",
+ )
+ parser.add_argument(
+ "--dry-run",
+ action="store_true",
+ help=(
+ "Read the history and report what would be written, without "
+ "writing it. Start here."
+ ),
+ )
+ parser.add_argument(
+ "--force",
+ action="store_true",
+ help=(
+ "Walk rooms that have already been backfilled to their start. "
+ "Without it they are skipped: the walk always starts from the "
+ "newest message, so re-reading a finished room costs its whole "
+ "history in pages to learn there is nothing to write."
+ ),
+ )
+ parser.add_argument(
+ "--allow-empty",
+ action="store_true",
+ help=(
+ "Treat 'nothing to walk' as success. For unattended runs — a "
+ "first boot has no admin client and no rooms yet, and a stack "
+ "that refuses to start over an empty database is worse than one "
+ "with nothing to backfill."
+ ),
+ )
+ return parser.parse_args()
+
+
+class _ReadOnlyStore(MessageStore):
+ """Counts what a real run would write, and writes nothing.
+
+ A dry run has to walk exactly as far as a real one and make exactly the
+ same decisions, so it shares everything but the insert.
+ """
+
+ async def create_historical(self, session, message, attachments): # type: ignore[no-untyped-def]
+ return message
+
+ async def mark_history_backfilled(self, session, room_id): # type: ignore[no-untyped-def]
+ """A room a dry run walked has not been backfilled.
+
+ Marking it would make the walk that wrote nothing look like the one
+ that did, and the real run afterwards would find no rooms left to do.
+ """
+ return None
+
+
+async def _run(args: argparse.Namespace) -> int:
+ config = SwitchConfig()
+ engine = create_engine_from_config(config)
+ session_factory = create_session_factory(engine)
+
+ async with session_factory() as session:
+ readers = await ClientStore().get_by_type(session, READER_CLIENT_TYPE)
+ if not readers:
+ print(
+ f"No {READER_CLIENT_TYPE} client exists, so no identity can read "
+ "every room. Start switch-core once to provision it.",
+ file=sys.stderr,
+ )
+ return 0 if args.allow_empty else 2
+ reader = readers[0]
+ query = select(Room).where(Room.archived_at.is_(None))
+ if args.room:
+ query = query.where(Room.id == args.room)
+ if not args.force:
+ query = query.where(Room.history_backfilled_at.is_(None))
+ rooms = list((await session.execute(query)).scalars().all())
+
+ if not rooms:
+ print(
+ "No rooms to backfill — every room has already been walked to its "
+ "start, or there are none. Use --force to walk them again.",
+ file=sys.stderr,
+ )
+ return 0 if args.allow_empty else 2
+
+ transport = MatrixTransport(
+ server_url=config.matrix_server,
+ user_id=reader.matrix_user_id,
+ password=reader.password,
+ device_id=reader.device_id,
+ access_token=reader.access_token,
+ )
+ await transport.connect()
+ joined = set(await transport.joined_rooms())
+
+ store: MessageStore = _ReadOnlyStore() if args.dry_run else MessageStore()
+ written = 0
+ incomplete = 0
+ unreadable: list[str] = []
+ try:
+ for room in rooms:
+ if room.matrix_room_id not in joined:
+ # A room nobody can read is not a room with no history, and
+ # reporting it as done would be the one answer that misleads.
+ unreadable.append(f"{room.name} ({room.matrix_room_id})")
+ continue
+ report = await backfill_room(transport, session_factory, room, store=store)
+ print(report.summary())
+ written += report.written
+ incomplete += 1 if report.incomplete else 0
+ finally:
+ await transport.close()
+ await engine.dispose()
+
+ if unreadable:
+ print(
+ f"\n{len(unreadable)} room(s) the {READER_CLIENT_TYPE} client is not "
+ "in, so they were not backfilled:",
+ file=sys.stderr,
+ )
+ for where in unreadable:
+ print(f" {where}", file=sys.stderr)
+
+ verb = "would be written" if args.dry_run else "written"
+ print(
+ f"\n{len(rooms) - len(unreadable)} room(s) walked, {written} message(s) {verb}."
+ )
+ if incomplete:
+ print(
+ f"{incomplete} room(s) hit the page limit and are only partially "
+ "reconstructed. Re-run to continue.",
+ file=sys.stderr,
+ )
+ return 1 if (unreadable or incomplete) else 0
+
+
+def main() -> int:
+ return asyncio.run(_run(_parse_args()))
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/core/switch_core/cli/reconcile.py b/core/switch_core/cli/reconcile.py
new file mode 100644
index 000000000..22a991f13
--- /dev/null
+++ b/core/switch_core/cli/reconcile.py
@@ -0,0 +1,173 @@
+"""Check that the recorded messages agree with what the message bus holds.
+
+Every message is written to Postgres alongside the send, but the write happens
+after delivery and cannot fail it — so a database problem leaves a row missing
+for a message that really was sent. This walks a room's history on the bus,
+compares it against the recorded rows, and reports the difference.
+
+Run it against a real deployment before moving any read path onto those rows.
+Unit tests cannot answer this question: the thing being checked is whether two
+records of the same live traffic agree.
+
+Only the window in which recording was active is compared — from the oldest
+recorded message in each room, or from `--since`. Messages older than that are
+legitimately absent and are not reported as drift.
+
+Exits non-zero when any room disagrees, so it can gate a deployment.
+
+Usage:
+ just reconcile-messages
+ just reconcile-messages --room <switch-room-uuid>
+ just reconcile-messages --since 2026-09-01T00:00:00+00:00
+ just reconcile-messages --verbose
+
+In a deployment it is the same command inside the image:
+ python -m switch_core.cli.reconcile --verbose
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from datetime import datetime
+
+from sqlalchemy import select
+
+from switch_core.config import SwitchConfig
+from switch_core.db.engine import create_engine_from_config, create_session_factory
+from switch_core.db.models import Room
+from switch_core.db.stores.client_store import ClientStore
+from switch_core.messages import RoomReconciliation, reconcile_room
+from switch_core.transport.matrix import MatrixTransport
+
+# The admin client is a member of every room by design, which is what makes it
+# the one identity that can read every room's history.
+READER_CLIENT_TYPE = "admin"
+
+
+def _parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--room",
+ help="A single Switch room id. Defaults to every non-archived room.",
+ )
+ parser.add_argument(
+ "--since",
+ help=(
+ "ISO-8601 instant to compare from, overriding the per-room "
+ "recorded-from cutoff. Anything older is not reported as missing."
+ ),
+ )
+ parser.add_argument(
+ "--verbose",
+ action="store_true",
+ help="List every differing event rather than only the counts.",
+ )
+ return parser.parse_args()
+
+
+def _report(reconciliation: RoomReconciliation, *, verbose: bool) -> None:
+ print(reconciliation.summary())
+ if reconciliation.ignored_by_type:
+ counts = ", ".join(
+ f"{name}={count}"
+ for name, count in sorted(reconciliation.ignored_by_type.items())
+ )
+ print(f" not sends, so not compared: {counts}")
+ if reconciliation.unverifiable_by_type:
+ counts = ", ".join(
+ f"{name}={count}"
+ for name, count in sorted(reconciliation.unverifiable_by_type.items())
+ )
+ print(f" rows the bus walk cannot check: {counts}")
+ if not reconciliation.anchored:
+ print(
+ " the oldest recorded event was not found on the bus, so the "
+ "start of the window is approximate"
+ )
+ if not verbose:
+ return
+ for event_id in reconciliation.missing_rows:
+ print(f" missing row: {event_id}")
+ for event_id in reconciliation.unsent_rows:
+ print(f" recorded but not on the bus: {event_id}")
+ for mismatch in reconciliation.mismatches:
+ print(f" {mismatch.describe()}")
+
+
+async def _run(args: argparse.Namespace) -> int:
+ since = datetime.fromisoformat(args.since) if args.since else None
+
+ config = SwitchConfig()
+ engine = create_engine_from_config(config)
+ session_factory = create_session_factory(engine)
+
+ async with session_factory() as session:
+ readers = await ClientStore().get_by_type(session, READER_CLIENT_TYPE)
+ if not readers:
+ print(
+ f"No {READER_CLIENT_TYPE} client exists, so no identity can read "
+ "every room. Start switch-core once to provision it.",
+ file=sys.stderr,
+ )
+ return 2
+ reader = readers[0]
+ query = select(Room).where(Room.archived_at.is_(None))
+ if args.room:
+ query = query.where(Room.id == args.room)
+ rooms = list((await session.execute(query)).scalars().all())
+
+ if not rooms:
+ print("No rooms to check.", file=sys.stderr)
+ return 2
+
+ transport = MatrixTransport(
+ server_url=config.matrix_server,
+ user_id=reader.matrix_user_id,
+ password=reader.password,
+ device_id=reader.device_id,
+ access_token=reader.access_token,
+ )
+ await transport.connect()
+ joined = set(await transport.joined_rooms())
+
+ drifted = 0
+ unreadable: list[str] = []
+ try:
+ for room in rooms:
+ if room.matrix_room_id not in joined:
+ # Reporting a room nobody can read as clean would be the worst
+ # possible answer, so it is named and counted as a failure.
+ unreadable.append(f"{room.name} ({room.matrix_room_id})")
+ continue
+ async with session_factory() as session:
+ reconciliation = await reconcile_room(
+ transport, session, room, since=since
+ )
+ _report(reconciliation, verbose=args.verbose)
+ if not reconciliation.clean:
+ drifted += 1
+ finally:
+ await transport.close()
+ await engine.dispose()
+
+ if unreadable:
+ print(
+ f"\n{len(unreadable)} room(s) the {READER_CLIENT_TYPE} client is not "
+ "in, so they were not checked:",
+ file=sys.stderr,
+ )
+ for where in unreadable:
+ print(f" {where}", file=sys.stderr)
+
+ print(f"\n{len(rooms) - len(unreadable)} room(s) checked, {drifted} with drift.")
+ return 1 if (drifted or unreadable) else 0
+
+
+def main() -> int:
+ return asyncio.run(_run(_parse_args()))
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/core/switch_core/clients/admin_client.py b/core/switch_core/clients/admin_client.py
index 6d460b923..5b2c6dba6 100644
--- a/core/switch_core/clients/admin_client.py
+++ b/core/switch_core/clients/admin_client.py
@@ -1,9 +1,7 @@
from __future__ import annotations
import logging
-from typing import TYPE_CHECKING, Any, Literal
-
-from nio import MatrixRoom, RoomMessage, RoomMessageText
+from typing import TYPE_CHECKING, Literal, Unpack
from switch_core.agent_display_name import agent_label_with_identifier
from switch_core.bridges.agent.commands import dispatch_admin_command
@@ -13,7 +11,11 @@ from switch_core.clients.admin_messages import (
AdminMessageType,
admin_extra_content,
)
-from switch_core.clients.client_base import ClientBase, ClientConfig
+from switch_core.clients.client_base import (
+ ClientBase,
+ ClientBaseKwargs,
+ ClientConfig,
+)
from switch_core.clients.mentions import (
mention_regex,
strip_emphasis,
@@ -27,6 +29,7 @@ from switch_core.db.stores.reference_store import ReferenceStore
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.events import CommandEvent
+from switch_core.transport import InboundMessage, RoomRef
if TYPE_CHECKING:
from switch_core.room_service import RoomService
@@ -61,7 +64,7 @@ class AdminClient(ClientBase[ClientConfig]):
agent_session_store: AgentSessionStore,
room_service: RoomService,
frontend_base_url: str | None,
- **kwargs: Any,
+ **kwargs: Unpack[ClientBaseKwargs[ClientConfig]],
) -> None:
super().__init__(**kwargs)
self._agent_store = agent_store
@@ -80,8 +83,8 @@ class AdminClient(ClientBase[ClientConfig]):
# ── Event hooks ───────────────────────────────────────────────────────────
- async def on_message(self, room: MatrixRoom, event: RoomMessageText) -> None:
- content = event.source.get("content", {}) or {}
+ async def on_message(self, room: RoomRef, event: InboundMessage) -> None:
+ content = event.content
# Never react to admin/system messages — including our own notices —
# so the rail can't loop on itself.
if ADMIN_MARKER in content:
@@ -94,16 +97,13 @@ class AdminClient(ClientBase[ClientConfig]):
if meta is None:
return
- thread_id: str | None = None
- relates = content.get("m.relates_to") or {}
- if relates.get("rel_type") == "m.thread":
- thread_id = relates.get("event_id")
+ thread_id = event.thread_root_id
thread_root = thread_id if thread_id is not None else event.event_id
await self._warn_unreachable_roles(room, event, meta.room_id, thread_root)
await self._warn_absent_agents(room, event, meta.room_id, thread_root)
- async def on_command(self, room: MatrixRoom, event: CommandEvent) -> None:
+ async def on_command(self, room: RoomRef, event: CommandEvent) -> None:
await dispatch_admin_command(self, room, event)
async def reply_command(
@@ -128,8 +128,8 @@ class AdminClient(ClientBase[ClientConfig]):
async def _warn_unreachable_roles(
self,
- room: MatrixRoom,
- event: RoomMessage,
+ room: RoomRef,
+ event: InboundMessage,
room_id: str,
thread_id: str | None,
) -> None:
@@ -170,8 +170,8 @@ class AdminClient(ClientBase[ClientConfig]):
async def _warn_absent_agents(
self,
- room: MatrixRoom,
- event: RoomMessage,
+ room: RoomRef,
+ event: InboundMessage,
room_id: str,
thread_id: str | None,
) -> None:
@@ -244,7 +244,7 @@ class AdminClient(ClientBase[ClientConfig]):
extra_content=admin_extra_content(message_type),
)
- def _sender_handle(self, event: RoomMessage) -> str:
+ def _sender_handle(self, event: InboundMessage) -> str:
"""The @-handle to tag the message sender with.
Prefers the bridge-provided `sender_name` (the external username, which
@@ -252,7 +252,7 @@ class AdminClient(ClientBase[ClientConfig]):
Mattermost); falls back to the mxid localpart for a native Matrix user
(paired with `mentions=[event.sender]` so Matrix renders a pill).
"""
- content = event.source.get("content", {}) or {}
+ content = event.content
name = content.get("sender_name")
if name:
return str(name)
diff --git a/core/switch_core/clients/agent_client.py b/core/switch_core/clients/agent_client.py
index 92439c734..554c448b2 100644
--- a/core/switch_core/clients/agent_client.py
+++ b/core/switch_core/clients/agent_client.py
@@ -5,18 +5,8 @@ import logging
import random
import re
from dataclasses import dataclass, field
-from typing import Literal, NamedTuple
-
-from nio import (
- MatrixRoom,
- RoomMemberEvent,
- RoomMessage,
- RoomMessageMedia,
- RoomMessageText,
-)
-from sqlalchemy.ext.asyncio import AsyncSession
+from typing import TYPE_CHECKING, Literal, NamedTuple, Unpack
-from switch_core.addressing import SenderKind, can_address, parse_policy
from switch_core.attachments import parse_attachment_group
from switch_core.bridges.agent.commands import (
AGENT_GREETINGS,
@@ -38,16 +28,11 @@ from switch_core.bridges.agent.protocol.types import (
TaskFinalisePayload,
TaskUpdatePayload,
)
-from switch_core.bridges.agent.request_tracker import RequestTracker
-from switch_core.bridges.resource.events import (
- ResourceLoadResponse,
- RoomDocumentCreateResponse,
- RoomDocumentDeleteResponse,
- RoomDocumentUpdateResponse,
+from switch_core.clients.client_base import (
+ ClientBase,
+ ClientBaseKwargs,
+ ClientConfig,
)
-from switch_core.bridges.resource.tracker import ResourceRequestTracker
-from switch_core.clients.admin_messages import ADMIN_MARKER
-from switch_core.clients.client_base import ClientBase, ClientConfig
from switch_core.clients.mentions import (
NAME_CHAR as _NAME_CHAR,
)
@@ -67,11 +52,15 @@ from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.reference_store import ReferenceStore
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
+from switch_core.delivery.addressing import (
+ ADDRESSING_DENIED_MESSAGE,
+ ADDRESSING_UNCLAIMED_MESSAGE,
+ AddressingDecision,
+ AddressingResolver,
+ IncomingMessage,
+)
from switch_core.events import (
CommandEvent,
- MediationLlmResponse,
- MediationResult,
- MediationToolResult,
TaskAccept,
TaskCancel,
TaskDelegate,
@@ -79,6 +68,15 @@ from switch_core.events import (
TaskUpdate,
)
from switch_core.gateway.known_agents import known_agent_for
+from switch_core.transport import (
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+ RoomRef,
+)
+
+if TYPE_CHECKING:
+ from sqlalchemy.ext.asyncio import AsyncSession
logger = logging.getLogger(__name__)
@@ -113,7 +111,7 @@ class _PendingAttachmentGroup:
# The index-0 event, kept so a group that has to be flushed incomplete is
# still anchored on its canonical first part (message_id / timestamp /
# sender) rather than on whichever part happened to arrive last.
- first_event: RoomMessageMedia | None = None
+ first_event: InboundMedia | None = None
_UNAVAILABLE_MESSAGES = {
@@ -191,45 +189,11 @@ def _offline_owner_message(
return f"{opening} {terminal}\n\n```\n{cmd}\n```"
-# Posted (once, guarded by AUTO_REPLY_FLAG) when a sender tags this agent but
-# the agent's scoped addressing policy does not permit that sender to address
-# it here. The message is demoted to unaddressed room chatter; this reply is
-# the sender's only feedback that the attempt was rejected.
-_ADDRESSING_DENIED_MESSAGE = (
- "You're not permitted to direct messages to me in this room — my operator "
- "has restricted who can address me here."
-)
-
-
-# The same refusal, for the case worth telling apart: the agent answers only to
-# its owner, and the sender's chat account is not linked to any Switch user, so
-# it cannot be recognised as the owner even if it is. Without this the owner
-# gets refused by their own agent with no idea why.
-_ADDRESSING_UNCLAIMED_MESSAGE = (
- "I only take instructions from my owner, and this chat account isn't "
- "linked to a Switch user yet — so I can't tell whether that's you. If it "
- "is, link this account to your Switch user in Switch Console and try again."
-)
-
-
-class _SenderPrincipal(NamedTuple):
- """Who a Matrix sender turned out to be, in the terms a policy is written
- in. `user_ids` and `owner_user_id` are the two ways a symbolic subject
- resolves, and are mutually exclusive: a human has claimants, an agent has
- an owner."""
-
- kind: SenderKind
- id: str
- user_ids: list[str]
- owner_user_id: str | None
-
-
-class _AddressingDecision(NamedTuple):
- """The outcome of checking a sender against an agent's addressing policy,
- carrying the wording to reply with so the caller need not re-derive why."""
-
- allowed: bool
- refusal: str
+# The refusal wording lives with the decision that produces it. Kept under
+# these names because they are how the rest of the package and its tests refer
+# to them.
+_ADDRESSING_DENIED_MESSAGE = ADDRESSING_DENIED_MESSAGE
+_ADDRESSING_UNCLAIMED_MESSAGE = ADDRESSING_UNCLAIMED_MESSAGE
class _GateOutcome(NamedTuple):
@@ -272,13 +236,11 @@ class AgentClient(ClientBase[ClientConfig]):
agent_session_store: AgentSessionStore,
room_role_store: RoomRoleStore,
external_user_store: ExternalUserStore,
- request_tracker: RequestTracker,
- resource_request_tracker: ResourceRequestTracker,
connections: ConnectionRegistry,
frontend_base_url: str | None,
- **kwargs: object,
+ **kwargs: Unpack[ClientBaseKwargs[ClientConfig]],
) -> None:
- super().__init__(**kwargs) # type: ignore[arg-type]
+ super().__init__(**kwargs)
self._event_buffer = event_buffer
self._agent_store = agent_store
self._room_store = room_store
@@ -288,13 +250,21 @@ class AgentClient(ClientBase[ClientConfig]):
self._agent_session_store = agent_session_store
self._room_role_store = room_role_store
self._external_user_store = external_user_store
- self._request_tracker = request_tracker
- self._resource_request_tracker = resource_request_tracker
self._connections = connections
self._frontend_base_url = (
frontend_base_url.rstrip("/") if frontend_base_url else None
)
self._agent: Agent | None = None
+ # Addressing is decided from stores, not from this client, so the same
+ # rules can decide for a message read out of the log.
+ self._addressing = AddressingResolver(
+ room_store=room_store,
+ room_role_store=room_role_store,
+ client_store=self.client_store,
+ agent_store=agent_store,
+ external_user_store=external_user_store,
+ live_agent_ids=connections.live_agent_ids,
+ )
self._room_meta: dict[str, RoomMeta | None] = {}
# In-flight multi-attachment groups, by group id, with their safety-net
# timers. Both are cleared when a group completes or times out, so a
@@ -336,7 +306,7 @@ class AgentClient(ClientBase[ClientConfig]):
# ── Event hooks ───────────────────────────────────────────────────────────
- async def on_self_join(self, room: MatrixRoom, event: RoomMemberEvent) -> None:
+ async def on_self_join(self, room: RoomRef, event: InboundMembership) -> None:
is_direct = await self._is_direct_room(room.room_id)
name = self.agent.name
# The per-agent self-join greeting can be switched off per bridge
@@ -357,7 +327,29 @@ class AgentClient(ClientBase[ClientConfig]):
greeting = random.choice(AGENT_GREETINGS).format(name=name)
await self.send_message(room.room_id, greeting, format="markdown")
- async def on_member_event(self, room: MatrixRoom, event: RoomMemberEvent) -> None:
+ async def _member_name(
+ self, session: AsyncSession, event: InboundMembership
+ ) -> str:
+ """What to call the member who just arrived.
+
+ The name Switch knows them by, not the one on the membership event: a
+ profile is set from whatever the source platform calls someone, so
+ taking it makes the same person read one way when they arrive and
+ another way when they speak — and the log, which records the Switch
+ name, disagree with what was delivered live.
+ """
+ client = await self.client_store.get_by_matrix_user_id(session, event.state_key)
+ if client is not None:
+ return client.display_name
+ fallback = event.display_name or event.state_key.split(":")[0].lstrip("@")
+ logger.warning(
+ "No Switch client owns %s; naming the arrival %r from the membership event",
+ event.state_key,
+ fallback,
+ )
+ return fallback
+
+ async def on_member_event(self, room: RoomRef, event: InboundMembership) -> None:
# Only forward genuine joins. A membership-preserving update (e.g. a
# display-name or avatar change) re-fires m.room.member with
# membership == "join" and prev_membership == "join" — exclude those, and
@@ -369,9 +361,6 @@ class AgentClient(ClientBase[ClientConfig]):
meta = await self._resolve_room_meta(room.room_id)
if meta is None:
return
- member_name = event.content.get("displayname") or event.state_key.split(":")[
- 0
- ].lstrip("@")
# `listening` tells each connector whether THIS receiving agent is
# configured to react to join events in this room. The event is always
# delivered; the connector decides whether to surface it.
@@ -379,6 +368,7 @@ class AgentClient(ClientBase[ClientConfig]):
listening = await self._room_store.get_receives_join_events(
session, meta.room_id, self.agent.id
)
+ member_name = await self._member_name(session, event)
self._event_buffer.enqueue(
self.agent.id,
meta.room_id,
@@ -390,21 +380,18 @@ class AgentClient(ClientBase[ClientConfig]):
payload=RoomJoinPayload(
member=event.state_key,
member_name=member_name,
- timestamp=event.server_timestamp,
+ timestamp=event.timestamp,
listening=listening,
),
),
)
- async def on_message(self, room: MatrixRoom, event: RoomMessageText) -> None:
+ async def on_message(self, room: RoomRef, event: InboundMessage) -> None:
meta = await self._resolve_room_meta(room.room_id)
if meta is None:
return
- thread_id: str | None = None
- relates = event.source.get("content", {}).get("m.relates_to") or {}
- if relates.get("rel_type") == "m.thread":
- thread_id = relates.get("event_id")
+ thread_id = event.thread_root_id
reply_thread_root = thread_id if thread_id is not None else event.event_id
@@ -459,7 +446,7 @@ class AgentClient(ClientBase[ClientConfig]):
text = event.body
- sender_name = event.source.get("content", {}).get("sender_name")
+ sender_name = event.sender_name
if not sender_name:
sender_name = event.sender
logger.error(
@@ -478,7 +465,7 @@ class AgentClient(ClientBase[ClientConfig]):
sender_name=sender_name,
message_id=event.event_id,
body=text,
- timestamp=event.server_timestamp,
+ timestamp=event.timestamp,
thread_id=thread_id,
),
)
@@ -490,26 +477,24 @@ class AgentClient(ClientBase[ClientConfig]):
agent_event,
)
- async def on_media(self, room: MatrixRoom, event: RoomMessageMedia) -> None:
+ async def on_media(self, room: RoomRef, event: InboundMedia) -> None:
meta = await self._resolve_room_meta(room.room_id)
if meta is None:
return
is_addressed = await self._addressed(event, meta)
- content = event.source.get("content", {})
- info = content.get("info", {}) or {}
+ content = event.content
# With a caption, body is the caption text and the real filename lives in
# `filename`; without one, body is the filename itself.
- filename = content.get("filename") or event.body
attachment = AttachmentRef(
- filename=filename,
- mimetype=str(info.get("mimetype", "")),
- size=int(info.get("size", 0) or 0),
- mxc=str(event.url),
- msgtype=str(content.get("msgtype", "")),
+ filename=event.filename or event.body,
+ mimetype=event.mimetype or "",
+ size=event.size or 0,
+ mxc=event.uri,
+ msgtype=event.msgtype,
)
- sender_name = content.get("sender_name")
+ sender_name = event.sender_name
if not sender_name:
sender_name = event.sender
logger.error(
@@ -518,10 +503,7 @@ class AgentClient(ClientBase[ClientConfig]):
)
# Mirror on_message: surface the thread this media belongs to (if any).
- thread_id: str | None = None
- relates = content.get("m.relates_to") or {}
- if relates.get("rel_type") == "m.thread":
- thread_id = relates.get("event_id")
+ thread_id = event.thread_root_id
# Several files posted as one message arrive as separate Matrix events
# sharing a group marker (Matrix has no multi-attachment event). Hold
@@ -574,8 +556,8 @@ class AgentClient(ClientBase[ClientConfig]):
def _schedule_attachment_group_flush(
self,
group_id: str,
- room: MatrixRoom,
- event: RoomMessageMedia,
+ room: RoomRef,
+ event: InboundMedia,
meta: RoomMeta,
sender_name: str,
thread_id: str | None,
@@ -610,8 +592,8 @@ class AgentClient(ClientBase[ClientConfig]):
async def _flush_incomplete_attachment_group(
self,
group_id: str,
- room: MatrixRoom,
- event: RoomMessageMedia,
+ room: RoomRef,
+ event: InboundMedia,
meta: RoomMeta,
sender_name: str,
thread_id: str | None,
@@ -650,8 +632,8 @@ class AgentClient(ClientBase[ClientConfig]):
async def _emit_media(
self,
- room: MatrixRoom,
- event: RoomMessageMedia,
+ room: RoomRef,
+ event: InboundMedia,
meta: RoomMeta,
is_addressed: bool,
sender_name: str,
@@ -681,7 +663,7 @@ class AgentClient(ClientBase[ClientConfig]):
sender_name=sender_name,
message_id=event.event_id,
body=body,
- timestamp=event.server_timestamp,
+ timestamp=event.timestamp,
thread_id=thread_id,
attachments=attachments,
),
@@ -694,7 +676,7 @@ class AgentClient(ClientBase[ClientConfig]):
agent_event,
)
- async def on_command(self, room: MatrixRoom, event: CommandEvent) -> None:
+ async def on_command(self, room: RoomRef, event: CommandEvent) -> None:
meta = await self._resolve_room_meta(room.room_id)
if meta is None:
return
@@ -751,7 +733,7 @@ class AgentClient(ClientBase[ClientConfig]):
return await self._text_tags_my_role(session, args, room_id)
async def _gate_command(
- self, room: MatrixRoom, event: CommandEvent, meta: RoomMeta
+ self, room: RoomRef, event: CommandEvent, meta: RoomMeta
) -> bool:
"""Apply the addressing policy to a command aimed at this agent.
@@ -794,7 +776,7 @@ class AgentClient(ClientBase[ClientConfig]):
# ── Command handling ──────────────────────────────────────────────────────
- async def _handle_command(self, room: MatrixRoom, event: CommandEvent) -> bool:
+ async def _handle_command(self, room: RoomRef, event: CommandEvent) -> bool:
is_direct = await self._is_direct_room(room.room_id)
return await dispatch_command(self, room, event, is_direct)
@@ -1067,7 +1049,7 @@ class AgentClient(ClientBase[ClientConfig]):
# ── Task event forwarding ────────────────────────────────────────────────
- async def on_task_delegate(self, room: MatrixRoom, event: TaskDelegate) -> None:
+ async def on_task_delegate(self, room: RoomRef, event: TaskDelegate) -> None:
if event.performer_agent_id != self.agent.id:
return
await self.send_message(room.room_id, "Working on it.", format="markdown")
@@ -1092,7 +1074,7 @@ class AgentClient(ClientBase[ClientConfig]):
),
)
- async def on_task_accept(self, room: MatrixRoom, event: TaskAccept) -> None:
+ async def on_task_accept(self, room: RoomRef, event: TaskAccept) -> None:
if event.requester_agent_id != self.agent.id:
return
meta = await self._resolve_room_meta(room.room_id)
@@ -1114,7 +1096,7 @@ class AgentClient(ClientBase[ClientConfig]):
),
)
- async def on_task_update(self, room: MatrixRoom, event: TaskUpdate) -> None:
+ async def on_task_update(self, room: RoomRef, event: TaskUpdate) -> None:
if event.requester_agent_id != self.agent.id:
return
meta = await self._resolve_room_meta(room.room_id)
@@ -1137,7 +1119,7 @@ class AgentClient(ClientBase[ClientConfig]):
),
)
- async def on_task_finalise(self, room: MatrixRoom, event: TaskFinalise) -> None:
+ async def on_task_finalise(self, room: RoomRef, event: TaskFinalise) -> None:
if event.requester_agent_id != self.agent.id:
return
meta = await self._resolve_room_meta(room.room_id)
@@ -1160,7 +1142,7 @@ class AgentClient(ClientBase[ClientConfig]):
),
)
- async def on_task_cancel(self, room: MatrixRoom, event: TaskCancel) -> None:
+ async def on_task_cancel(self, room: RoomRef, event: TaskCancel) -> None:
if event.performer_agent_id != self.agent.id:
return
meta = await self._resolve_room_meta(room.room_id)
@@ -1183,56 +1165,20 @@ class AgentClient(ClientBase[ClientConfig]):
),
)
- # ── Post-invocation mediation ──────────────────────────────────────────────
-
- async def on_mediation_tool_result(
- self, room: MatrixRoom, event: MediationToolResult
- ) -> None:
- if event.agent_id != self.agent.id:
- return
- result = MediationResult(verdict=event.status)
- self._request_tracker.resolve(event.request_id, result)
-
- async def on_mediation_llm_response(
- self, room: MatrixRoom, event: MediationLlmResponse
- ) -> None:
- if event.agent_id != self.agent.id:
- return
- result = MediationResult(verdict=event.status)
- self._request_tracker.resolve(event.request_id, result)
-
- async def on_resource_load_response(
- self, room: MatrixRoom, event: ResourceLoadResponse
- ) -> None:
- if event.agent_id != self.agent.id:
- return
- self._resource_request_tracker.resolve(event.request_id, event)
-
- async def on_room_document_create_response(
- self, room: MatrixRoom, event: RoomDocumentCreateResponse
- ) -> None:
- if event.agent_id != self.agent.id:
- return
- self._resource_request_tracker.resolve(event.request_id, event)
-
- async def on_room_document_update_response(
- self, room: MatrixRoom, event: RoomDocumentUpdateResponse
- ) -> None:
- if event.agent_id != self.agent.id:
- return
- self._resource_request_tracker.resolve(event.request_id, event)
-
- async def on_room_document_delete_response(
- self, room: MatrixRoom, event: RoomDocumentDeleteResponse
- ) -> None:
- if event.agent_id != self.agent.id:
- return
- self._resource_request_tracker.resolve(event.request_id, event)
-
# ── Mention detection ─────────────────────────────────────────────────────
+ @staticmethod
+ def _as_incoming(event: InboundMessage) -> IncomingMessage:
+ """The parts of a bus event that addressing is decided from."""
+ return IncomingMessage(
+ sender=event.sender,
+ body=getattr(event, "body", "") or "",
+ formatted_body=getattr(event, "formatted_body", None),
+ content=event.content,
+ )
+
def _addressed_without_lookup(
- self, event: RoomMessage, meta: RoomMeta
+ self, event: InboundMessage, meta: RoomMeta
) -> bool | None:
"""The addressing answer that needs no database read, or None when the
room's aliases and role leases have to be consulted.
@@ -1241,17 +1187,14 @@ class AgentClient(ClientBase[ClientConfig]):
chatter carries no `@` and is answered here, and a room fans every
message out to all of its agent clients at once.
"""
- if ADMIN_MARKER in (event.source.get("content") or {}):
- return False
- if meta.channel_type == "direct":
- return True
- if self._is_mentioned(event):
- return True
- if "@" not in (getattr(event, "body", "") or ""):
- return False
- return None
+ return self._addressing.addressed_without_lookup(
+ agent=self.agent,
+ agent_matrix_id=self.matrix_user_id,
+ channel_type=meta.channel_type,
+ message=self._as_incoming(event),
+ )
- async def _addressed(self, event: RoomMessage, meta: RoomMeta) -> bool:
+ async def _addressed(self, event: InboundMessage, meta: RoomMeta) -> bool:
"""`_compute_addressed`, in a session of its own when it needs one."""
decided = self._addressed_without_lookup(event, meta)
if decided is not None:
@@ -1260,144 +1203,36 @@ class AgentClient(ClientBase[ClientConfig]):
return await self._compute_addressed(session, event, meta)
async def _compute_addressed(
- self, session: AsyncSession, event: RoomMessage, meta: RoomMeta
+ self, session: AsyncSession, event: InboundMessage, meta: RoomMeta
) -> bool:
- """Whether this message addresses this agent (expects a response).
-
- Direct rooms always address. Otherwise the agent is addressed by an
- `@name` mention OR by an `@<role>` tag for a room-role it currently
- holds (see `_is_mentioned_via_role`).
-
- **A system message never addresses anyone**, whatever the room type.
- Switch's own notices — a command's answer, "Added X to this room", the
- guidance shown when someone tags the app itself — are output, not a
- request for a reply. Two ways they were read as one: in a direct room
- every message addresses the agent, so running `/list-agents` in a 1:1
- chat had the agent start a session to respond to its own roster; and in
- any room, a notice that lists the agents present writes each `@name`,
- which tagged every one of them. The marker exists to say "generated by
- Switch"; this is it being honoured.
- """
- decided = self._addressed_without_lookup(event, meta)
- if decided is not None:
- return decided
- if await self._is_mentioned_via_alias(session, event, meta.room_id):
- return True
- return await self._is_mentioned_via_role(session, event, meta.room_id)
-
- async def _resolve_sender_principal(
- self, session: AsyncSession, matrix_user_id: str
- ) -> _SenderPrincipal | None:
- """Resolve a Matrix sender to an addressing principal.
-
- Maps the sender's mxid to its Client, then to either an Agent (an
- agent-to-agent attempt) or an ExternalUser (a human on a bridge).
- Returns ``None`` when the sender has no such record — an
- unresolvable identity that a restricted agent should not trust.
-
- The two symbolic subjects resolve from different fields, and only one
- applies to any given sender: ``user_ids`` are the Switch users who have
- claimed a human's platform account (empty for an agent — an agent is
- never its owner, even its owner's own), and ``owner_user_id`` is who
- owns an agent sender (None for a human).
- """
- client = await self.client_store.get_by_matrix_user_id(session, matrix_user_id)
- if client is None:
- return None
- agent = await self._agent_store.get_by_client_id(session, client.id)
- if agent is not None:
- return _SenderPrincipal("agent", agent.id, [], agent.owner_id)
- external_user = await self._external_user_store.get_by_client_id(
- session, client.id
+ return await self._addressing.addresses(
+ session,
+ agent=self.agent,
+ agent_matrix_id=self.matrix_user_id,
+ room_id=meta.room_id,
+ channel_type=meta.channel_type,
+ message=self._as_incoming(event),
)
- if external_user is not None:
- claimants = await self._external_user_store.claimant_ids(
- session, external_user.id
- )
- return _SenderPrincipal("user", external_user.id, claimants, None)
- return None
async def _addressing_allowed(
self, session: AsyncSession, agent: Agent, matrix_sender: str, room_id: str
- ) -> _AddressingDecision:
+ ) -> AddressingDecision:
"""Whether `matrix_sender` may address this agent in `room_id`, per the
agent's scoped addressing policy.
- An agent with no policy is open to anyone, so this returns allowed
- without a DB round-trip. With a policy set it is deny-by-default: an
- unresolvable sender is rejected (fail-closed). A denial carries the
- wording to send back, which differs when the sender looks like someone
- whose platform identity simply has not been claimed yet.
+ `agent` is the freshly-read row rather than the cached snapshot: the
+ policy is the thing being enforced, and enforcing a stale copy of it is
+ the one way this check can be wrong in the dangerous direction.
"""
- policy = parse_policy(agent.addressing_policy)
- if policy.is_open():
- return _AddressingDecision(allowed=True, refusal="")
- principal = await self._resolve_sender_principal(session, matrix_sender)
- room = await self._room_store.get(session, room_id)
- if principal is None:
- logger.warning(
- "Addressing denied for %s: unresolvable sender %s in room %s",
- self.agent.name,
- matrix_sender,
- room_id,
- )
- return _AddressingDecision(
- allowed=False, refusal=_ADDRESSING_DENIED_MESSAGE
- )
- sender_kind, sender_id, sender_user_ids = (
- principal.kind,
- principal.id,
- principal.user_ids,
- )
- group_id = room.group_id if room is not None else None
- allowed = can_address(
- policy,
- room_id=room_id,
- group_id=group_id,
- sender_kind=sender_kind,
- sender_id=sender_id,
- sender_user_ids=sender_user_ids,
- sender_owner_user_id=principal.owner_user_id,
- owner_user_id=agent.owner_id,
- )
- if allowed:
- return _AddressingDecision(allowed=True, refusal="")
- unclaimed = (
- sender_kind == "user"
- and not sender_user_ids
- and policy.requires_owner_identity()
- )
- if unclaimed:
- logger.warning(
- "Addressing denied for %s: sender %s in room %s has not been "
- "claimed by any Switch user, so an owner-scoped rule cannot "
- "match them — the owner may need to link this identity",
- self.agent.name,
- sender_id,
- room_id,
- )
- else:
- logger.warning(
- "Addressing denied for %s: %s %s not permitted in room %s",
- self.agent.name,
- sender_kind,
- sender_id,
- room_id,
- )
- return _AddressingDecision(
- allowed=False,
- refusal=(
- _ADDRESSING_UNCLAIMED_MESSAGE
- if unclaimed
- else _ADDRESSING_DENIED_MESSAGE
- ),
+ return await self._addressing.permitted(
+ session, agent=agent, room_id=room_id, sender=matrix_sender
)
async def _gate_addressed(
self,
session: AsyncSession,
agent: Agent,
- event: RoomMessage,
+ event: InboundMessage,
meta: RoomMeta,
) -> _GateOutcome:
"""Apply the scoped addressing policy to a message that tags this agent.
@@ -1418,13 +1253,13 @@ class AgentClient(ClientBase[ClientConfig]):
return _GateOutcome(addressed=False, refusal=decision.refusal)
@staticmethod
- def _triggered_by_auto_reply(event: RoomMessage) -> bool:
- return bool(event.source.get("content", {}).get(AUTO_REPLY_FLAG))
+ def _triggered_by_auto_reply(event: InboundMessage) -> bool:
+ return bool(event.content.get(AUTO_REPLY_FLAG))
async def _post_auto_reply(
self,
matrix_room_id: str,
- event: RoomMessage,
+ event: InboundMessage,
msg: str,
thread_root_id: str | None,
) -> None:
@@ -1449,65 +1284,24 @@ class AgentClient(ClientBase[ClientConfig]):
async def _text_tags_my_alias(
self, session: AsyncSession, text: str, room_id: str
) -> bool:
- """True when `text` `@`-tags this agent's room alias at a token boundary.
-
- The alias is looked up live (like a role lease) so a change takes effect
- on the next message without any per-client cache to invalidate.
- """
- if "@" not in text:
- return False
- alias = await self._room_store.get_alias(session, room_id, self.agent.id)
- if not alias:
- return False
- return _mention_regex(alias).search(text) is not None
-
- async def _is_mentioned_via_alias(
- self, session: AsyncSession, event: RoomMessage, room_id: str
- ) -> bool:
- """True when the message body tags this agent's room alias.
-
- A room alias addresses the agent exactly like its real name, so an
- `@<alias>` mention routes here just as `@<name>` does.
- """
- return await self._text_tags_my_alias(
- session, getattr(event, "body", "") or "", room_id
+ return await self._addressing.mentions_alias(
+ session,
+ agent=self.agent,
+ room_id=room_id,
+ message=IncomingMessage(sender="", body=text),
)
async def _text_tags_my_role(
self, session: AsyncSession, text: str, room_id: str
) -> bool:
- """True when `text` `@`-tags a room-role this agent LIVE-holds.
-
- Only a live lease counts, so "held" means the same thing here as in
- `!roles` and the moderator warning: a stale lease (session gone, role
- auto-released → shown free) does NOT route here — the moderator flags
- it as unassigned instead. A holder whose session merely hopped to
- another room still matches, because that lease is kept alive by the
- renewal loop. The moderator holds no role, so this is a no-op for it.
- """
- if "@" not in text:
- return False
- role_name = await self._room_role_store.agent_room_role(
- session, room_id, self.agent.id, self._connections.live_agent_ids()
- )
- if not role_name:
- return False
- return _mention_regex(role_name).search(_strip_emphasis(text)) is not None
-
- async def _is_mentioned_via_role(
- self, session: AsyncSession, event: RoomMessage, room_id: str
- ) -> bool:
- """True when the message body tags a room-role this agent holds.
-
- Tagging `@<role>` addresses whichever agent holds that role, so an
- interchangeable agent can be reached by responsibility rather than by
- name.
- """
- return await self._text_tags_my_role(
- session, getattr(event, "body", "") or "", room_id
+ return await self._addressing.mentions_role(
+ session,
+ agent=self.agent,
+ room_id=room_id,
+ message=IncomingMessage(sender="", body=text),
)
- def _sender_handle(self, event: RoomMessage) -> str:
+ def _sender_handle(self, event: InboundMessage) -> str:
"""The @-handle to tag the message sender with.
Prefers the bridge-provided `sender_name` (the external username, which
@@ -1515,21 +1309,17 @@ class AgentClient(ClientBase[ClientConfig]):
Mattermost); falls back to the mxid localpart for a native Matrix user
(paired with `mentions=[event.sender]` so Matrix renders a pill).
"""
- content = event.source.get("content", {}) or {}
+ content = event.content
name = content.get("sender_name")
if name:
return str(name)
return str(event.sender).split(":")[0].lstrip("@")
- def _is_mentioned(self, event: RoomMessage) -> bool:
- # Media events (RoomMessageImage/File) have no formatted_body; fall back
- # to a plain-text mention scan on the body (the caption, for media).
- formatted_body = getattr(event, "formatted_body", None)
- if formatted_body is not None and self.matrix_user_id in formatted_body:
- return True
- return (
- _mention_regex(self.agent.name).search(_strip_emphasis(event.body))
- is not None
+ def _is_mentioned(self, event: InboundMessage) -> bool:
+ return self._addressing.mentions_name(
+ agent=self.agent,
+ agent_matrix_id=self.matrix_user_id,
+ message=self._as_incoming(event),
)
def _strip_mention(self, text: str) -> str:
diff --git a/core/switch_core/clients/bridge_client.py b/core/switch_core/clients/bridge_client.py
index ab860bd45..6713a6c3b 100644
--- a/core/switch_core/clients/bridge_client.py
+++ b/core/switch_core/clients/bridge_client.py
@@ -1,12 +1,15 @@
from __future__ import annotations
import logging
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Unpack
-from nio import MatrixRoom, RoomMessageMedia, RoomMessageText
-
-from switch_core.clients.client_base import ClientBase, ClientConfig
+from switch_core.clients.client_base import (
+ ClientBase,
+ ClientBaseKwargs,
+ ClientConfig,
+)
from switch_core.events import AgentRuntimeStateEvent
+from switch_core.transport import InboundMedia, InboundMessage, RoomRef
if TYPE_CHECKING:
from switch_core.bridges.collaboration.bridge_core import BridgeCore
@@ -21,11 +24,16 @@ class BridgeClientConfig(ClientConfig):
class BridgeClient(ClientBase[BridgeClientConfig]):
config_class = BridgeClientConfig
- def __init__(self, *, bridge_core: BridgeCore, **kwargs: Any) -> None:
+ def __init__(
+ self,
+ *,
+ bridge_core: BridgeCore,
+ **kwargs: Unpack[ClientBaseKwargs[BridgeClientConfig]],
+ ) -> None:
super().__init__(**kwargs)
self._bridge_core = bridge_core
- async def on_message(self, room: MatrixRoom, event: RoomMessageText) -> None:
+ async def on_message(self, room: RoomRef, event: InboundMessage) -> None:
logger.debug(
"[BRIDGE-CLIENT] on_message room=%s sender=%s",
room.room_id,
@@ -33,7 +41,7 @@ class BridgeClient(ClientBase[BridgeClientConfig]):
)
await self._bridge_core.handle_outbound_message(room, event)
- async def on_media(self, room: MatrixRoom, event: RoomMessageMedia) -> None:
+ async def on_media(self, room: RoomRef, event: InboundMedia) -> None:
logger.debug(
"[BRIDGE-CLIENT] on_media room=%s sender=%s",
room.room_id,
@@ -42,6 +50,6 @@ class BridgeClient(ClientBase[BridgeClientConfig]):
await self._bridge_core.handle_outbound_media(room, event, self)
async def on_agent_runtime_state(
- self, room: MatrixRoom, event: AgentRuntimeStateEvent
+ self, room: RoomRef, event: AgentRuntimeStateEvent
) -> None:
await self._bridge_core.handle_agent_runtime_state(room, event)
diff --git a/core/switch_core/clients/client_base.py b/core/switch_core/clients/client_base.py
index f17569b0c..c82212844 100644
--- a/core/switch_core/clients/client_base.py
+++ b/core/switch_core/clients/client_base.py
@@ -1,56 +1,19 @@
from __future__ import annotations
import asyncio
-import io
import logging
import random
import time
-from typing import Literal
-
-import markdown
-from nio import (
- AsyncClient,
- InviteMemberEvent,
- JoinedRoomsError,
- LoginError,
- MatrixRoom,
- ProfileSetDisplayNameError,
- ReactionEvent,
- RoomMemberEvent,
- RoomMessageMedia,
- RoomMessageText,
- RoomSendError,
- RoomTypingError,
- SyncError,
- SyncResponse,
- UnknownEvent,
- UploadError,
-)
+from typing import TYPE_CHECKING, Literal, NotRequired, TypedDict
+
from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
-from switch_core.attachments import ATTACHMENT_GROUP_KEY
-from switch_core.bridges.resource.events import (
- ResourceLoadRequest,
- ResourceLoadResponse,
- RoomDocumentCreateRequest,
- RoomDocumentCreateResponse,
- RoomDocumentDeleteRequest,
- RoomDocumentDeleteResponse,
- RoomDocumentUpdateRequest,
- RoomDocumentUpdateResponse,
-)
from switch_core.db.stores.client_store import ClientStore
from switch_core.events import (
AgentRuntimeStateEvent,
CommandEvent,
LlmCallReport,
- MediationLlmRequest,
- MediationLlmResponse,
- MediationToolRequest,
- MediationToolResult,
- PermissionRequest,
- PermissionResponse,
SwitchEvent,
TaskAccept,
TaskCancel,
@@ -59,6 +22,22 @@ from switch_core.events import (
TaskUpdate,
ToolCallReport,
)
+from switch_core.messages.recording import MessageRecording
+from switch_core.transport import (
+ InboundCustomEvent,
+ InboundEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+ MessageTransport,
+ RoomRef,
+ SendResult,
+ TransportError,
+ TransportHandlers,
+)
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
logger = logging.getLogger(__name__)
@@ -79,23 +58,37 @@ SYNC_BACKOFF_BASE = 1.0
SYNC_BACKOFF_CAP = 60.0
-def _carries_durable_events(response: SyncResponse) -> bool:
- """Whether a sync response holds anything a restart would need to replay.
+class ClientConfig(BaseModel):
+ pass
+
+
+class ClientBaseKwargs[ConfigT: ClientConfig](TypedDict):
+ """What every `ClientBase` subclass must forward to `ClientBase`.
- Timeline events, room state and invites are dispatched to handlers, so the
- cursor must move past them durably. Presence, typing, receipts and account
- data are not — they only advance the token.
- """
- if response.rooms.invite or response.to_device_events:
- return True
- return any(
- room.timeline.events or room.state
- for room in (*response.rooms.join.values(), *response.rooms.leave.values())
- )
+ Subclasses take their own arguments and pass the rest through. Spelled as
+ `**kwargs: Any`, that pass-through is invisible to the type checker on both
+ sides: the subclass cannot be told it is missing something, and a caller
+ cannot be told it is passing something that no longer exists. A stale
+ `device_id=` type-checked clean that way and took all four collaboration
+ bridges down at startup — the credential had moved into `session_state`
+ and nothing said so until the process refused to start.
+ Declaring the shape here and unpacking it restores both checks without
+ making every subclass restate eleven parameters.
+ """
-class ClientConfig(BaseModel):
- pass
+ client_id: str
+ matrix_user_id: str
+ display_name: str
+ password: str
+ server_url: str
+ session_factory: async_sessionmaker[AsyncSession]
+ client_store: ClientStore
+ config: ConfigT
+ transport_factory: Callable[[ClientBase[ConfigT]], MessageTransport]
+ session_state: dict[str, str | None]
+ message_recorder: MessageRecording
+ next_batch_token: NotRequired[str | None]
class ClientBase[ConfigT: ClientConfig]:
@@ -112,8 +105,9 @@ class ClientBase[ConfigT: ClientConfig]:
session_factory: async_sessionmaker[AsyncSession],
client_store: ClientStore,
config: ConfigT,
- device_id: str | None = None,
- access_token: str | None = None,
+ transport_factory: Callable[[ClientBase[ConfigT]], MessageTransport],
+ session_state: dict[str, str | None],
+ message_recorder: MessageRecording,
next_batch_token: str | None = None,
) -> None:
self.client_id = client_id
@@ -124,12 +118,15 @@ class ClientBase[ConfigT: ClientConfig]:
self.session_factory = session_factory
self.client_store = client_store
self.config = config
+ self.message_recorder = message_recorder
- self.device_id = device_id
- self.access_token = access_token
+ # Credentials the transport owns. Stored and handed back unread, so
+ # what authentication needs is the transport's business alone.
+ self.session_state = session_state
self.next_batch_token = next_batch_token
- self.nio_client: AsyncClient | None = None
+ self._transport_factory = transport_factory
+ self.transport: MessageTransport | None = None
self.room_join_times: dict[str, int] = {}
self._room_joined_events: dict[str, asyncio.Event] = {}
# Rooms this client has already announced its arrival in. Distinct from
@@ -153,17 +150,13 @@ class ClientBase[ConfigT: ClientConfig]:
await self._ready.wait()
async def set_display_name(self, display_name: str) -> None:
- """Change the name this client shows under in Matrix.
+ """Change the name this client shows under.
The user id is an address and stays put; this is the label rooms
render. Used to correct a puppet filed under a platform id before the
platform would say who the person was.
"""
- resp = await self.client.set_displayname(display_name)
- if isinstance(resp, ProfileSetDisplayNameError):
- raise RuntimeError(
- f"Could not set the display name of {self.matrix_user_id}: {resp}"
- )
+ await self._transport.set_display_name(display_name)
self.display_name = display_name
def _joined_event(self, room_id: str) -> asyncio.Event:
@@ -178,15 +171,7 @@ class ClientBase[ConfigT: ClientConfig]:
self._joined_event(room_id).set()
async def _is_joined_on_server(self, room_id: str) -> bool:
- resp = await self.client.joined_rooms()
- if isinstance(resp, JoinedRoomsError):
- logger.error(
- "Failed to list joined rooms for %s: %s",
- self.matrix_user_id,
- resp.message,
- )
- return False
- return room_id in resp.rooms
+ return room_id in await self._transport.joined_rooms()
async def wait_joined(self, room_id: str, timeout: float) -> bool:
"""Block until this client is a member of `room_id`, up to `timeout`
@@ -214,12 +199,12 @@ class ClientBase[ConfigT: ClientConfig]:
return True
@property
- def client(self) -> AsyncClient:
- if self.nio_client is None:
+ def _transport(self) -> MessageTransport:
+ if self.transport is None:
raise RuntimeError(
f"Client {self.matrix_user_id} is not connected — call start() first"
)
- return self.nio_client
+ return self.transport
# ── Lifecycle ──────────────────────────────────────────────────────────────
@@ -234,9 +219,7 @@ class ClientBase[ConfigT: ClientConfig]:
retries = 0
while self._running:
try:
- await self.client.sync_forever(
- timeout=30000, since=self.next_batch_token
- )
+ await self._transport.receive_forever(since=self.next_batch_token)
retries = 0
except Exception:
if not self._running:
@@ -264,20 +247,22 @@ class ClientBase[ConfigT: ClientConfig]:
self._running = False
await self._persist_state(force=True)
await self.teardown()
- if self.nio_client:
- await self.nio_client.close()
+ if self.transport is not None:
+ await self.transport.close()
def setup(self) -> None:
- self.client.add_event_callback(self._handle_message, RoomMessageText)
- # RoomMessageMedia is the base of RoomMessageImage / RoomMessageFile, so
- # one callback covers every media msgtype.
- self.client.add_event_callback(self._handle_media, RoomMessageMedia)
- self.client.add_event_callback(self._handle_reaction, ReactionEvent)
- self.client.add_event_callback(self._handle_member_event, RoomMemberEvent)
- self.client.add_event_callback(self._handle_custom_event, UnknownEvent)
- self.client.add_event_callback(self._handle_invite, InviteMemberEvent) # type: ignore[arg-type]
- self.client.add_response_callback(self._handle_sync, SyncResponse)
- self.client.add_response_callback(self._handle_sync_error, SyncError)
+ self._transport.register_handlers(
+ TransportHandlers(
+ on_message=self._handle_message,
+ on_media=self._handle_media,
+ on_reaction=self._handle_reaction,
+ on_member_event=self._handle_member_event,
+ on_custom_event=self._handle_custom_event,
+ on_invite=self._handle_invite,
+ on_sync=self._handle_sync,
+ on_sync_error=self._handle_sync_error,
+ )
+ )
async def teardown(self) -> None:
pass
@@ -285,32 +270,22 @@ class ClientBase[ConfigT: ClientConfig]:
# ── Authentication ─────────────────────────────────────────────────────────
async def _create_client(self) -> None:
- self.nio_client = AsyncClient(self.server_url, self.matrix_user_id)
-
- if self.access_token and self.device_id:
- self.client.access_token = self.access_token
- self.client.device_id = self.device_id
- logger.info(
- "Client %s restored session from stored token", self.matrix_user_id
- )
- elif self.password:
- resp = await self.client.login(self.password)
- if isinstance(resp, LoginError):
- raise RuntimeError(
- f"Login failed for {self.matrix_user_id}: {resp.message}"
- )
- self.device_id = resp.device_id
- self.access_token = self.client.access_token
+ before = dict(self.session_state)
+ self.transport = self._transport_factory(self)
+ await self.transport.connect()
+ self._absorb_session_state()
+ if self.session_state != before:
await self._persist_state(force=True)
- logger.info("Client %s authenticated via password", self.matrix_user_id)
- else:
- raise RuntimeError(f"No credentials available for {self.matrix_user_id}")
self._ready.set()
+ def _absorb_session_state(self) -> None:
+ """Take back whatever the transport wants persisted, without reading it."""
+ self.session_state = dict(self._transport.session_state)
+
# ── Internal event handlers (filtering + dispatch to hooks) ────────────────
- async def _handle_message(self, room: MatrixRoom, event: RoomMessageText) -> None:
+ async def _handle_message(self, room: RoomRef, event: InboundMessage) -> None:
if self._should_ignore(room, event):
return
try:
@@ -320,7 +295,7 @@ class ClientBase[ConfigT: ClientConfig]:
"Error in on_message for %s in %s", self.matrix_user_id, room.room_id
)
- async def _handle_media(self, room: MatrixRoom, event: RoomMessageMedia) -> None:
+ async def _handle_media(self, room: RoomRef, event: InboundMedia) -> None:
if self._should_ignore(room, event):
return
try:
@@ -330,7 +305,7 @@ class ClientBase[ConfigT: ClientConfig]:
"Error in on_media for %s in %s", self.matrix_user_id, room.room_id
)
- async def _handle_reaction(self, room: MatrixRoom, event: ReactionEvent) -> None:
+ async def _handle_reaction(self, room: RoomRef, event: InboundEvent) -> None:
if self._should_ignore(room, event):
return
try:
@@ -341,11 +316,21 @@ class ClientBase[ConfigT: ClientConfig]:
)
async def _handle_member_event(
- self, room: MatrixRoom, event: RoomMemberEvent
+ self, room: RoomRef, event: InboundMembership
) -> None:
if event.state_key == self.matrix_user_id:
if event.membership == "join":
- self._mark_joined(room.room_id, event.server_timestamp)
+ self._mark_joined(room.room_id, event.timestamp)
+ if event.prev_membership != "join":
+ # Recorded on the arrival itself rather than under the
+ # announcement guards below: the log wants every arrival,
+ # including ones too old to be worth announcing.
+ await self.message_recorder.record_join(
+ transport_room_id=room.room_id,
+ event=event,
+ client_id=self.client_id,
+ member_name=self.display_name,
+ )
# A membership-preserving update (display name, avatar) re-fires
# m.room.member with membership == "join"; only a transition into
# membership is an arrival. Joins predating this process are not
@@ -353,7 +338,7 @@ class ClientBase[ConfigT: ClientConfig]:
# the same join does not announce it twice.
if (
event.prev_membership != "join"
- and event.server_timestamp >= self._startup_ts
+ and event.timestamp >= self._startup_ts
and room.room_id not in self._self_join_dispatched
):
self._self_join_dispatched.add(room.room_id)
@@ -380,7 +365,7 @@ class ClientBase[ConfigT: ClientConfig]:
room.room_id,
)
- async def _handle_invite(self, room: MatrixRoom, event: InviteMemberEvent) -> None:
+ async def _handle_invite(self, room: RoomRef, event: InboundMembership) -> None:
try:
await self.on_invite(room, event)
except Exception:
@@ -390,22 +375,6 @@ class ClientBase[ConfigT: ClientConfig]:
_EVENT_DISPATCH: dict[str, tuple[type[SwitchEvent], str]] = {
"com.switch.command": (CommandEvent, "on_command"),
- "com.switch.mediation.tool_request": (
- MediationToolRequest,
- "on_mediation_tool_request",
- ),
- "com.switch.mediation.llm_request": (
- MediationLlmRequest,
- "on_mediation_llm_request",
- ),
- "com.switch.mediation.tool_result": (
- MediationToolResult,
- "on_mediation_tool_result",
- ),
- "com.switch.mediation.llm_response": (
- MediationLlmResponse,
- "on_mediation_llm_response",
- ),
"com.switch.report.tool_call": (ToolCallReport, "on_tool_call_report"),
"com.switch.report.llm_call": (LlmCallReport, "on_llm_call_report"),
"com.switch.task.delegate": (TaskDelegate, "on_task_delegate"),
@@ -417,61 +386,26 @@ class ClientBase[ConfigT: ClientConfig]:
AgentRuntimeStateEvent,
"on_agent_runtime_state",
),
- "com.switch.permission.request": (PermissionRequest, "on_permission_request"),
- "com.switch.permission.response": (
- PermissionResponse,
- "on_permission_response",
- ),
- "com.switch.resource.load_request": (
- ResourceLoadRequest,
- "on_resource_load_request",
- ),
- "com.switch.resource.load_response": (
- ResourceLoadResponse,
- "on_resource_load_response",
- ),
- "com.switch.resource.room_document_create_request": (
- RoomDocumentCreateRequest,
- "on_room_document_create_request",
- ),
- "com.switch.resource.room_document_create_response": (
- RoomDocumentCreateResponse,
- "on_room_document_create_response",
- ),
- "com.switch.resource.room_document_update_request": (
- RoomDocumentUpdateRequest,
- "on_room_document_update_request",
- ),
- "com.switch.resource.room_document_update_response": (
- RoomDocumentUpdateResponse,
- "on_room_document_update_response",
- ),
- "com.switch.resource.room_document_delete_request": (
- RoomDocumentDeleteRequest,
- "on_room_document_delete_request",
- ),
- "com.switch.resource.room_document_delete_response": (
- RoomDocumentDeleteResponse,
- "on_room_document_delete_response",
- ),
}
- async def _handle_custom_event(self, room: MatrixRoom, event: UnknownEvent) -> None:
+ async def _handle_custom_event(
+ self, room: RoomRef, event: InboundCustomEvent
+ ) -> None:
if self._should_ignore(room, event):
return
- entry = self._EVENT_DISPATCH.get(event.type)
+ entry = self._EVENT_DISPATCH.get(event.event_type)
if entry is None:
- if event.type.startswith("com.switch.observe."):
+ if event.event_type.startswith("com.switch.observe."):
logger.warning(
"Observe event %s not yet supported in %s",
- event.type,
+ event.event_type,
room.room_id,
)
else:
logger.error(
"Unhandled custom event type %s in %s",
- event.type,
+ event.event_type,
room.room_id,
)
return
@@ -479,10 +413,12 @@ class ClientBase[ConfigT: ClientConfig]:
event_class, method_name = entry
try:
typed_event = event_class(
- **event.source.get("content", {}),
+ **event.content,
)
except Exception:
- logger.exception("Failed to parse %s event in %s", event.type, room.room_id)
+ logger.exception(
+ "Failed to parse %s event in %s", event.event_type, room.room_id
+ )
return
# Command results reply into the command's thread. When the command was
@@ -491,174 +427,99 @@ class ClientBase[ConfigT: ClientConfig]:
# Otherwise the command itself roots the thread — use its own event id.
# The id is not part of the event content, so inject it here.
if isinstance(typed_event, CommandEvent):
- relates = event.source.get("content", {}).get("m.relates_to") or {}
- if relates.get("rel_type") == "m.thread":
- typed_event.thread_id = relates.get("event_id")
- else:
- typed_event.thread_id = event.event_id
+ typed_event.thread_id = event.thread_root_id or event.event_id
try:
await getattr(self, method_name)(room, typed_event)
except Exception:
- logger.exception("Error in handler for %s in %s", event.type, room.room_id)
+ logger.exception(
+ "Error in handler for %s in %s", event.event_type, room.room_id
+ )
- async def _handle_sync(self, response: SyncResponse) -> None:
- if not response.next_batch or response.next_batch == self.next_batch_token:
+ async def _handle_sync(self, next_batch: str, durable: bool) -> None:
+ if not next_batch or next_batch == self.next_batch_token:
return
- self.next_batch_token = response.next_batch
- if _carries_durable_events(response):
+ self.next_batch_token = next_batch
+ if durable:
await self._persist_state()
return
self._sync_state_dirty = True
if (time.monotonic() - self._last_sync_persist) >= SYNC_STATE_MAX_STALENESS:
await self._persist_state(force=True)
- async def _handle_sync_error(self, response: SyncError) -> None:
- logger.error("Sync error for %s: %s", self.matrix_user_id, response.message)
+ async def _handle_sync_error(self, message: str) -> None:
+ logger.error("Sync error for %s: %s", self.matrix_user_id, message)
if self.password:
logger.info("Attempting re-login for %s", self.matrix_user_id)
- resp = await self.client.login(self.password)
- if isinstance(resp, LoginError):
- logger.error(
- "Re-login failed for %s: %s", self.matrix_user_id, resp.message
- )
+ try:
+ await self._transport.relogin()
+ except TransportError as exc:
+ logger.error("%s", exc)
+ return
+ self._absorb_session_state()
# ── Filtering ──────────────────────────────────────────────────────────────
- def _should_ignore(self, room: MatrixRoom, event: object) -> bool:
- sender = getattr(event, "sender", None)
- if sender == self.matrix_user_id:
+ def _should_ignore(self, room: RoomRef, event: InboundEvent) -> bool:
+ if event.sender == self.matrix_user_id:
return True
- server_ts = getattr(event, "server_timestamp", None)
- if server_ts is not None:
+ if event.timestamp:
join_time = self.room_join_times.get(room.room_id, self._startup_ts)
- if server_ts < join_time:
+ if event.timestamp < join_time:
return True
return False
# ── Event hooks (subclasses override) ──────────────────────────────────────
- async def on_message(self, room: MatrixRoom, event: RoomMessageText) -> None:
+ async def on_message(self, room: RoomRef, event: InboundMessage) -> None:
pass
- async def on_media(self, room: MatrixRoom, event: RoomMessageMedia) -> None:
+ async def on_media(self, room: RoomRef, event: InboundMedia) -> None:
pass
- async def on_reaction(self, room: MatrixRoom, event: ReactionEvent) -> None:
+ async def on_reaction(self, room: RoomRef, event: InboundEvent) -> None:
pass
- async def on_self_join(self, room: MatrixRoom, event: RoomMemberEvent) -> None:
+ async def on_self_join(self, room: RoomRef, event: InboundMembership) -> None:
pass
- async def on_member_event(self, room: MatrixRoom, event: RoomMemberEvent) -> None:
+ async def on_member_event(self, room: RoomRef, event: InboundMembership) -> None:
pass
- async def on_invite(self, room: MatrixRoom, event: InviteMemberEvent) -> None:
+ async def on_invite(self, room: RoomRef, event: InboundMembership) -> None:
logger.info(
"Client %s auto-accepting invite to %s", self.matrix_user_id, room.room_id
)
await self.join_room(room.room_id)
- async def on_command(self, room: MatrixRoom, event: CommandEvent) -> None:
- pass
-
- async def on_mediation_tool_request(
- self, room: MatrixRoom, event: MediationToolRequest
- ) -> None:
- pass
-
- async def on_mediation_llm_request(
- self, room: MatrixRoom, event: MediationLlmRequest
- ) -> None:
- pass
-
- async def on_mediation_tool_result(
- self, room: MatrixRoom, event: MediationToolResult
- ) -> None:
- pass
-
- async def on_mediation_llm_response(
- self, room: MatrixRoom, event: MediationLlmResponse
- ) -> None:
+ async def on_command(self, room: RoomRef, event: CommandEvent) -> None:
pass
- async def on_tool_call_report(
- self, room: MatrixRoom, event: ToolCallReport
- ) -> None:
+ async def on_tool_call_report(self, room: RoomRef, event: ToolCallReport) -> None:
pass
- async def on_llm_call_report(self, room: MatrixRoom, event: LlmCallReport) -> None:
+ async def on_llm_call_report(self, room: RoomRef, event: LlmCallReport) -> None:
pass
- async def on_task_delegate(self, room: MatrixRoom, event: TaskDelegate) -> None:
+ async def on_task_delegate(self, room: RoomRef, event: TaskDelegate) -> None:
pass
- async def on_task_accept(self, room: MatrixRoom, event: TaskAccept) -> None:
+ async def on_task_accept(self, room: RoomRef, event: TaskAccept) -> None:
pass
- async def on_task_update(self, room: MatrixRoom, event: TaskUpdate) -> None:
+ async def on_task_update(self, room: RoomRef, event: TaskUpdate) -> None:
pass
- async def on_task_finalise(self, room: MatrixRoom, event: TaskFinalise) -> None:
+ async def on_task_finalise(self, room: RoomRef, event: TaskFinalise) -> None:
pass
- async def on_task_cancel(self, room: MatrixRoom, event: TaskCancel) -> None:
+ async def on_task_cancel(self, room: RoomRef, event: TaskCancel) -> None:
pass
async def on_agent_runtime_state(
- self, room: MatrixRoom, event: AgentRuntimeStateEvent
- ) -> None:
- pass
-
- async def on_permission_request(
- self, room: MatrixRoom, event: PermissionRequest
- ) -> None:
- pass
-
- async def on_permission_response(
- self, room: MatrixRoom, event: PermissionResponse
- ) -> None:
- pass
-
- async def on_resource_load_request(
- self, room: MatrixRoom, event: ResourceLoadRequest
- ) -> None:
- pass
-
- async def on_room_document_create_request(
- self, room: MatrixRoom, event: RoomDocumentCreateRequest
- ) -> None:
- pass
-
- async def on_room_document_create_response(
- self, room: MatrixRoom, event: RoomDocumentCreateResponse
- ) -> None:
- pass
-
- async def on_room_document_update_request(
- self, room: MatrixRoom, event: RoomDocumentUpdateRequest
- ) -> None:
- pass
-
- async def on_room_document_update_response(
- self, room: MatrixRoom, event: RoomDocumentUpdateResponse
- ) -> None:
- pass
-
- async def on_room_document_delete_request(
- self, room: MatrixRoom, event: RoomDocumentDeleteRequest
- ) -> None:
- pass
-
- async def on_room_document_delete_response(
- self, room: MatrixRoom, event: RoomDocumentDeleteResponse
- ) -> None:
- pass
-
- async def on_resource_load_response(
- self, room: MatrixRoom, event: ResourceLoadResponse
+ self, room: RoomRef, event: AgentRuntimeStateEvent
) -> None:
pass
@@ -674,61 +535,43 @@ class ClientBase[ConfigT: ClientConfig]:
thread_root_id: str | None = None,
extra_content: dict[str, object] | None = None,
) -> str | None:
- content: dict[str, object] = {
- "msgtype": "m.text",
- "body": body,
- "sender_name": self.display_name,
- }
- # Caller-supplied content fields (e.g. a `com.switch.*` marker) are
- # merged in. They ride on the plain m.room.message — the body still
- # renders normally; the extra keys are metadata other clients can read.
- if extra_content:
- content.update(extra_content)
-
- if format == "markdown":
- html = markdown.markdown(body)
- if mentions:
- for user_id in mentions:
- local = user_id.split(":")[0].lstrip("@")
- pill = f'<a href="https://matrix.to/#/{user_id}">{local}</a>'
- html = html.replace(f"@{local}", pill)
- content["format"] = "org.matrix.custom.html"
- content["formatted_body"] = html
-
- # Threaded reply: relate this message to the thread root via a pure
- # m.thread relation (no m.in_reply_to fallback). The root id must be an
- # actual thread root — callers normalise mid-thread ids upstream.
- if thread_root_id is not None:
- content["m.relates_to"] = {
- "rel_type": "m.thread",
- "event_id": thread_root_id,
- }
-
- resp = await self.client.room_send(room_id, "m.room.message", content)
-
- if isinstance(resp, RoomSendError):
- logger.error("Failed to send message to %s: %s", room_id, resp.message)
+ try:
+ result = await self._transport.send_message(
+ room_id,
+ body,
+ sender_name=self.display_name,
+ format=format,
+ mentions=mentions,
+ thread_root_id=thread_root_id,
+ extra_content=extra_content,
+ )
+ except TransportError as exc:
+ logger.error("Failed to send message to %s: %s", room_id, exc)
return None
+ await self._record(room_id, result)
+ return result.event_id
- return resp.event_id # type: ignore[no-any-return]
+ async def send_event(
+ self, room_id: str, event_type: str, content: dict[str, object]
+ ) -> str:
+ """Send a custom event, e.g. one of the `com.switch.*` types.
+
+ Raises rather than returning None: unlike a chat message, these events
+ carry protocol state, and a caller that proceeds as though one was
+ delivered when it was not corrupts whatever it was coordinating.
+ """
+ result = await self._transport.send_event(room_id, event_type, content)
+ await self._record(room_id, result)
+ return result.event_id
async def upload_media(self, data: bytes, content_type: str, filename: str) -> str:
- """Upload bytes to the Matrix media repository and return the mxc URI.
+ """Upload bytes to the media store and return the URI referencing them.
Raises on failure — a media upload that silently returns None would
produce a broken event referencing nothing.
"""
- resp, _ = await self.client.upload(
- data_provider=io.BytesIO(data),
- content_type=content_type,
- filename=filename,
- filesize=len(data),
- )
- if isinstance(resp, UploadError):
- raise RuntimeError(
- f"Failed to upload media '{filename}' to Matrix: {resp.message}"
- )
- return resp.content_uri # type: ignore[no-any-return]
+ result = await self._transport.upload_media(data, content_type, filename)
+ return result.uri
async def send_media(
self,
@@ -757,53 +600,43 @@ class ClientBase[ConfigT: ClientConfig]:
receivers coalesce back into one logical message. Absent the field, an
event is simply a group of one.
"""
- content: dict[str, object] = {
- "msgtype": msgtype,
- "body": caption if caption else filename,
- "url": mxc,
- "info": {"mimetype": mimetype, "size": size},
- "sender_name": self.display_name,
- }
- if caption:
- content["filename"] = filename
- if group is not None:
- content[ATTACHMENT_GROUP_KEY] = group
- if thread_root_id is not None:
- content["m.relates_to"] = {
- "rel_type": "m.thread",
- "event_id": thread_root_id,
- }
-
- resp = await self.client.room_send(room_id, "m.room.message", content)
-
- if isinstance(resp, RoomSendError):
- logger.error("Failed to send media to %s: %s", room_id, resp.message)
+ try:
+ result = await self._transport.send_media(
+ room_id,
+ mxc,
+ filename,
+ mimetype,
+ size,
+ sender_name=self.display_name,
+ msgtype=msgtype,
+ caption=caption,
+ thread_root_id=thread_root_id,
+ group=group,
+ )
+ except TransportError as exc:
+ logger.error("Failed to send media to %s: %s", room_id, exc)
return None
-
- return resp.event_id # type: ignore[no-any-return]
+ await self._record(room_id, result)
+ return result.event_id
+
+ async def _record(self, room_id: str, result: SendResult) -> None:
+ await self.message_recorder.record(
+ transport_room_id=room_id,
+ result=result,
+ sender_matrix_id=self.matrix_user_id,
+ sender_client_id=self.client_id,
+ sender_name=self.display_name,
+ )
async def set_typing(self, room_id: str, is_typing: bool) -> None:
- logger.debug(
- "Setting typing %s in room %s for matrix user %s",
- is_typing,
- room_id,
- self.matrix_user_id,
- )
- resp = await self.client.room_typing(room_id, is_typing)
- if isinstance(resp, RoomTypingError):
- logger.error("Failed to set typing in %s: %s", room_id, resp.message)
+ await self._transport.set_typing(room_id, is_typing)
# ── Room operations ────────────────────────────────────────────────────────
async def join_room(self, room_id: str) -> None:
- resp = await self.client.join(room_id)
- if hasattr(resp, "room_id"):
+ if await self._transport.join_room(room_id):
self._mark_joined(room_id, int(time.time() * 1000))
logger.info("Client %s joined %s", self.matrix_user_id, room_id)
- else:
- logger.error(
- "Client %s failed to join %s: %s", self.matrix_user_id, room_id, resp
- )
# ── State persistence ──────────────────────────────────────────────────────
@@ -818,9 +651,8 @@ class ClientBase[ConfigT: ClientConfig]:
await self.client_store.update_state(
session,
self.client_id,
- access_token=self.access_token,
- device_id=self.device_id,
next_batch_token=self.next_batch_token,
+ **self.session_state,
)
await session.commit()
self._last_sync_persist = now
diff --git a/core/switch_core/clients/client_factory.py b/core/switch_core/clients/client_factory.py
index eee10bc33..37c2b6fef 100644
--- a/core/switch_core/clients/client_factory.py
+++ b/core/switch_core/clients/client_factory.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import logging
+from typing import Any
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -8,10 +9,40 @@ from switch_core.clients.client_base import ClientBase, ClientConfig
from switch_core.config import SwitchConfig
from switch_core.db.models import Client
from switch_core.db.stores.client_store import ClientStore
+from switch_core.db.stores.media_store import MediaStore
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.db.stores.room_store import RoomStore
+from switch_core.messages import MessageRecorder
+from switch_core.messages.notify import MessageListener
+from switch_core.messages.recording import MessageRecording, NoRecording
+from switch_core.transport import MessageTransport
+from switch_core.transport.ephemeral import EphemeralBus
+from switch_core.transport.invites import InviteBus
+from switch_core.transport.matrix import MatrixTransport
+from switch_core.transport.postgres import PostgresTransport
logger = logging.getLogger(__name__)
+def matrix_transport_for(client: ClientBase[Any]) -> MessageTransport:
+ """Build the transport a client runs on.
+
+ Choosing the implementation is the factory's job, so a client never names
+ one.
+
+ The config type is `Any` because nothing here reads the config: a factory
+ that works for every client would otherwise have to be re-typed for each
+ subclass, since `ClientBase` is invariant in it.
+ """
+ return MatrixTransport(
+ server_url=client.server_url,
+ user_id=client.matrix_user_id,
+ password=client.password,
+ device_id=client.session_state.get("device_id"),
+ access_token=client.session_state.get("access_token"),
+ )
+
+
class ClientFactory:
def __init__(
self,
@@ -19,10 +50,24 @@ class ClientFactory:
client_store: ClientStore,
session_factory: async_sessionmaker[AsyncSession],
config: SwitchConfig,
+ message_recorder: MessageRecorder,
+ room_store: RoomStore,
+ message_store: MessageStore,
+ media_store: MediaStore,
+ listener: MessageListener,
+ invites: InviteBus,
+ ephemeral: EphemeralBus,
) -> None:
self._client_store = client_store
self._session_factory = session_factory
self._config = config
+ self._message_recorder = message_recorder
+ self._room_store = room_store
+ self._message_store = message_store
+ self._media_store = media_store
+ self._listener = listener
+ self._invites = invites
+ self._ephemeral = ephemeral
self._registry: dict[
str, tuple[type[ClientBase[ClientConfig]], dict[str, object]]
] = {}
@@ -50,8 +95,50 @@ class ClientFactory:
session_factory=self._session_factory,
client_store=self._client_store,
config=config,
- device_id=record.device_id,
- access_token=record.access_token,
+ transport_factory=self.transport_for,
+ message_recorder=self.recorder(),
+ session_state={
+ "access_token": record.access_token,
+ "device_id": record.device_id,
+ },
next_batch_token=record.next_batch_token,
**extra_kwargs,
)
+
+ def transport_for(self, client: ClientBase[Any]) -> MessageTransport:
+ """The transport every client in the process runs on.
+
+ Public because not every client is built by `create`: a collaboration
+ bridge's client is constructed by its own lifecycle service, which
+ carries per-bridge state the registry cannot hold. It still has to make
+ the same choice, and a caller that named an implementation directly
+ would put its clients on a different bus from everyone else's — agents
+ talking in rows while bridges talk to a homeserver, each side healthy
+ and neither reaching the other.
+ """
+ if self._config.message_transport == "matrix":
+ return matrix_transport_for(client)
+ return PostgresTransport(
+ user_id=client.matrix_user_id,
+ client_id=client.client_id,
+ display_name=client.display_name,
+ session_factory=self._session_factory,
+ room_store=self._room_store,
+ message_store=self._message_store,
+ media_store=self._media_store,
+ listener=self._listener,
+ invites=self._invites,
+ ephemeral=self._ephemeral,
+ )
+
+ def recorder(self) -> MessageRecording:
+ """The recorder that goes with the transport.
+
+ Paired here rather than configured separately: a transport that stores
+ what it carries needs no recorder, and one that does not needs one.
+ Splitting the decision would let a deployment pick both and write every
+ message twice.
+ """
+ if self._config.message_transport == "matrix":
+ return self._message_recorder
+ return NoRecording()
diff --git a/core/switch_core/clients/client_lifecycle_service.py b/core/switch_core/clients/client_lifecycle_service.py
index cd7f674b3..a76b8ba74 100644
--- a/core/switch_core/clients/client_lifecycle_service.py
+++ b/core/switch_core/clients/client_lifecycle_service.py
@@ -12,7 +12,7 @@ from switch_core.clients.client_factory import ClientFactory
from switch_core.config import SwitchConfig
from switch_core.db.models import Client
from switch_core.db.stores.client_store import ClientStore
-from switch_core.matrix_admin import MatrixAdmin
+from switch_core.provisioning import Provisioning
logger = logging.getLogger(__name__)
@@ -21,7 +21,7 @@ class ClientLifecycleService:
def __init__(
self,
*,
- matrix_admin: MatrixAdmin,
+ matrix_admin: Provisioning,
client_store: ClientStore,
client_factory: ClientFactory,
session_factory: async_sessionmaker[AsyncSession],
diff --git a/core/switch_core/clients/resource_manager_client.py b/core/switch_core/clients/resource_manager_client.py
deleted file mode 100644
index 3da9067b8..000000000
--- a/core/switch_core/clients/resource_manager_client.py
+++ /dev/null
@@ -1,295 +0,0 @@
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from nio import MatrixRoom
-
-from switch_core.bridges.agent.request_tracker import RequestTracker
-from switch_core.bridges.resource.events import (
- ResourceLoadRequest,
- ResourceLoadResponse,
- RoomDocumentCreateRequest,
- RoomDocumentCreateResponse,
- RoomDocumentDeleteRequest,
- RoomDocumentDeleteResponse,
- RoomDocumentUpdateRequest,
- RoomDocumentUpdateResponse,
-)
-from switch_core.bridges.resource.service import ResourceService
-from switch_core.clients.client_base import ClientBase, ClientConfig
-from switch_core.db.stores.agent_store import AgentStore
-from switch_core.db.stores.room_store import RoomStore
-from switch_core.events import (
- MediationLlmRequest,
- MediationResult,
- MediationToolRequest,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class ResourceManagerClient(ClientBase[ClientConfig]):
- def __init__(
- self,
- *,
- agent_store: AgentStore,
- room_store: RoomStore,
- resource_service: ResourceService,
- request_tracker: RequestTracker,
- **kwargs: Any,
- ) -> None:
- super().__init__(**kwargs)
- self._agent_store = agent_store
- self._room_store = room_store
- self._resource_service = resource_service
- self._request_tracker = request_tracker
-
- async def on_mediation_tool_request(
- self, room: MatrixRoom, event: MediationToolRequest
- ) -> None:
- verdict, reason = await self._check_tool_access(event.agent_id, event.tool_id)
- result = MediationResult(verdict=verdict, reason=reason)
- self._request_tracker.resolve(event.request_id, result)
-
- async def on_mediation_llm_request(
- self, room: MatrixRoom, event: MediationLlmRequest
- ) -> None:
- verdict, reason = await self._check_model_access(event.agent_id, event.model_id)
- result = MediationResult(verdict=verdict, reason=reason)
- self._request_tracker.resolve(event.request_id, result)
-
- async def on_resource_load_request(
- self, room: MatrixRoom, event: ResourceLoadRequest
- ) -> None:
- """Fetch the requested documents and reply with a load_response.
-
- The agent's membership in the room is implicit (the request was sent
- in this room) and the service validates that each requested doc is
- actually attached here — preventing cross-room access.
- """
- response: ResourceLoadResponse
- if self.nio_client is None:
- logger.error(
- "Resource manager not connected; cannot send load response %s",
- event.request_id,
- )
- return
- try:
- async with self.session_factory() as session:
- switch_room = await self._room_store.get_by_matrix_room_id(
- session, room.room_id
- )
- if switch_room is None:
- raise ValueError(
- f"No Switch room maps to matrix room {room.room_id}"
- )
- entries = await self._resource_service.load_documents(
- session, switch_room.id, event.document_ids
- )
- response = ResourceLoadResponse(
- request_id=event.request_id,
- agent_id=event.agent_id,
- status="ok",
- documents=entries,
- )
- except Exception as exc:
- logger.exception(
- "Failed to load documents for request %s", event.request_id
- )
- response = ResourceLoadResponse(
- request_id=event.request_id,
- agent_id=event.agent_id,
- status="error",
- error=str(exc),
- )
-
- await self.nio_client.room_send(
- room.room_id,
- "com.switch.resource.load_response",
- response.model_dump(mode="json"),
- )
-
- async def on_room_document_create_request(
- self, room: MatrixRoom, event: RoomDocumentCreateRequest
- ) -> None:
- if self.nio_client is None:
- logger.error(
- "Resource manager not connected; cannot reply to %s", event.request_id
- )
- return
- response: RoomDocumentCreateResponse
- try:
- async with self.session_factory() as session:
- switch_room = await self._room_store.get_by_matrix_room_id(
- session, room.room_id
- )
- if switch_room is None:
- raise ValueError(
- f"No Switch room maps to matrix room {room.room_id}"
- )
- agent = await self._agent_store.get(session, event.agent_id)
- doc = await self._resource_service.create_room_document(
- session,
- room_id=switch_room.id,
- agent_id=event.agent_id,
- owner_id=agent.owner_id if agent is not None else None,
- name=event.name,
- description=event.description,
- instructions=event.instructions,
- content=event.content,
- )
- await session.commit()
- response = RoomDocumentCreateResponse(
- request_id=event.request_id,
- agent_id=event.agent_id,
- status="ok",
- document_id=doc.id,
- document_name=doc.name,
- )
- except Exception as exc:
- logger.exception(
- "Failed to create room document for request %s", event.request_id
- )
- response = RoomDocumentCreateResponse(
- request_id=event.request_id,
- agent_id=event.agent_id,
- status="error",
- error=str(exc),
- )
-
- await self.nio_client.room_send(
- room.room_id,
- "com.switch.resource.room_document_create_response",
- response.model_dump(mode="json"),
- )
-
- async def on_room_document_update_request(
- self, room: MatrixRoom, event: RoomDocumentUpdateRequest
- ) -> None:
- if self.nio_client is None:
- logger.error(
- "Resource manager not connected; cannot reply to %s", event.request_id
- )
- return
- response: RoomDocumentUpdateResponse
- try:
- async with self.session_factory() as session:
- switch_room = await self._room_store.get_by_matrix_room_id(
- session, room.room_id
- )
- if switch_room is None:
- raise ValueError(
- f"No Switch room maps to matrix room {room.room_id}"
- )
- doc = await self._resource_service.update_room_document(
- session,
- room_id=switch_room.id,
- agent_id=event.agent_id,
- document_id=event.document_id,
- name=event.name,
- description=event.description,
- instructions=event.instructions,
- content=event.content,
- )
- await session.commit()
- response = RoomDocumentUpdateResponse(
- request_id=event.request_id,
- agent_id=event.agent_id,
- status="ok",
- document_name=doc.name,
- )
- except Exception as exc:
- logger.exception(
- "Failed to update room document for request %s", event.request_id
- )
- response = RoomDocumentUpdateResponse(
- request_id=event.request_id,
- agent_id=event.agent_id,
- status="error",
- error=str(exc),
- )
-
- await self.nio_client.room_send(
- room.room_id,
- "com.switch.resource.room_document_update_response",
- response.model_dump(mode="json"),
- )
-
- async def on_room_document_delete_request(
- self, room: MatrixRoom, event: RoomDocumentDeleteRequest
- ) -> None:
- if self.nio_client is None:
- logger.error(
- "Resource manager not connected; cannot reply to %s", event.request_id
- )
- return
- response: RoomDocumentDeleteResponse
- deleted_name: str | None = None
- try:
- async with self.session_factory() as session:
- switch_room = await self._room_store.get_by_matrix_room_id(
- session, room.room_id
- )
- if switch_room is None:
- raise ValueError(
- f"No Switch room maps to matrix room {room.room_id}"
- )
- doc = await self._resource_service.get_room_scoped_document(
- session, switch_room.id, event.document_id
- )
- deleted_name = doc.name
- await self._resource_service.delete_room_document(
- session,
- room_id=switch_room.id,
- agent_id=event.agent_id,
- document_id=event.document_id,
- )
- await session.commit()
- response = RoomDocumentDeleteResponse(
- request_id=event.request_id,
- agent_id=event.agent_id,
- status="ok",
- document_name=deleted_name,
- )
- except Exception as exc:
- logger.exception(
- "Failed to delete room document for request %s", event.request_id
- )
- response = RoomDocumentDeleteResponse(
- request_id=event.request_id,
- agent_id=event.agent_id,
- status="error",
- error=str(exc),
- )
-
- await self.nio_client.room_send(
- room.room_id,
- "com.switch.resource.room_document_delete_response",
- response.model_dump(mode="json"),
- )
-
- async def _check_tool_access(
- self, agent_id: str, tool_name: str
- ) -> tuple[str, str | None]:
- async with self.session_factory() as session:
- tools = await self._agent_store.get_tools(session, agent_id)
-
- if any(t.name == tool_name for t in tools):
- return "proceed", None
-
- return "blocked", f"Agent {agent_id} does not have tool '{tool_name}' attached"
-
- async def _check_model_access(
- self, agent_id: str, model_name: str
- ) -> tuple[str, str | None]:
- async with self.session_factory() as session:
- models = await self._agent_store.get_models(session, agent_id)
-
- if any(m.name == model_name for m in models):
- return "proceed", None
-
- return (
- "blocked",
- f"Agent {agent_id} does not have model '{model_name}' attached",
- )
diff --git a/core/switch_core/config.py b/core/switch_core/config.py
index 1709ffe53..9fd8fa840 100644
--- a/core/switch_core/config.py
+++ b/core/switch_core/config.py
@@ -1,4 +1,5 @@
import re
+from typing import Literal
from urllib.parse import urlsplit
from pydantic import model_validator
@@ -17,6 +18,13 @@ class SwitchConfig(BaseSettings):
db_password: str
db_name: str
+ # Which transport carries messages: "matrix" for the homeserver,
+ # "postgres" for the message table. The choice pairs a transport with a
+ # provisioning implementation and a recorder, so it is one setting rather
+ # than three. Defaults to matrix, so an existing deployment is unchanged
+ # until it is asked to move.
+ message_transport: Literal["matrix", "postgres"] = "matrix"
+
matrix_server: str
matrix_server_name: str
matrix_admin_user: str
diff --git a/core/switch_core/db/engine.py b/core/switch_core/db/engine.py
index aeb425a9a..053c4a9bc 100644
--- a/core/switch_core/db/engine.py
+++ b/core/switch_core/db/engine.py
@@ -4,6 +4,7 @@ from sqlalchemy.ext.asyncio import (
async_sessionmaker,
create_async_engine,
)
+from sqlalchemy.pool import NullPool
from switch_core.config import SwitchConfig
@@ -46,5 +47,21 @@ def create_engine_from_config(
return create_async_engine(config.database_url, **defaults)
+def create_unpooled_engine(config: SwitchConfig) -> AsyncEngine:
+ """An engine for a connection that is held rather than borrowed.
+
+ A `LISTEN` lives on one connection for the process's life. Every pool
+ setting is either meaningless for that or actively harmful — recycling
+ would drop the subscription, and the silence afterwards is indistinguishable
+ from a quiet room — so it takes the connection arguments and none of the
+ pooling.
+ """
+ return create_async_engine(
+ config.database_url,
+ poolclass=NullPool,
+ connect_args=app_connect_args(config),
+ )
+
+
def create_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
return async_sessionmaker(bind=engine, expire_on_commit=False)
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index 6798bfe95..19b157c2e 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -1,15 +1,20 @@
import uuid
from sqlalchemy import (
+ DDL,
+ BigInteger,
Boolean,
CheckConstraint,
Column,
DateTime,
ForeignKey,
Index,
+ Integer,
+ LargeBinary,
Table,
Text,
UniqueConstraint,
+ event,
func,
text,
)
@@ -17,6 +22,11 @@ from sqlalchemy.dialects.postgresql import JSONB
from sqlalchemy.orm import Mapped, mapped_column
from switch_core.db.base import Base
+from switch_core.db.notify_ddl import (
+ CREATE_NOTIFY_FUNCTION,
+ CREATE_NOTIFY_TRIGGER,
+ DROP_NOTIFY_TRIGGER,
+)
def _uuid() -> str:
@@ -95,6 +105,7 @@ class ClientRoom(Base):
class Agent(Base):
__tablename__ = "agents"
+ __table_args__ = (Index("ix_agents_parent_agent_id", "parent_agent_id"),)
id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)
name: Mapped[str] = mapped_column(Text, unique=True, nullable=False)
@@ -294,6 +305,14 @@ class Room(Base):
archived_at: Mapped[str | None] = mapped_column(
DateTime(timezone=True), nullable=True
)
+ # Set when this room's history has been walked to its start and written
+ # into the message log. Null means never completed — including a walk that
+ # stopped at the page limit, which leaves the room partly reconstructed.
+ # The walk always starts from the newest message, so without this a re-run
+ # reads every page of every room again to discover it has nothing to do.
+ history_backfilled_at: Mapped[str | None] = mapped_column(
+ DateTime(timezone=True), nullable=True
+ )
# ── Room Groups ─────────────────────────────────────────────────────────────────
@@ -612,6 +631,7 @@ class ExternalUserClaim(Base):
"""
__tablename__ = "external_user_claims"
+ __table_args__ = (Index("ix_external_user_claims_user_id", "user_id"),)
external_user_id: Mapped[str] = mapped_column(
Text,
@@ -657,6 +677,8 @@ class AgentSession(Base):
text("coalesce(room_id, '')"),
unique=True,
),
+ Index("ix_agent_sessions_agent_room", "agent_id", "room_id"),
+ Index("ix_agent_sessions_transport_session_id", "transport_session_id"),
)
id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)
@@ -854,3 +876,183 @@ class FeatureFlag(Base):
onupdate=func.now(),
nullable=False,
)
+
+
+# ── Messages ─────────────────────────────────────────────────────────────────
+
+
+class Message(Base):
+ """A message as it was sent into a room.
+
+ Written alongside the send to the message bus, which remains the source of
+ truth for history until the read path moves here. Rows are therefore a
+ parallel record, not yet an authoritative one: a write that fails after a
+ successful send leaves a gap, by design, so that a database problem cannot
+ make messaging less reliable.
+
+ Every participant in a room is a Switch-owned client, so recording each
+ send captures the whole room exactly once — including messages a human
+ originates on a bridged platform, which enter through that user's puppet.
+
+ `content` is the full event body as sent. The columns beside it are
+ denormalised out of it for querying; for a custom `com.switch.*` event
+ they are mostly null and `content` carries everything.
+ """
+
+ __tablename__ = "messages"
+ __table_args__ = (
+ UniqueConstraint("room_id", "seq", name="uq_messages_room_seq"),
+ # `seq` orders the room and is what the read path pages on; `sent_at`
+ # is what a caller asking for a time window filters by, so it needs an
+ # index of its own rather than a scan back along seq.
+ Index("ix_messages_room_sent_at", "room_id", "sent_at"),
+ Index(
+ "ix_messages_thread_root",
+ "room_id",
+ "thread_root_event_id",
+ postgresql_where=text("thread_root_event_id IS NOT NULL"),
+ ),
+ )
+
+ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)
+ # Position within the room, from 1, and the cursor the read path pages on.
+ # Assigned by MessageStore.create under a per-room lock rather than by a
+ # sequence: a sequence hands out numbers when a statement runs, not when it
+ # commits, so a row can commit after one with a higher number and a reader
+ # paging on `seq > n` would step straight over it. See the store for the
+ # argument in full.
+ seq: Mapped[int] = mapped_column(BigInteger, nullable=False)
+ room_id: Mapped[str] = mapped_column(
+ Text, ForeignKey("rooms.id", ondelete="CASCADE"), nullable=False
+ )
+ transport_event_id: Mapped[str] = mapped_column(Text, unique=True, nullable=False)
+ sender_matrix_id: Mapped[str] = mapped_column(Text, nullable=False)
+ sender_client_id: Mapped[str | None] = mapped_column(
+ Text, ForeignKey("clients.id", ondelete="SET NULL"), nullable=True
+ )
+ sender_name: Mapped[str | None] = mapped_column(Text, nullable=True)
+ event_type: Mapped[str] = mapped_column(Text, nullable=False)
+ msgtype: Mapped[str | None] = mapped_column(Text, nullable=True)
+ body: Mapped[str | None] = mapped_column(Text, nullable=True)
+ formatted_body: Mapped[str | None] = mapped_column(Text, nullable=True)
+ thread_root_event_id: Mapped[str | None] = mapped_column(Text, nullable=True)
+ content: Mapped[dict] = mapped_column(JSONB, nullable=False)
+ sent_at: Mapped[str] = mapped_column(
+ DateTime(timezone=True), server_default=func.now(), nullable=False
+ )
+
+
+class MessageAttachment(Base):
+ """A file carried by a message.
+
+ One row per file, so a multi-file send is several rows against one message
+ in the order they were sent.
+ """
+
+ __tablename__ = "message_attachments"
+ __table_args__ = (Index("ix_message_attachments_message", "message_id"),)
+
+ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)
+ message_id: Mapped[str] = mapped_column(
+ Text, ForeignKey("messages.id", ondelete="CASCADE"), nullable=False
+ )
+ position: Mapped[int] = mapped_column(Integer, nullable=False)
+ uri: Mapped[str] = mapped_column(Text, nullable=False)
+ filename: Mapped[str | None] = mapped_column(Text, nullable=True)
+ mimetype: Mapped[str | None] = mapped_column(Text, nullable=True)
+ size: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+ created_at: Mapped[str] = mapped_column(
+ DateTime(timezone=True), server_default=func.now(), nullable=False
+ )
+
+
+class DeliveryCursor(Base):
+ """How far one agent has been delivered in one room.
+
+ The cursor it replaces lived in memory in the event buffer, so a restart
+ resumed from wherever that buffer happened to be rather than from what the
+ agent had actually been given. Persisting it makes "what has this agent
+ seen" outlive the process, which is what lets delivery be driven from the
+ table instead of from a live connection.
+
+ `last_seq` is a position in the room, not a count: `seq` is a per-room
+ total order, so "everything up to n" is unambiguous and re-reading from it
+ is idempotent. It is only ever advanced, never rewound — a cursor that
+ could go backwards would redeliver, and a redelivered message is
+ indistinguishable to a reader from a new one.
+ """
+
+ __tablename__ = "delivery_cursors"
+ __table_args__ = (
+ UniqueConstraint("agent_id", "room_id", name="uq_delivery_cursors_agent_room"),
+ )
+
+ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)
+ agent_id: Mapped[str] = mapped_column(
+ Text, ForeignKey("agents.id", ondelete="CASCADE"), nullable=False
+ )
+ room_id: Mapped[str] = mapped_column(
+ Text, ForeignKey("rooms.id", ondelete="CASCADE"), nullable=False
+ )
+ last_seq: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+ updated_at: Mapped[str] = mapped_column(
+ DateTime(timezone=True),
+ server_default=func.now(),
+ onupdate=func.now(),
+ nullable=False,
+ )
+
+
+class MediaBlob(Base):
+ """The bytes behind an attachment.
+
+ Media used to live in the homeserver's own store, reached by an opaque
+ handle that travelled on the message. The handle is still opaque and still
+ travels on the message; only what is behind it changed. Callers must not
+ parse `uri` — it is a key, and the store behind it is free to become object
+ storage without the protocol noticing.
+
+ `bytea` rather than a large object: attachments are capped
+ (`agent_media_max_bytes`, 20MB by default) and are written and read whole,
+ which is exactly what TOAST handles well and what large objects add
+ lifecycle problems to. A blob that would not fit is rejected at the edge,
+ loudly, as it already is.
+
+ Rows are not reference-counted against the attachments pointing at them.
+ Deleting a room deletes its messages; the bytes it referenced are then
+ unreferenced and a later sweep can find them by that. Cascading from the
+ attachment instead would delete the bytes of a file that two messages
+ quote.
+ """
+
+ __tablename__ = "media_blobs"
+
+ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)
+ uri: Mapped[str] = mapped_column(Text, unique=True, nullable=False)
+ content_type: Mapped[str | None] = mapped_column(Text, nullable=True)
+ filename: Mapped[str | None] = mapped_column(Text, nullable=True)
+ size: Mapped[int] = mapped_column(BigInteger, nullable=False)
+ data: Mapped[bytes] = mapped_column(LargeBinary, nullable=False)
+ created_at: Mapped[str] = mapped_column(
+ DateTime(timezone=True), server_default=func.now(), nullable=False
+ )
+
+
+# `create_all` builds the schema for tests; the trigger has to come with it or
+# the delivery tests would exercise a table that announces nothing. Real
+# databases get the same DDL from a migration.
+event.listen(
+ Message.__table__,
+ "after_create",
+ DDL(CREATE_NOTIFY_FUNCTION).execute_if(dialect="postgresql"),
+)
+event.listen(
+ Message.__table__,
+ "after_create",
+ DDL(CREATE_NOTIFY_TRIGGER).execute_if(dialect="postgresql"),
+)
+event.listen(
+ Message.__table__,
+ "before_drop",
+ DDL(DROP_NOTIFY_TRIGGER).execute_if(dialect="postgresql"),
+)
diff --git a/core/switch_core/db/notify_ddl.py b/core/switch_core/db/notify_ddl.py
new file mode 100644
index 000000000..268efba32
--- /dev/null
+++ b/core/switch_core/db/notify_ddl.py
@@ -0,0 +1,72 @@
+"""The database side of message delivery: a trigger that announces new rows.
+
+Delivery used to be the message bus pushing an event at a long-lived sync
+connection. It becomes the table announcing its own inserts, and a listener
+reading the rows back.
+
+**The notification is a hint, never the payload.** It carries a room, a
+position and a row id, and a consumer reads the row itself. That is what makes
+a lost notification cost latency instead of data: a consumer that keeps a
+position can always ask what it has not seen, and one that never hears
+anything is behind rather than wrong. Putting the message in the payload would
+make the queue authoritative, and Postgres's notification queue is neither
+durable nor replayable.
+
+**It is a trigger rather than a call in the writer** so that it cannot be
+forgotten. Anything that inserts a row — the recorder today, a backfill
+tomorrow, a human with psql — announces it, and the announcement commits with
+the row or not at all. `NOTIFY` is only delivered on commit, so a listener
+never learns about a row it could not then read.
+
+One channel carries every room, and listeners filter. A channel per room would
+save wakeups, but each one needs a `LISTEN` issued before the first row it
+should catch, which is a race the consumer has to close by reading the table
+anyway — so the correctness machinery is identical and the subscription churn
+is pure cost. See `switch_core/messages/notify.py` for the in-process fan-out
+that replaces it.
+
+The migration that installs this on a real database carries its own verbatim
+copy: a migration is frozen at the moment it was written and must not change
+meaning because this file did. The copy here is what `create_all` builds, so
+tests exercise the same trigger the server runs.
+"""
+
+from __future__ import annotations
+
+# Deliberately not per-room. See the module docstring.
+MESSAGE_CHANNEL = "switch_message"
+
+NOTIFY_FUNCTION_NAME = "switch_notify_message"
+NOTIFY_TRIGGER_NAME = "messages_notify"
+
+CREATE_NOTIFY_FUNCTION = f"""
+CREATE OR REPLACE FUNCTION {NOTIFY_FUNCTION_NAME}() RETURNS trigger AS $$
+BEGIN
+ -- Reconstructed history is numbered below zero and is not news. A backfill
+ -- inserts thousands of rows nobody is waiting for, and announcing them
+ -- would wake every subscriber in the room to read nothing, because their
+ -- cursors are above these positions by construction.
+ IF NEW.seq <= 0 THEN
+ RETURN NULL;
+ END IF;
+ PERFORM pg_notify(
+ '{MESSAGE_CHANNEL}',
+ json_build_object(
+ 'room_id', NEW.room_id,
+ 'seq', NEW.seq,
+ 'id', NEW.id
+ )::text
+ );
+ RETURN NULL;
+END;
+$$ LANGUAGE plpgsql
+"""
+
+CREATE_NOTIFY_TRIGGER = f"""
+CREATE TRIGGER {NOTIFY_TRIGGER_NAME}
+ AFTER INSERT ON messages
+ FOR EACH ROW EXECUTE FUNCTION {NOTIFY_FUNCTION_NAME}()
+"""
+
+DROP_NOTIFY_TRIGGER = f"DROP TRIGGER IF EXISTS {NOTIFY_TRIGGER_NAME} ON messages"
+DROP_NOTIFY_FUNCTION = f"DROP FUNCTION IF EXISTS {NOTIFY_FUNCTION_NAME}()"
diff --git a/core/switch_core/db/stores/__init__.py b/core/switch_core/db/stores/__init__.py
index 7d23337ff..ede68f314 100644
--- a/core/switch_core/db/stores/__init__.py
+++ b/core/switch_core/db/stores/__init__.py
@@ -5,6 +5,7 @@ from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore
from switch_core.db.stores.document_store import DocumentStore
from switch_core.db.stores.external_user_store import ExternalUserStore
+from switch_core.db.stores.message_store import MessageStore
from switch_core.db.stores.reference_store import ReferenceStore
from switch_core.db.stores.reference_type_store import ReferenceTypeStore
from switch_core.db.stores.room_group_store import RoomGroupStore
@@ -22,6 +23,7 @@ __all__ = [
"CollaborationBridgeStore",
"DocumentStore",
"ExternalUserStore",
+ "MessageStore",
"ReferenceStore",
"ReferenceTypeStore",
"RoomGroupStore",
diff --git a/core/switch_core/db/stores/delivery_cursor_store.py b/core/switch_core/db/stores/delivery_cursor_store.py
new file mode 100644
index 000000000..5506bb06e
--- /dev/null
+++ b/core/switch_core/db/stores/delivery_cursor_store.py
@@ -0,0 +1,76 @@
+"""Where each agent has been delivered to in each room."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sqlalchemy import func, select
+from sqlalchemy.dialects.postgresql import insert
+
+from switch_core.db.models import DeliveryCursor
+
+if TYPE_CHECKING:
+ from collections.abc import Collection
+
+ from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class DeliveryCursorStore:
+ async def position(self, session: AsyncSession, agent_id: str, room_id: str) -> int:
+ """How far this agent has been delivered, 0 if it never has.
+
+ Zero rather than None because `seq` starts at 1: an agent with no
+ cursor is behind the room's first message, which is the same statement
+ the number already makes.
+ """
+ result = await session.execute(
+ select(DeliveryCursor.last_seq).where(
+ DeliveryCursor.agent_id == agent_id,
+ DeliveryCursor.room_id == room_id,
+ )
+ )
+ return result.scalar_one_or_none() or 0
+
+ async def positions_in(
+ self, session: AsyncSession, room_id: str, agent_ids: Collection[str]
+ ) -> dict[str, int]:
+ """Several agents' positions in one room, for dispatching a room once.
+
+ Agents with no cursor are absent from the map rather than present at 0,
+ so a caller can tell "never delivered" from "delivered nothing".
+ """
+ if not agent_ids:
+ return {}
+ result = await session.execute(
+ select(DeliveryCursor.agent_id, DeliveryCursor.last_seq).where(
+ DeliveryCursor.room_id == room_id,
+ DeliveryCursor.agent_id.in_(list(agent_ids)),
+ )
+ )
+ return {agent_id: last_seq for agent_id, last_seq in result.all()}
+
+ async def advance(
+ self, session: AsyncSession, agent_id: str, room_id: str, seq: int
+ ) -> None:
+ """Move the cursor forward to `seq`, never backward.
+
+ `GREATEST` rather than an assignment because two deliveries for the
+ same agent can finish out of order — a retry after a slow read, two
+ workers on the same room — and the later write must not undo the
+ further one. Rewinding a cursor redelivers, and a redelivered message
+ is indistinguishable from a new one to whoever reads it.
+ """
+ statement = insert(DeliveryCursor).values(
+ agent_id=agent_id, room_id=room_id, last_seq=seq
+ )
+ await session.execute(
+ statement.on_conflict_do_update(
+ constraint="uq_delivery_cursors_agent_room",
+ set_={
+ "last_seq": func.greatest(
+ DeliveryCursor.last_seq, statement.excluded.last_seq
+ ),
+ "updated_at": func.now(),
+ },
+ )
+ )
diff --git a/core/switch_core/db/stores/media_store.py b/core/switch_core/db/stores/media_store.py
new file mode 100644
index 000000000..409d91d88
--- /dev/null
+++ b/core/switch_core/db/stores/media_store.py
@@ -0,0 +1,15 @@
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from switch_core.db.models import MediaBlob
+
+
+class MediaStore:
+ async def put(self, session: AsyncSession, blob: MediaBlob) -> MediaBlob:
+ session.add(blob)
+ await session.flush()
+ return blob
+
+ async def get(self, session: AsyncSession, uri: str) -> MediaBlob | None:
+ result = await session.execute(select(MediaBlob).where(MediaBlob.uri == uri))
+ return result.scalar_one_or_none()
diff --git a/core/switch_core/db/stores/message_store.py b/core/switch_core/db/stores/message_store.py
new file mode 100644
index 000000000..dbb21bdbf
--- /dev/null
+++ b/core/switch_core/db/stores/message_store.py
@@ -0,0 +1,262 @@
+from collections.abc import Collection
+from datetime import UTC, datetime
+
+from sqlalchemy import func, select, text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from switch_core.db.models import Message, MessageAttachment, Room
+
+
+class MessageStore:
+ async def create(
+ self,
+ session: AsyncSession,
+ message: Message,
+ attachments: list[MessageAttachment],
+ ) -> Message:
+ """Persist a message and its files as one unit.
+
+ Attachments are numbered by their order in the list, which is the order
+ they were sent in.
+
+ The caller must not have set `seq`; this assigns it.
+ """
+ message.seq = await self._next_seq(session, message.room_id)
+ session.add(message)
+ await session.flush()
+ for position, attachment in enumerate(attachments):
+ attachment.message_id = message.id
+ attachment.position = position
+ session.add(attachment)
+ await session.flush()
+ return message
+
+ async def mark_history_backfilled(
+ self, session: AsyncSession, room_id: str
+ ) -> None:
+ """Record that this room's history has been walked to its start.
+
+ A write of the backfill's own progress, so it lives beside the writes
+ of its output: a dry run replaces this store wholesale, and anything
+ that reaches the database from outside it is a write a dry run does
+ not know to withhold.
+ """
+ room = await session.get(Room, room_id)
+ if room is None:
+ return
+ room.history_backfilled_at = datetime.now(UTC) # type: ignore[assignment]
+ await session.flush()
+
+ async def create_historical(
+ self,
+ session: AsyncSession,
+ message: Message,
+ attachments: list[MessageAttachment],
+ ) -> Message:
+ """Persist a message that predates recording, numbered below zero.
+
+ Reconstructed history cannot take positions above the live log: `seq`
+ orders the room, and giving a message from last month a number above
+ one from this morning would put it at the top of every read. It cannot
+ take positions among the live rows either — they are taken, and
+ renumbering to make room would move every cursor that points at them.
+
+ So it counts down from zero. Ordering by `seq` still walks the room in
+ the order it happened, `(room_id, seq)` stays unique, and the sign
+ carries a fact worth being able to read off a row: **positive is what
+ Switch recorded as it happened, negative is what was reconstructed
+ afterwards.**
+
+ The sign is load-bearing for delivery, not just descriptive. A cursor
+ starts at 0, so backfilling a year of history delivers none of it —
+ which is the only sane answer, since nobody wants last March's
+ messages pushed at them tonight.
+
+ The caller must not have set `seq`; this assigns it. `sent_at` is the
+ caller's to set, and must be when the message was *sent* rather than
+ when this row was written, or the reconstructed history lands in the
+ wrong place in every time window.
+ """
+ message.seq = await self._previous_seq(session, message.room_id)
+ session.add(message)
+ await session.flush()
+ for position, attachment in enumerate(attachments):
+ attachment.message_id = message.id
+ attachment.position = position
+ session.add(attachment)
+ await session.flush()
+ return message
+
+ async def _previous_seq(self, session: AsyncSession, room_id: str) -> int:
+ """The next position below the room's oldest, at most -1.
+
+ Same lock as `_next_seq`, for the same reason and against the same
+ contenders: two backfills of one room must not pick the same number,
+ and the uniqueness constraint would otherwise be the thing that noticed.
+ """
+ await session.execute(
+ text("SELECT pg_advisory_xact_lock(hashtext(:room_id))"),
+ {"room_id": room_id},
+ )
+ result = await session.execute(
+ select(func.coalesce(func.min(Message.seq), 0)).where(
+ Message.room_id == room_id
+ )
+ )
+ return min(int(result.scalar_one()), 0) - 1
+
+ async def _next_seq(self, session: AsyncSession, room_id: str) -> int:
+ """The next position in this room, allocated in commit order.
+
+ A database sequence — `Identity`, `SERIAL`, `nextval` — is the obvious
+ way to number rows and the wrong one here. It hands out a number when
+ the INSERT runs, not when the transaction commits, and it does so
+ outside transaction control so the number is never given back. Two
+ concurrent senders therefore take 7 and 8, and if 8 commits first a
+ reader paging on `seq > n` can advance its cursor past 8 while 7 is
+ still in flight. When 7 lands it is behind the cursor and is never
+ read again: a message that was delivered, recorded, and silently
+ skipped. Rare, unreproducible, and invisible — the worst shape of bug
+ this table could have.
+
+ So the number is allocated under a lock held to commit. Writers to the
+ same room serialise, which makes `seq` order and commit order the same
+ order, which is the only property a cursor actually needs. The lock is
+ an advisory one keyed on the room: it takes no row lock, so it cannot
+ deadlock against anything that updates the room itself, and Postgres
+ releases it at commit or rollback whatever happens. Two rooms whose
+ ids collide in the hash serialise against each other needlessly and
+ are otherwise unaffected.
+
+ The cost is per-room serialisation of a single INSERT on a path that
+ has already returned to the caller — the send completed before
+ recording began. Rooms do not contend with each other.
+ """
+ await session.execute(
+ text("SELECT pg_advisory_xact_lock(hashtext(:room_id))"),
+ {"room_id": room_id},
+ )
+ result = await session.execute(
+ select(func.coalesce(func.max(Message.seq), 0)).where(
+ Message.room_id == room_id
+ )
+ )
+ return int(result.scalar_one()) + 1
+
+ async def head_seq(self, session: AsyncSession, room_id: str) -> int:
+ """The room's current position, or 0 when nothing has been sent.
+
+ What a subscriber starts from when it wants everything after now
+ rather than everything. Reconstructed history is numbered below zero,
+ so an empty live log answers 0 whatever has been backfilled into it.
+ """
+ result = await session.execute(
+ select(func.coalesce(func.max(Message.seq), 0)).where(
+ Message.room_id == room_id
+ )
+ )
+ return max(int(result.scalar_one()), 0)
+
+ async def get_by_transport_event_id(
+ self, session: AsyncSession, transport_event_id: str
+ ) -> Message | None:
+ result = await session.execute(
+ select(Message).where(Message.transport_event_id == transport_event_id)
+ )
+ return result.scalar_one_or_none()
+
+ async def list_for_room(
+ self, session: AsyncSession, room_id: str, *, after_seq: int, limit: int
+ ) -> list[Message]:
+ """Oldest first, from just after `after_seq`. Pass 0 to start.
+
+ Paging on `seq` rather than a timestamp keeps the cursor exact: within
+ a room it is a total order with no ties, and `create` assigns it in
+ commit order, so no row can be skipped or repeated between pages.
+
+ This is also what a delivery cursor reads: it must see the room in the
+ order it happened, and must be able to stop part-way and resume from
+ the last row it handled. `after_seq` is exclusive, so re-reading with
+ the same cursor delivers nothing twice. Passing 0 also skips
+ reconstructed history, which is numbered below zero — a backfill is
+ not something to deliver.
+ """
+ result = await session.execute(
+ select(Message)
+ .where(Message.room_id == room_id, Message.seq > after_seq)
+ .order_by(Message.seq)
+ .limit(limit)
+ )
+ return list(result.scalars().all())
+
+ async def list_timeline(
+ self,
+ session: AsyncSession,
+ room_id: str,
+ *,
+ limit: int,
+ since: datetime | None,
+ before: datetime | None,
+ ) -> list[Message]:
+ """The newest `limit` rows in the window, newest first.
+
+ The window is half-open: `since` is included, `before` is not. Ordering
+ is by `seq` rather than `sent_at` — within a room `seq` is a total order
+ with no ties, whereas two rows can share a timestamp — so a caller that
+ asks for the newest N gets the same N every time.
+ """
+ query = select(Message).where(Message.room_id == room_id)
+ if since is not None:
+ query = query.where(Message.sent_at >= since)
+ if before is not None:
+ query = query.where(Message.sent_at < before)
+ result = await session.execute(query.order_by(Message.seq.desc()).limit(limit))
+ return list(result.scalars().all())
+
+ async def list_by_transport_event_ids(
+ self, session: AsyncSession, room_id: str, event_ids: Collection[str]
+ ) -> list[Message]:
+ """Rows for specific transport event ids within one room.
+
+ Scoped to the room so an id from elsewhere cannot be read through it.
+ """
+ if not event_ids:
+ return []
+ result = await session.execute(
+ select(Message).where(
+ Message.room_id == room_id,
+ Message.transport_event_id.in_(list(event_ids)),
+ )
+ )
+ return list(result.scalars().all())
+
+ async def attachments_for(
+ self, session: AsyncSession, message_ids: Collection[str]
+ ) -> dict[str, list[MessageAttachment]]:
+ """Attachments for several messages at once, keyed by message id.
+
+ One query for the whole page: fetching per message would put the N+1
+ back that moving the read path here is meant to remove. Messages with
+ no files are simply absent from the map.
+ """
+ if not message_ids:
+ return {}
+ result = await session.execute(
+ select(MessageAttachment)
+ .where(MessageAttachment.message_id.in_(list(message_ids)))
+ .order_by(MessageAttachment.message_id, MessageAttachment.position)
+ )
+ by_message: dict[str, list[MessageAttachment]] = {}
+ for attachment in result.scalars().all():
+ by_message.setdefault(attachment.message_id, []).append(attachment)
+ return by_message
+
+ async def get_attachments(
+ self, session: AsyncSession, message_id: str
+ ) -> list[MessageAttachment]:
+ result = await session.execute(
+ select(MessageAttachment)
+ .where(MessageAttachment.message_id == message_id)
+ .order_by(MessageAttachment.position)
+ )
+ return list(result.scalars().all())
diff --git a/core/switch_core/db/stores/room_store.py b/core/switch_core/db/stores/room_store.py
index a0b45854b..49f441c4f 100644
--- a/core/switch_core/db/stores/room_store.py
+++ b/core/switch_core/db/stores/room_store.py
@@ -2,6 +2,7 @@ from datetime import UTC, datetime
from sqlalchemy import delete, insert, or_, select, update
from sqlalchemy import func as sa_func
+from sqlalchemy.dialects.postgresql import insert as pg_insert
from sqlalchemy.ext.asyncio import AsyncSession
from switch_core.db.models import (
@@ -283,7 +284,28 @@ class RoomStore:
async def add_client(
self, session: AsyncSession, client_id: str, room_id: str
) -> None:
- session.add(ClientRoom(client_id=client_id, room_id=room_id))
+ """Record a membership, tolerating one that is already there.
+
+ Membership has more than one writer. Over Matrix it effectively had
+ one: an invitation was accepted later, over sync, long after the
+ inviting transaction had committed, so `room_service` was the only
+ thing writing this table. On the Postgres transport the invitation is
+ the join — synchronous and in-process — so the joining client writes
+ the row and the inviting caller then writes it again.
+
+ A plain insert made that second write an IntegrityError that rolled
+ the caller's whole transaction back, leaving an agent a member of the
+ room but not one of its agents: receiving messages while
+ `!list-agents` reported nobody. The conflict is a correct outcome
+ rather than a failure — the membership exists, which is what the
+ caller asked for — and this also closes the check-then-insert race
+ between two concurrent invitations.
+ """
+ await session.execute(
+ pg_insert(ClientRoom)
+ .values(client_id=client_id, room_id=room_id)
+ .on_conflict_do_nothing(index_elements=["client_id", "room_id"])
+ )
await session.flush()
async def remove_client(
@@ -297,6 +319,20 @@ class RoomStore:
)
await session.flush()
+ async def get_for_client(self, session: AsyncSession, client_id: str) -> list[Room]:
+ """The rooms a client is a member of.
+
+ The mirror of `get_client_ids`, and what a client asks for when it
+ wants to know where it belongs — over Matrix that question went to the
+ homeserver, which answered from the same memberships this table holds.
+ """
+ result = await session.execute(
+ select(Room)
+ .join(ClientRoom, ClientRoom.room_id == Room.id)
+ .where(ClientRoom.client_id == client_id)
+ )
+ return list(result.scalars().all())
+
async def get_client_ids(self, session: AsyncSession, room_id: str) -> list[str]:
result = await session.execute(
select(ClientRoom.client_id).where(ClientRoom.room_id == room_id)
diff --git a/core/switch_core/delivery/__init__.py b/core/switch_core/delivery/__init__.py
new file mode 100644
index 000000000..83803f729
--- /dev/null
+++ b/core/switch_core/delivery/__init__.py
@@ -0,0 +1,14 @@
+"""Working out who a message is for, independently of how it arrived.
+
+Everything here takes a message as data — a sender, a body, a content dict —
+rather than a transport event, so the same rules apply whether the message came
+off the bus or was read back out of the message log.
+"""
+
+from switch_core.delivery.addressing import (
+ AddressingDecision,
+ AddressingResolver,
+ IncomingMessage,
+)
+
+__all__ = ["AddressingDecision", "AddressingResolver", "IncomingMessage"]
diff --git a/core/switch_core/delivery/addressing.py b/core/switch_core/delivery/addressing.py
new file mode 100644
index 000000000..279225f2e
--- /dev/null
+++ b/core/switch_core/delivery/addressing.py
@@ -0,0 +1,360 @@
+"""Whether a message addresses a given agent, and whether it is allowed to.
+
+Two separate questions, deliberately kept apart:
+
+- **Addressed** is about intent. Did this message ask this agent for something
+ — by name, by the alias it goes under in this room, by a role it holds, or
+ by being the only other party in a direct chat?
+- **Permitted** is about authority. An agent may carry a scoped addressing
+ policy saying who is allowed to ask it for things at all.
+
+A message can be addressed and not permitted, and the caller demotes it to
+ordinary room chatter when so. Nothing here sends anything; deciding is all it
+does, and the refusal wording travels back with the decision so the caller does
+not have to re-derive why.
+
+This used to live on `AgentClient`, where every answer was reached through a
+live Matrix client. It takes a message as data instead — a sender, a body, a
+content dict — so the same rules decide for a message read out of the log as
+for one that arrived on the bus. That equivalence is the point: two code paths
+answering "is this for me?" differently would be a security bug waiting for a
+rewrite to expose it.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, NamedTuple
+
+from switch_core.addressing import SenderKind, can_address, parse_policy
+from switch_core.clients.admin_messages import ADMIN_MARKER
+from switch_core.clients.mentions import mention_regex, strip_emphasis
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+ from sqlalchemy.ext.asyncio import AsyncSession
+
+ from switch_core.db.models import Agent
+ from switch_core.db.stores.agent_store import AgentStore
+ from switch_core.db.stores.client_store import ClientStore
+ from switch_core.db.stores.external_user_store import ExternalUserStore
+ from switch_core.db.stores.room_role_store import RoomRoleStore
+ from switch_core.db.stores.room_store import RoomStore
+
+logger = logging.getLogger(__name__)
+
+# Posted (once, guarded by an auto-reply flag) when a sender tags an agent but
+# the agent's scoped addressing policy does not permit that sender to address
+# it there. The message is demoted to unaddressed room chatter; this reply is
+# the sender's only feedback that the attempt was rejected.
+ADDRESSING_DENIED_MESSAGE = (
+ "You're not permitted to direct messages to me in this room — my operator "
+ "has restricted who can address me here."
+)
+
+
+# The same refusal, for the case worth telling apart: the agent answers only to
+# its owner, and the sender's chat account is not linked to any Switch user, so
+# it cannot be recognised as the owner even if it is. Without this the owner
+# gets refused by their own agent with no idea why.
+ADDRESSING_UNCLAIMED_MESSAGE = (
+ "I only take instructions from my owner, and this chat account isn't "
+ "linked to a Switch user yet — so I can't tell whether that's you. If it "
+ "is, link this account to your Switch user in Switch Console and try again."
+)
+
+
+@dataclass(frozen=True)
+class IncomingMessage:
+ """What addressing needs to know about a message, and nothing else.
+
+ `formatted_body` is where a Matrix client puts a rendered mention pill,
+ which is the one addressing signal that has no plain-text equivalent. It is
+ absent on media events and on anything read back from the log that never
+ had one, so it is never the only thing consulted.
+ """
+
+ sender: str
+ body: str
+ formatted_body: str | None = None
+ content: dict = field(default_factory=dict)
+
+
+class AddressingDecision(NamedTuple):
+ """Whether a sender may address an agent, and what to say if not."""
+
+ allowed: bool
+ refusal: str
+
+
+class SenderPrincipal(NamedTuple):
+ """Who a sender turned out to be, in the terms a policy is written in.
+
+ `user_ids` and `owner_user_id` are the two ways a symbolic subject
+ resolves, and are mutually exclusive: a human has claimants, an agent has
+ an owner.
+ """
+
+ kind: SenderKind
+ id: str
+ user_ids: list[str]
+ owner_user_id: str | None
+
+
+class AddressingResolver:
+ """Answers "is this for that agent, and may it be?" from stores alone."""
+
+ def __init__(
+ self,
+ *,
+ room_store: RoomStore,
+ room_role_store: RoomRoleStore,
+ client_store: ClientStore,
+ agent_store: AgentStore,
+ external_user_store: ExternalUserStore,
+ live_agent_ids: Callable[[], set[str]],
+ ) -> None:
+ self._room_store = room_store
+ self._room_role_store = room_role_store
+ self._client_store = client_store
+ self._agent_store = agent_store
+ self._external_user_store = external_user_store
+ # A callable rather than a set: a role only routes while its holder's
+ # session is live, and that changes between one message and the next.
+ self._live_agent_ids = live_agent_ids
+
+ # ── Addressed ─────────────────────────────────────────────────────────────
+
+ def addressed_without_lookup(
+ self,
+ *,
+ agent: Agent,
+ agent_matrix_id: str,
+ channel_type: str | None,
+ message: IncomingMessage,
+ ) -> bool | None:
+ """The addressing answer that needs no database read, or None when the
+ room's aliases and role leases have to be consulted.
+
+ Callers use it to decide whether to take a pool slot at all: most room
+ chatter carries no `@` and is answered here, and a room fans every
+ message out to all of its agent clients at once.
+ """
+ if ADMIN_MARKER in message.content:
+ return False
+ if channel_type == "direct":
+ return True
+ if self.mentions_name(
+ agent=agent, agent_matrix_id=agent_matrix_id, message=message
+ ):
+ return True
+ if "@" not in message.body:
+ return False
+ return None
+
+ async def addresses(
+ self,
+ session: AsyncSession,
+ *,
+ agent: Agent,
+ agent_matrix_id: str,
+ room_id: str,
+ channel_type: str | None,
+ message: IncomingMessage,
+ ) -> bool:
+ """Whether this message asks this agent for something.
+
+ **A system message never addresses anyone**, whatever the room type.
+ Switch's own notices — a command's answer, "Added X to this room", the
+ guidance shown when someone tags the app itself — are output, not a
+ request for a reply. Two ways they were read as one: in a direct room
+ every message addresses the agent, so running `/list-agents` in a 1:1
+ chat had the agent start a session to respond to its own roster; and in
+ any room, a notice that lists the agents present writes each `@name`,
+ which tagged every one of them. The marker exists to say "generated by
+ Switch"; this is it being honoured.
+ """
+ decided = self.addressed_without_lookup(
+ agent=agent,
+ agent_matrix_id=agent_matrix_id,
+ channel_type=channel_type,
+ message=message,
+ )
+ if decided is not None:
+ return decided
+ if await self.mentions_alias(
+ session, agent=agent, room_id=room_id, message=message
+ ):
+ return True
+ return await self.mentions_role(
+ session, agent=agent, room_id=room_id, message=message
+ )
+
+ def mentions_name(
+ self, *, agent: Agent, agent_matrix_id: str, message: IncomingMessage
+ ) -> bool:
+ """An `@name` at a token boundary, or a rendered mention pill.
+
+ The pill is checked first because it is unambiguous. The plain-text
+ scan is what catches everything else — media captions carry no
+ formatted body, and neither does a bridged message.
+ """
+ if message.formatted_body and agent_matrix_id in message.formatted_body:
+ return True
+ return (
+ mention_regex(agent.name).search(strip_emphasis(message.body)) is not None
+ )
+
+ async def mentions_alias(
+ self,
+ session: AsyncSession,
+ *,
+ agent: Agent,
+ room_id: str,
+ message: IncomingMessage,
+ ) -> bool:
+ """An `@alias` for the name this agent goes under in this room.
+
+ A room alias addresses the agent exactly like its real name. Looked up
+ live, so a change takes effect on the next message with no per-client
+ cache to invalidate.
+ """
+ if "@" not in message.body:
+ return False
+ alias = await self._room_store.get_alias(session, room_id, agent.id)
+ if not alias:
+ return False
+ return mention_regex(alias).search(message.body) is not None
+
+ async def mentions_role(
+ self,
+ session: AsyncSession,
+ *,
+ agent: Agent,
+ room_id: str,
+ message: IncomingMessage,
+ ) -> bool:
+ """An `@role` for a room-role this agent LIVE-holds.
+
+ Tagging a role reaches whoever is doing that job, so an interchangeable
+ agent can be addressed by responsibility rather than by name. Only a
+ live lease counts, which makes "held" mean the same thing here as in
+ `!roles`: a stale lease — session gone, role auto-released, shown free
+ — does not route here. A holder whose session merely hopped to another
+ room still matches, because the renewal loop keeps that lease alive.
+ """
+ if "@" not in message.body:
+ return False
+ role_name = await self._room_role_store.agent_room_role(
+ session, room_id, agent.id, self._live_agent_ids()
+ )
+ if not role_name:
+ return False
+ return mention_regex(role_name).search(strip_emphasis(message.body)) is not None
+
+ # ── Permitted ─────────────────────────────────────────────────────────────
+
+ async def permitted(
+ self, session: AsyncSession, *, agent: Agent, room_id: str, sender: str
+ ) -> AddressingDecision:
+ """Whether `sender` may address this agent in this room.
+
+ An agent with no policy is open to anyone, so this answers without a
+ database round-trip. With a policy set it is deny-by-default: a sender
+ that resolves to nothing is refused rather than given the benefit of
+ the doubt, because an identity nobody can name is exactly what a
+ restricted agent is restricted against.
+ """
+ policy = parse_policy(agent.addressing_policy)
+ if policy.is_open():
+ return AddressingDecision(allowed=True, refusal="")
+
+ principal = await self.resolve_sender(session, sender)
+ room = await self._room_store.get(session, room_id)
+
+ if principal is None:
+ logger.warning(
+ "Addressing denied for %s: unresolvable sender %s in room %s",
+ agent.name,
+ sender,
+ room_id,
+ )
+ return AddressingDecision(allowed=False, refusal=ADDRESSING_DENIED_MESSAGE)
+
+ allowed = can_address(
+ policy,
+ room_id=room_id,
+ group_id=room.group_id if room is not None else None,
+ sender_kind=principal.kind,
+ sender_id=principal.id,
+ sender_user_ids=principal.user_ids,
+ sender_owner_user_id=principal.owner_user_id,
+ owner_user_id=agent.owner_id,
+ )
+ if allowed:
+ return AddressingDecision(allowed=True, refusal="")
+
+ # An owner-scoped rule cannot match a human nobody has claimed, so the
+ # refusal says what to fix rather than implying a decision was made.
+ unclaimed = (
+ principal.kind == "user"
+ and not principal.user_ids
+ and policy.requires_owner_identity()
+ )
+ if unclaimed:
+ logger.warning(
+ "Addressing denied for %s: sender %s in room %s has not been "
+ "claimed by any Switch user, so an owner-scoped rule cannot "
+ "match them — the owner may need to link this identity",
+ agent.name,
+ principal.id,
+ room_id,
+ )
+ else:
+ logger.warning(
+ "Addressing denied for %s: %s %s not permitted in room %s",
+ agent.name,
+ principal.kind,
+ principal.id,
+ room_id,
+ )
+ return AddressingDecision(
+ allowed=False,
+ refusal=(
+ ADDRESSING_UNCLAIMED_MESSAGE if unclaimed else ADDRESSING_DENIED_MESSAGE
+ ),
+ )
+
+ async def resolve_sender(
+ self, session: AsyncSession, matrix_user_id: str
+ ) -> SenderPrincipal | None:
+ """Map a sender's mxid to the principal a policy is written about.
+
+ Every participant is a Switch client, so the mxid resolves to a Client
+ and from there to either an Agent (an agent-to-agent attempt) or an
+ ExternalUser (a human on a bridge). None means neither, which a
+ restricted agent should not trust.
+
+ The two symbolic subjects come from different fields and only one
+ applies to any sender: `user_ids` are the Switch users who have claimed
+ a human's platform account — empty for an agent, which is never its own
+ owner — and `owner_user_id` is who owns an agent sender, None for a
+ human.
+ """
+ client = await self._client_store.get_by_matrix_user_id(session, matrix_user_id)
+ if client is None:
+ return None
+ agent = await self._agent_store.get_by_client_id(session, client.id)
+ if agent is not None:
+ return SenderPrincipal("agent", agent.id, [], agent.owner_id)
+ external_user = await self._external_user_store.get_by_client_id(
+ session, client.id
+ )
+ if external_user is not None:
+ claimants = await self._external_user_store.claimant_ids(
+ session, external_user.id
+ )
+ return SenderPrincipal("user", external_user.id, claimants, None)
+ return None
diff --git a/core/switch_core/events.py b/core/switch_core/events.py
index dcd46ac9d..b5fa1835f 100644
--- a/core/switch_core/events.py
+++ b/core/switch_core/events.py
@@ -3,11 +3,6 @@ from __future__ import annotations
from pydantic import BaseModel, ConfigDict
-class MediationResult(BaseModel):
- verdict: str
- reason: str | None = None
-
-
class SwitchEvent(BaseModel):
model_config = ConfigDict(extra="allow")
@@ -30,48 +25,6 @@ class CommandEvent(SwitchEvent):
thread_id: str | None = None
-# ── Mediation (pre-invocation) ────────────────────────────────────────────────
-
-
-class MediationToolRequest(SwitchEvent):
- request_id: str
- agent_id: str
- tool_id: str
- args: dict[str, object]
- task_id: str | None = None
- status: str
-
-
-class MediationLlmRequest(SwitchEvent):
- request_id: str
- agent_id: str
- model_id: str
- messages: list[dict[str, object]]
- task_id: str | None = None
- status: str
-
-
-# ── Mediation (post-invocation) ───────────────────────────────────────────────
-
-
-class MediationToolResult(SwitchEvent):
- request_id: str
- agent_id: str
- tool_id: str
- result: object
- task_id: str | None = None
- status: str
-
-
-class MediationLlmResponse(SwitchEvent):
- request_id: str
- agent_id: str
- model_id: str
- response: object
- task_id: str | None = None
- status: str
-
-
# ── Event reporting ───────────────────────────────────────────────────────────
@@ -164,19 +117,3 @@ class AgentRuntimeStateEvent(SwitchEvent):
# the agent really has. Unchanged between reports (e.g. the periodic
# activity refresh) means the indicator stays where it is.
anchor_event_id: str | None = None
-
-
-# ── Permission ────────────────────────────────────────────────────────────────
-
-
-class PermissionRequest(SwitchEvent):
- request_id: str
- agent_id: str
- action: str
- details: dict[str, object] | None = None
-
-
-class PermissionResponse(SwitchEvent):
- request_id: str
- approved: bool
- responder_id: str
diff --git a/core/switch_core/main.py b/core/switch_core/main.py
index 5da5e89a7..0f07aaa7a 100644
--- a/core/switch_core/main.py
+++ b/core/switch_core/main.py
@@ -22,7 +22,6 @@ from switch_core.bridges.agent.protocol.connections import (
)
from switch_core.bridges.agent.protocol.event_buffer import EventBuffer
from switch_core.bridges.agent.protocol.service import ProtocolService
-from switch_core.bridges.agent.request_tracker import RequestTracker
from switch_core.bridges.agent.server_connectors.lifecycle import (
ServerSideConnectorLifecycleService,
)
@@ -54,16 +53,18 @@ from switch_core.bridges.collaboration.telegram.adapter import (
TelegramConnectionConfig,
)
from switch_core.bridges.resource.service import ResourceService
-from switch_core.bridges.resource.tracker import ResourceRequestTracker
from switch_core.clients.admin_client import AdminClient
from switch_core.clients.agent_client import AgentClient
from switch_core.clients.client_base import ClientBase
from switch_core.clients.client_factory import ClientFactory
from switch_core.clients.client_lifecycle_service import ClientLifecycleService
-from switch_core.clients.resource_manager_client import ResourceManagerClient
from switch_core.config import SwitchConfig
from switch_core.crypto import encrypt_token
-from switch_core.db.engine import create_engine_from_config, create_session_factory
+from switch_core.db.engine import (
+ create_engine_from_config,
+ create_session_factory,
+ create_unpooled_engine,
+)
from switch_core.db.models import ApiKey, User
from switch_core.db.stores.agent_session_store import AgentSessionStore
from switch_core.db.stores.agent_store import AgentStore
@@ -73,6 +74,8 @@ from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore
from switch_core.db.stores.document_store import DocumentStore
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.package_store import PackageStore
from switch_core.db.stores.reference_store import ReferenceStore
from switch_core.db.stores.reference_type_store import ReferenceTypeStore
@@ -90,7 +93,13 @@ from switch_core.matrix_admin import (
ensure_admin_exists,
wait_for_homeserver,
)
+from switch_core.messages import MessageRecorder
+from switch_core.messages.notify import MessageListener
+from switch_core.provisioning import Provisioning
+from switch_core.provisioning.postgres import PostgresProvisioning
from switch_core.room_service import RoomService
+from switch_core.transport.ephemeral import EphemeralBus
+from switch_core.transport.invites import InviteBus
from switch_core.version import switch_core_version
logger = logging.getLogger(__name__)
@@ -176,21 +185,15 @@ async def run() -> None:
# ── Database ─────────────────────────────────────────────────────────────
engine = create_engine_from_config(config)
session_factory = create_session_factory(engine)
+ # Its connection is held rather than borrowed, so it builds its own outside
+ # the pool. Nothing subscribes yet; it starts with the server so that the
+ # subscription exists before the first consumer needs it.
+ message_listener = MessageListener(lambda: create_unpooled_engine(config))
- # ── Matrix homeserver admin ──────────────────────────────────────────────
- await wait_for_homeserver(config.matrix_server)
- await ensure_admin_exists(
- server_url=config.matrix_server,
- username=config.matrix_admin_user,
- password=config.matrix_admin_password,
- shared_secret=config.matrix_registration_shared_secret,
- )
- matrix_admin = await MatrixAdmin.create(
- server_url=config.matrix_server,
- admin_user=config.matrix_admin_user,
- admin_password=config.matrix_admin_password,
- shared_secret=config.matrix_registration_shared_secret,
- )
+ # Invitations for the Postgres transport, which has no durable one of its
+ # own. Built unconditionally: it is a dict until something registers.
+ invites = InviteBus()
+ ephemeral = EphemeralBus()
# ── Stores ───────────────────────────────────────────────────────────────
agent_store = AgentStore()
@@ -210,6 +213,13 @@ async def run() -> None:
room_link_store = RoomLinkStore()
room_group_store = RoomGroupStore()
room_role_store = RoomRoleStore()
+ message_store = MessageStore()
+ media_store = MediaStore()
+ message_recorder = MessageRecorder(
+ session_factory=session_factory,
+ room_store=room_store,
+ message_store=message_store,
+ )
# ── Seed admin user + registration key ──────────────────────────────────
await _seed_admin_user(session_factory, user_store, config)
@@ -219,8 +229,6 @@ async def run() -> None:
# ── Event queue + request trackers ───────────────────────────────────────
event_buffer = EventBuffer()
- request_tracker = RequestTracker()
- resource_request_tracker = ResourceRequestTracker()
connector_store = ServerConnectorStore()
# ── Resource service ─────────────────────────────────────────────────────
@@ -235,6 +243,38 @@ async def run() -> None:
async with session_factory() as session:
await resource_service.log_builtin_shadowing(session)
+ # ── Provisioning ─────────────────────────────────────────────────────────
+ # The homeserver is only contacted when it is the transport. Reaching it
+ # unconditionally would keep a Postgres deployment waiting on, and failing
+ # to start without, a service it does not use.
+ matrix_admin: Provisioning
+ if config.message_transport == "matrix":
+ await wait_for_homeserver(config.matrix_server)
+ await ensure_admin_exists(
+ server_url=config.matrix_server,
+ username=config.matrix_admin_user,
+ password=config.matrix_admin_password,
+ shared_secret=config.matrix_registration_shared_secret,
+ )
+ matrix_admin = await MatrixAdmin.create(
+ server_url=config.matrix_server,
+ admin_user=config.matrix_admin_user,
+ admin_password=config.matrix_admin_password,
+ shared_secret=config.matrix_registration_shared_secret,
+ )
+ else:
+ logger.warning(
+ "Running on the Postgres transport: no homeserver is contacted, "
+ "and media uploaded before the switch cannot be served"
+ )
+ matrix_admin = PostgresProvisioning(
+ session_factory=session_factory,
+ room_store=room_store,
+ client_store=client_store,
+ message_store=message_store,
+ invites=invites,
+ )
+
# One connection registry for the process. Created here rather than inside
# the agent bridge because the Matrix agent clients are wired first and read
# presence from it — an agent is reachable if it has a live connection OR a
@@ -246,6 +286,13 @@ async def run() -> None:
client_store=client_store,
session_factory=session_factory,
config=config,
+ message_recorder=message_recorder,
+ room_store=room_store,
+ message_store=message_store,
+ media_store=media_store,
+ listener=message_listener,
+ invites=invites,
+ ephemeral=ephemeral,
)
client_factory.register(
"agent",
@@ -259,19 +306,9 @@ async def run() -> None:
agent_session_store=agent_session_store,
room_role_store=room_role_store,
external_user_store=external_user_store,
- request_tracker=request_tracker,
- resource_request_tracker=resource_request_tracker,
connections=connections,
frontend_base_url=config.frontend_base_url,
)
- client_factory.register(
- "resource_manager",
- ResourceManagerClient,
- agent_store=agent_store,
- room_store=room_store,
- resource_service=resource_service,
- request_tracker=request_tracker,
- )
client_factory.register("user", ClientBase)
client_factory.register("bridge", ClientBase)
@@ -297,6 +334,7 @@ async def run() -> None:
matrix_admin=matrix_admin,
session_factory=session_factory,
config=config,
+ client_factory=client_factory,
)
# ── Room service ─────────────────────────────────────────────────────────
@@ -339,8 +377,6 @@ async def run() -> None:
collab_lifecycle=collab_lifecycle,
event_buffer=event_buffer,
task_store=task_store,
- request_tracker=request_tracker,
- resource_request_tracker=resource_request_tracker,
resource_service=resource_service,
api_key_store=api_key_store,
external_user_store=external_user_store,
@@ -403,7 +439,6 @@ async def run() -> None:
agent_bridge_app.mount("/gateway", gateway_app)
# ── Ensure system clients exist ─────────────────────────────────────────
- await client_lifecycle.ensure_system_client("resource_manager")
await client_lifecycle.ensure_system_client("admin")
# ── Lifespan: start server-side connectors once HTTP is serving ────────
@@ -417,11 +452,13 @@ async def run() -> None:
connection_sweep_task = asyncio.create_task(
_connection_sweep_loop(protocol)
)
+ await message_listener.start()
try:
yield
finally:
sweep_task.cancel()
connection_sweep_task.cancel()
+ await message_listener.stop()
agent_bridge_app.router.lifespan_context = lifespan # type: ignore[assignment]
@@ -529,7 +566,7 @@ async def _shutdown(
client_lifecycle: ClientLifecycleService,
collab_lifecycle: CollaborationBridgeLifecycleService,
connector_lifecycle: ServerSideConnectorLifecycleService,
- matrix_admin: MatrixAdmin,
+ matrix_admin: Provisioning,
) -> None:
logger.info("Shutting down...")
server.should_exit = True
diff --git a/core/switch_core/messages/__init__.py b/core/switch_core/messages/__init__.py
new file mode 100644
index 000000000..31b8b41b1
--- /dev/null
+++ b/core/switch_core/messages/__init__.py
@@ -0,0 +1,19 @@
+from switch_core.messages.backfill import BackfillReport, backfill_room
+from switch_core.messages.reconcile import (
+ Mismatch,
+ RoomReconciliation,
+ reconcile_room,
+)
+from switch_core.messages.recorded_types import NOT_RECORDED, should_record
+from switch_core.messages.recorder import MessageRecorder
+
+__all__ = [
+ "NOT_RECORDED",
+ "BackfillReport",
+ "MessageRecorder",
+ "Mismatch",
+ "RoomReconciliation",
+ "backfill_room",
+ "reconcile_room",
+ "should_record",
+]
diff --git a/core/switch_core/messages/backfill.py b/core/switch_core/messages/backfill.py
new file mode 100644
index 000000000..d401756c0
--- /dev/null
+++ b/core/switch_core/messages/backfill.py
@@ -0,0 +1,286 @@
+"""Reconstructs a room's history from the bus into the message log.
+
+Recording began when the recorder was deployed. Everything a room said before
+that is on the message bus and nowhere else — which did not matter while the
+read path went to the bus too, and matters a great deal now that it does not.
+On the first deployment to record and then read, that was 731 of 739 bridged
+messages: still on the homeserver, invisible to every agent.
+
+This walks a room backwards and writes the messages it finds that have no row.
+
+**Reconstructed rows are numbered below zero.** `seq` orders the room, so a
+message from last month cannot take a number above one from this morning, and
+it cannot take a number among the live rows either — those are taken, and
+renumbering to make room would move every cursor pointing at them. Counting
+down from zero keeps the order right, keeps `(room_id, seq)` unique, and makes
+the sign say something worth being able to read off a row: positive was
+recorded as it happened, negative was reconstructed afterwards. Delivery
+cursors start at 0, so none of this is pushed at anybody.
+
+**It is idempotent, and that is not incidental.** A backfill over a busy room
+is long, and the useful thing to do with a walk that failed halfway is to run
+it again. `transport_event_id` is unique, so every row this would write is
+either absent or already correct; the walk checks before writing and the
+constraint is the backstop.
+
+**What it does not reconstruct.** Only what the log is scoped to keep — see
+`recorded_types` — so bus traffic that was never part of the conversation
+stays out, exactly as it does going forward. Arrivals are reconstructed:
+membership is on the bus and the timeline reads wrong without them. Sender
+display names come from the event where the bus carried one and are otherwise
+null, which is what the read path already tolerates.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from switch_core.db.models import Message, MessageAttachment
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPE, should_record
+from switch_core.transport import (
+ InboundCustomEvent,
+ InboundEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+)
+
+if TYPE_CHECKING:
+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+ from switch_core.db.models import Room
+ from switch_core.transport import MessageTransport
+
+logger = logging.getLogger(__name__)
+
+# One page of backwards history, matching the reconciliation walk so a backfill
+# puts no unusual shape of load on the homeserver.
+PAGE_SIZE = 100
+
+# A stop for a walk that would otherwise never end. Reached only if the
+# homeserver keeps handing out pages with a cursor that advances forever; a
+# room that ends returns no next token and stops on its own.
+MAX_PAGES = 10_000
+
+
+@dataclass
+class BackfillReport:
+ room_id: str
+ matrix_room_id: str
+ room_name: str
+ pages_read: int = 0
+ seen: int = 0
+ written: int = 0
+ already_present: int = 0
+ skipped_by_type: dict[str, int] = field(default_factory=dict)
+ # True when the walk stopped because it ran out of pages rather than
+ # because the room ended. The room is then partially reconstructed, and
+ # saying so matters more than the count does.
+ incomplete: bool = False
+
+ def summary(self) -> str:
+ line = (
+ f"{self.room_name} ({self.matrix_room_id}): {self.written} written, "
+ f"{self.already_present} already recorded, {self.seen} seen "
+ f"over {self.pages_read} pages"
+ )
+ if self.skipped_by_type:
+ counts = ", ".join(
+ f"{name}={count}"
+ for name, count in sorted(self.skipped_by_type.items())
+ )
+ line += f"; not part of the log: {counts}"
+ if self.incomplete:
+ line += "; INCOMPLETE — hit the page limit before the room ended"
+ return line
+
+
+async def _mark_backfilled(
+ session_factory: async_sessionmaker[AsyncSession],
+ room: Room,
+ store: MessageStore,
+) -> None:
+ """Record that this room has been walked to its start.
+
+ Through the store, so a dry run withholds it along with everything else it
+ withholds. Marking a room that a dry run only pretended to write would
+ leave the real run with nothing to do and no way to say so.
+
+ Only on a clean finish, too. A walk that stopped at the page limit leaves
+ the room partly reconstructed, and calling that done would strand the rest
+ of its history the next time round.
+ """
+ async with session_factory() as session:
+ await store.mark_history_backfilled(session, room.id)
+ await session.commit()
+
+
+async def backfill_room(
+ transport: MessageTransport,
+ session_factory: async_sessionmaker[AsyncSession],
+ room: Room,
+ *,
+ store: MessageStore,
+) -> BackfillReport:
+ """Walk one room to its start, writing every message with no row.
+
+ The transport must already be connected and a member of the room.
+
+ Each page is its own transaction. A walk that fails partway therefore
+ leaves the pages it finished written rather than rolling back an hour of
+ work, and re-running picks up where it stopped — which is the behaviour
+ that makes a long backfill practical rather than something to be afraid of.
+ """
+ report = BackfillReport(
+ room_id=room.id,
+ matrix_room_id=room.matrix_room_id,
+ room_name=room.name,
+ )
+ start: str | None = None
+ while report.pages_read < MAX_PAGES:
+ page = await transport.read_history(
+ room.matrix_room_id, start=start, limit=PAGE_SIZE
+ )
+ report.pages_read += 1
+
+ # Newest first, which is how history comes back, and the direction the
+ # numbering has to run: each row written takes the next position below
+ # the last, so walking from the newest unrecorded message towards the
+ # room's start leaves the oldest message with the lowest number. Any
+ # other order would number the room backwards.
+ for raw in page.events:
+ await _consider(raw, session_factory, room, store, report)
+
+ end = page.next_token
+ if not end or end == start:
+ await _mark_backfilled(session_factory, room, store)
+ return report
+ start = end
+
+ report.incomplete = True
+ logger.warning(
+ "Backfill of %s stopped at the %d page limit; the room is only "
+ "partially reconstructed",
+ room.matrix_room_id,
+ MAX_PAGES,
+ )
+ return report
+
+
+async def _consider(
+ raw: object,
+ session_factory: async_sessionmaker[AsyncSession],
+ room: Room,
+ store: MessageStore,
+ report: BackfillReport,
+) -> None:
+ """Write one bus event as a message row, if it belongs in the log."""
+ if not isinstance(raw, InboundEvent):
+ report.skipped_by_type["unrecognised"] = (
+ report.skipped_by_type.get("unrecognised", 0) + 1
+ )
+ return
+
+ event_type = _event_type(raw)
+ if event_type is None or not should_record(event_type):
+ name = event_type or type(raw).__name__
+ report.skipped_by_type[name] = report.skipped_by_type.get(name, 0) + 1
+ return
+
+ report.seen += 1
+ async with session_factory() as session:
+ existing = await store.get_by_transport_event_id(session, raw.event_id)
+ if existing is not None:
+ report.already_present += 1
+ return
+ message, attachments = _row_for(raw, room.id, event_type)
+ await store.create_historical(session, message, attachments)
+ await session.commit()
+ report.written += 1
+
+
+def _event_type(raw: InboundEvent) -> str | None:
+ """The log's name for this event, or None if it has no place in the log."""
+ if isinstance(raw, InboundMembership):
+ # Only an arrival. A leave is not part of the timeline the log keeps,
+ # and recording one would put a row in history with nothing to say.
+ return MEMBERSHIP_EVENT_TYPE if raw.membership == "join" else None
+ if isinstance(raw, InboundCustomEvent):
+ return raw.event_type
+ if isinstance(raw, InboundMessage):
+ return "m.room.message"
+ return None
+
+
+def _row_for(
+ raw: InboundEvent, room_id: str, event_type: str
+) -> tuple[Message, list[MessageAttachment]]:
+ """Build the row and its files from a bus event.
+
+ `sender_client_id` is left null. It is the Switch client that did the
+ sending, and the bus records an mxid rather than a client id; resolving it
+ would be a lookup per row for a column nothing reads. `sender_name` comes
+ from the event where the bus carried one.
+ """
+ content = dict(raw.content)
+ message = Message(
+ room_id=room_id,
+ transport_event_id=raw.event_id,
+ sender_matrix_id=raw.sender,
+ sender_client_id=None,
+ sender_name=_sender_name(raw, content),
+ event_type=event_type,
+ msgtype=getattr(raw, "msgtype", None),
+ body=_body(raw),
+ formatted_body=content.get("formatted_body"),
+ thread_root_event_id=getattr(raw, "thread_root_id", None),
+ content=content,
+ sent_at=datetime.fromtimestamp(raw.timestamp / 1000, tz=UTC),
+ )
+ return message, _attachments(raw, content)
+
+
+def _sender_name(raw: InboundEvent, content: dict) -> str | None:
+ if isinstance(raw, InboundMembership):
+ return raw.display_name
+ name = content.get("sender_name")
+ return str(name) if name else None
+
+
+def _body(raw: InboundEvent) -> str | None:
+ # An arrival carries no body: how it reads is the reader's to phrase, and
+ # a rendered sentence in the log would freeze today's wording into every
+ # row ever written. Matches what the live recorder does.
+ if isinstance(raw, InboundMembership):
+ return None
+ return getattr(raw, "body", None)
+
+
+def _attachments(raw: InboundEvent, content: dict) -> list[MessageAttachment]:
+ """The files on this event, which on the bus is at most one.
+
+ Matrix has no multi-attachment event, so a send of several files is
+ several events sharing a group key. Reconstructing them as one row would
+ mean holding a page's worth of parts and guessing which belong together;
+ they are written as they were sent instead, and the group key survives in
+ `content` for anyone who wants to coalesce them later.
+ """
+ if not isinstance(raw, InboundMedia):
+ return []
+ info = content.get("info") or {}
+ size = info.get("size") if isinstance(info, dict) else None
+ return [
+ MessageAttachment(
+ uri=raw.uri,
+ filename=content.get("filename") or raw.body,
+ mimetype=info.get("mimetype") if isinstance(info, dict) else None,
+ size=int(size) if isinstance(size, int) else None,
+ )
+ ]
+
+
+__all__ = ["BackfillReport", "backfill_room"]
diff --git a/core/switch_core/messages/notify.py b/core/switch_core/messages/notify.py
new file mode 100644
index 000000000..f72fd5a68
--- /dev/null
+++ b/core/switch_core/messages/notify.py
@@ -0,0 +1,260 @@
+"""Listens for new-message announcements and wakes whoever cares.
+
+The database announces every insert into `messages` (see
+`switch_core/db/notify_ddl.py`). This is the other half: one long-lived
+connection holding a `LISTEN`, and an in-process fan-out to the consumers that
+asked about a room.
+
+**A wake-up is not a delivery.** A subscriber is told that a room has advanced
+to at least some position, never what was said. It then reads the rows it has
+not seen. Everything awkward about the notification queue — not durable, not
+replayable, delivered at most once, and only to connections that happened to
+be listening — stops mattering under that rule, because the worst a lost
+announcement can do is delay a read that a later announcement will trigger
+anyway.
+
+Two consequences are load-bearing:
+
+- **Announcements coalesce.** Only the highest position per room is kept while
+ a subscriber is busy. Ten rows arriving during one handler run produce one
+ wake-up, and the handler reads all ten, because the handler works from its
+ own cursor rather than from what it was handed. That is also why there is no
+ backpressure to apply and no queue to overflow.
+- **Reconnecting wakes every room.** A dropped connection misses
+ announcements outright, and nothing will ever replay them. So the listener
+ treats a reconnect as "everything may have moved" and wakes all subscribers,
+ which closes the gap without anyone having to detect it.
+
+The connection is deliberately not taken from the application pool. It is held
+for the process's life, never returns, and the pool's recycling and
+`idle_in_transaction_session_timeout` would both be actively wrong for it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from switch_core.db.notify_ddl import MESSAGE_CHANNEL
+
+if TYPE_CHECKING:
+ from sqlalchemy.ext.asyncio import AsyncEngine
+
+logger = logging.getLogger(__name__)
+
+# How often the listening connection is proved still alive. A half-open socket
+# reports nothing and delivers nothing, which is the failure this exists to
+# catch: without it the process looks connected and silently stops receiving.
+HEARTBEAT_SECONDS = 20.0
+
+# Backoff for a listener that cannot connect. Capped low: the whole system's
+# delivery latency is behind this, so a long sleep is a long outage.
+RECONNECT_BACKOFF_BASE = 1.0
+RECONNECT_BACKOFF_CAP = 15.0
+
+RoomWaker = Callable[[str], Awaitable[None]]
+EngineFactory = Callable[[], "AsyncEngine"]
+
+
+@dataclass(frozen=True)
+class Announcement:
+ """What the trigger said: a room moved, and how far.
+
+ `seq` is a lower bound on where the room now is, not a row to fetch. By the
+ time a subscriber runs there may be later rows, and after a coalesce there
+ certainly are.
+ """
+
+ room_id: str
+ seq: int
+ message_id: str
+
+ @staticmethod
+ def parse(payload: str) -> Announcement | None:
+ """Read one notification payload, or None if it is not one of ours.
+
+ A payload that cannot be understood is dropped with a warning rather
+ than raised: this runs inside the connection's read loop, and a bad
+ message from somewhere else on the channel must not take delivery down
+ for every room.
+ """
+ try:
+ data = json.loads(payload)
+ return Announcement(
+ room_id=str(data["room_id"]),
+ seq=int(data["seq"]),
+ message_id=str(data["id"]),
+ )
+ except (ValueError, TypeError, KeyError):
+ logger.warning(
+ "Ignoring an unreadable message announcement: %r", payload[:200]
+ )
+ return None
+
+
+class MessageListener:
+ """Holds the `LISTEN` and fans announcements out to room subscribers."""
+
+ def __init__(self, engine_factory: EngineFactory) -> None:
+ # A factory rather than an engine: reconnecting builds a fresh one, so
+ # a connection that failed leaves nothing of itself behind.
+ self._engine_factory = engine_factory
+ self._subscribers: dict[str, set[RoomWaker]] = {}
+ # Room → the highest position announced but not yet handed on. This is
+ # the coalescing buffer; see the module docstring.
+ self._pending: dict[str, int] = {}
+ self._has_pending = asyncio.Event()
+ self._tasks: list[asyncio.Task[None]] = []
+ self._running = False
+ # Set once the connection is up and every subscriber has been woken,
+ # so a caller can wait for delivery to be live rather than guess.
+ self.connected = asyncio.Event()
+
+ # ── Subscription ──────────────────────────────────────────────────────────
+
+ def subscribe(self, room_id: str, waker: RoomWaker) -> None:
+ """Ask to be woken when `room_id` advances.
+
+ The waker is called with the room id and nothing else, because what it
+ should do about it is read the rows after its own cursor. It is woken
+ once on subscribing too: a subscriber that starts mid-stream is behind
+ by definition, and making it read immediately is cheaper than making
+ every caller remember to.
+ """
+ self._subscribers.setdefault(room_id, set()).add(waker)
+ self._mark(room_id, 0)
+
+ def unsubscribe(self, room_id: str, waker: RoomWaker) -> None:
+ wakers = self._subscribers.get(room_id)
+ if wakers is None:
+ return
+ wakers.discard(waker)
+ if not wakers:
+ del self._subscribers[room_id]
+
+ # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+ async def start(self) -> None:
+ if self._running:
+ raise RuntimeError("MessageListener is already started")
+ self._running = True
+ self._tasks = [
+ asyncio.create_task(self._listen_forever(), name="message-listener"),
+ asyncio.create_task(self._fan_out_forever(), name="message-fan-out"),
+ ]
+
+ async def stop(self) -> None:
+ self._running = False
+ for task in self._tasks:
+ task.cancel()
+ for task in self._tasks:
+ with contextlib.suppress(asyncio.CancelledError):
+ await task
+ self._tasks = []
+ self.connected.clear()
+
+ # ── The listening connection ──────────────────────────────────────────────
+
+ async def _listen_forever(self) -> None:
+ attempt = 0
+ while self._running:
+ try:
+ await self._listen_once()
+ attempt = 0
+ except asyncio.CancelledError:
+ raise
+ except Exception:
+ attempt += 1
+ delay = min(
+ RECONNECT_BACKOFF_BASE * 2 ** (attempt - 1), RECONNECT_BACKOFF_CAP
+ )
+ logger.error(
+ "Message listener lost its connection; retrying in %.1fs",
+ delay,
+ exc_info=True,
+ )
+ self.connected.clear()
+ await asyncio.sleep(delay)
+
+ async def _listen_once(self) -> None:
+ engine = self._engine_factory()
+ try:
+ async with engine.connect() as connection:
+ raw = await connection.get_raw_connection()
+ driver = raw.driver_connection
+ if driver is None:
+ raise RuntimeError(
+ "No driver connection behind the message listener; "
+ "LISTEN needs asyncpg directly"
+ )
+ await driver.add_listener(MESSAGE_CHANNEL, self._on_notify)
+ try:
+ # Whatever happened while there was no connection was not
+ # queued anywhere, so assume every room moved.
+ self._wake_everything()
+ self.connected.set()
+ await self._hold_open(driver)
+ finally:
+ self.connected.clear()
+ with contextlib.suppress(Exception):
+ await driver.remove_listener(MESSAGE_CHANNEL, self._on_notify)
+ finally:
+ await engine.dispose()
+
+ async def _hold_open(self, driver: Any) -> None:
+ """Keep the connection until it fails, proving it alive as we go."""
+ while self._running:
+ await asyncio.sleep(HEARTBEAT_SECONDS)
+ await driver.execute("SELECT 1")
+
+ def _on_notify(
+ self, _connection: Any, _pid: int, _channel: str, payload: str
+ ) -> None:
+ """asyncpg's callback. Runs in the connection's read loop.
+
+ It does nothing but record a position, so a slow subscriber can never
+ stall the connection that every other room's delivery depends on.
+ """
+ announcement = Announcement.parse(payload)
+ if announcement is not None:
+ self._mark(announcement.room_id, announcement.seq)
+
+ # ── Fan-out ───────────────────────────────────────────────────────────────
+
+ def _mark(self, room_id: str, seq: int) -> None:
+ self._pending[room_id] = max(self._pending.get(room_id, 0), seq)
+ self._has_pending.set()
+
+ def _wake_everything(self) -> None:
+ for room_id in self._subscribers:
+ self._mark(room_id, 0)
+
+ async def _fan_out_forever(self) -> None:
+ while self._running:
+ await self._has_pending.wait()
+ self._has_pending.clear()
+ rooms = list(self._pending)
+ self._pending.clear()
+ for room_id in rooms:
+ await self._wake_room(room_id)
+
+ async def _wake_room(self, room_id: str) -> None:
+ for waker in list(self._subscribers.get(room_id, ())):
+ try:
+ await waker(room_id)
+ except asyncio.CancelledError:
+ raise
+ except Exception:
+ # One subscriber's failure is not the other subscribers' or the
+ # other rooms' problem; this is the delivery loop, and it has to
+ # survive whatever a handler does.
+ logger.error(
+ "A subscriber failed handling new messages in room %s",
+ room_id,
+ exc_info=True,
+ )
diff --git a/core/switch_core/messages/reconcile.py b/core/switch_core/messages/reconcile.py
new file mode 100644
index 000000000..cf1af75f2
--- /dev/null
+++ b/core/switch_core/messages/reconcile.py
@@ -0,0 +1,446 @@
+"""Compares what the message bus holds for a room against what was recorded.
+
+Recording happens after a send is accepted and cannot fail it, so a database
+problem leaves a row missing for a message that really was delivered. That is
+a deliberate trade, and this is how the cost of it is measured: before the
+read path moves onto these rows, the two records have to be shown to agree on
+a real room, not on fakes.
+
+**Only the window where recording was active is compared.** Rows exist from
+the moment the recorder was deployed; every message older than that is
+legitimately absent, and reporting a room's entire back-catalogue as missing
+would bury the one row that actually went astray. The window therefore starts
+at the oldest recorded message unless the caller names an earlier point, and
+every report says which window it covered.
+
+**The window's floor is an event id, not a moment.** A row's `sent_at` is when
+it was written, and writing happens after the send is accepted, so the bus
+event for the very first recorded message is always a little older than the
+row that describes it. A timestamp cutoff therefore excludes that event from
+the bus side while including its row on the recorded side, and the oldest
+message in every room reports as drift for as long as the room exists. Paging
+back to the oldest row's own event id instead makes the boundary exact and
+takes both clocks out of it. The timestamp survives only as a backstop, so a
+room whose anchor event is gone from the bus terminates instead of walking to
+the beginning of time — and says so rather than reporting the difference as
+drift it cannot explain.
+
+Events the bus replays that a send never produced — membership changes and
+the like — are counted by type rather than dropped, so a category nobody
+thought about shows up as unclassified instead of as agreement. Custom event
+types the recorder deliberately does not keep are counted the same way, under
+their own type name: they are absent by design, and calling that drift would
+make the report worthless.
+
+**Both sides apply that filter, not just the bus side.** A row of a type the
+bus walk discards has nothing to be compared against, so measuring it against
+an empty set reports it as recorded-but-never-sent every run, forever. Rows
+for types written before they were denied are the case that remains; they are
+counted under `unverifiable_by_type` — disclosed as outside the check rather
+than quietly dropped from it.
+
+**Arrivals are compared too**, from the point the log has one. Recording a
+join is the newest write path there is, and leaving it out made the least
+proven part of the system the one part nothing checked. Its window is its own:
+every room was joined long before arrivals were recorded, so a join older than
+the oldest recorded arrival cannot have a row and is counted rather than
+reported. After that point a join without a row is drift like any other.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, cast
+
+from sqlalchemy import select
+
+from switch_core.db.models import Message
+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPE, should_record
+from switch_core.transport import (
+ InboundCustomEvent,
+ InboundEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+)
+
+if TYPE_CHECKING:
+ from sqlalchemy.ext.asyncio import AsyncSession
+
+ from switch_core.db.models import Room
+ from switch_core.transport import MessageTransport
+
+# One page of backwards history. Matches the size the read path already uses,
+# so a reconciliation walk puts no unusual shape of load on the homeserver.
+PAGE_SIZE = 100
+
+# How far past the window the walk may go looking for the anchor event before
+# giving up. Only reached when the anchor is not on the bus at all; generous
+# because the cost of overshooting is a few extra pages, and the cost of
+# stopping early is a report that cannot tell drift from a short walk.
+ANCHOR_SEARCH_SLACK = timedelta(hours=1)
+
+
+@dataclass(frozen=True)
+class Mismatch:
+ """One field that disagrees between the bus and the recorded row."""
+
+ event_id: str
+ field_name: str
+ on_the_bus: object
+ recorded: object
+
+ def describe(self) -> str:
+ return (
+ f"{self.event_id} {self.field_name}: "
+ f"bus={self.on_the_bus!r} recorded={self.recorded!r}"
+ )
+
+
+@dataclass(frozen=True)
+class RoomReconciliation:
+ room_id: str
+ matrix_room_id: str
+ room_name: str
+ # The window compared. None means the room had no recorded messages at
+ # all, so there was nothing to compare rather than nothing wrong.
+ since: datetime | None
+ compared: int = 0
+ agreed: int = 0
+ missing_rows: list[str] = field(default_factory=list)
+ unsent_rows: list[str] = field(default_factory=list)
+ mismatches: list[Mismatch] = field(default_factory=list)
+ ignored_by_type: dict[str, int] = field(default_factory=dict)
+ # Rows of a type the bus walk does not collect, so nothing could be
+ # compared against them. Not drift, but not checked either.
+ unverifiable_by_type: dict[str, int] = field(default_factory=dict)
+ # Whether the walk reached the oldest recorded row's own event. False means
+ # the boundary fell back to a timestamp, so the edge of the window is
+ # approximate and a difference there may be an artefact of the walk.
+ anchored: bool = True
+
+ @property
+ def compared_nothing(self) -> bool:
+ return self.since is None
+
+ @property
+ def clean(self) -> bool:
+ return not (self.missing_rows or self.unsent_rows or self.mismatches)
+
+ def summary(self) -> str:
+ where = f"{self.room_name} ({self.matrix_room_id})"
+ if self.since is None:
+ return f"{where}: no recorded messages, nothing to compare"
+ verdict = "clean" if self.clean else "DRIFT"
+ line = (
+ f"{where}: {verdict} — {self.agreed}/{self.compared} agreed, "
+ f"{len(self.missing_rows)} missing, {len(self.unsent_rows)} unsent, "
+ f"{len(self.mismatches)} mismatched (since {self.since.isoformat()})"
+ )
+ if self.unverifiable_by_type:
+ skipped = sum(self.unverifiable_by_type.values())
+ line += f"; {skipped} rows not checkable against the bus"
+ if not self.anchored:
+ line += "; WINDOW UNANCHORED — oldest recorded event not found on the bus"
+ return line
+
+
+async def reconcile_room(
+ transport: MessageTransport,
+ session: AsyncSession,
+ room: Room,
+ *,
+ since: datetime | None = None,
+) -> RoomReconciliation:
+ """Compare one room. `since` overrides the recorded-from cutoff.
+
+ The transport must already be connected and a member of the room.
+ """
+ anchor = await _oldest_recorded(session, room.id)
+ # `Message.sent_at` is a timestamptz the models annotate as `str` — the
+ # established convention across every model in this package.
+ recorded_from = cast("datetime | None", anchor.sent_at) if anchor else None
+ window_start = since or recorded_from
+ if window_start is None:
+ return RoomReconciliation(
+ room_id=room.id,
+ matrix_room_id=room.matrix_room_id,
+ room_name=room.name,
+ since=None,
+ )
+
+ # An explicit `since` is the caller overriding the boundary, so the anchor
+ # only applies when the window is the recorded one.
+ anchor_event_id = anchor.transport_event_id if anchor and since is None else None
+ oldest_join = await _oldest_recorded_join(session, room.id)
+ on_the_bus, ignored, anchored = await _read_back_to(
+ transport,
+ room.matrix_room_id,
+ anchor_event_id=anchor_event_id,
+ floor_ms=_to_ms(window_start - ANCHOR_SEARCH_SLACK),
+ window_start_ms=_to_ms(window_start),
+ joins_from_ms=_joins_from_ms(oldest_join),
+ join_anchor_id=oldest_join.transport_event_id if oldest_join else None,
+ )
+ recorded = await _recorded_since(session, room.id, window_start)
+
+ agreed = 0
+ missing_rows: list[str] = []
+ mismatches: list[Mismatch] = []
+ for event_id, event in on_the_bus.items():
+ row = recorded.get(event_id)
+ if row is None:
+ missing_rows.append(event_id)
+ continue
+ found = _compare(event_id, event, row)
+ if found:
+ mismatches.extend(found)
+ else:
+ agreed += 1
+
+ unsent_rows: list[str] = []
+ unverifiable: dict[str, int] = {}
+ for event_id, row in recorded.items():
+ if event_id in on_the_bus:
+ continue
+ if _comparable(row):
+ unsent_rows.append(event_id)
+ else:
+ unverifiable[row.event_type] = unverifiable.get(row.event_type, 0) + 1
+
+ return RoomReconciliation(
+ room_id=room.id,
+ matrix_room_id=room.matrix_room_id,
+ room_name=room.name,
+ since=window_start,
+ compared=len(on_the_bus),
+ agreed=agreed,
+ missing_rows=missing_rows,
+ unsent_rows=unsent_rows,
+ mismatches=mismatches,
+ ignored_by_type=ignored,
+ unverifiable_by_type=unverifiable,
+ anchored=anchored,
+ )
+
+
+def _comparable(row: Message) -> bool:
+ """Whether the bus walk would have collected this row's event.
+
+ A row written before its type was denied has a bus event the walk now
+ discards; measuring it against the collected set says "recorded, never
+ sent" every single run.
+ """
+ return should_record(row.event_type)
+
+
+def _joins_from_ms(oldest_join: Message | None) -> int | None:
+ """The point from which a bus arrival is expected to have a row.
+
+ None means the log holds no arrival for this room, so every join on the
+ bus predates the path that records them and none can be compared.
+
+ The bound is the oldest recorded arrival's `sent_at`, which is fractionally
+ later than its own bus event — so that one event is admitted by event id
+ instead, the same way the window's anchor is.
+ """
+ if oldest_join is None:
+ return None
+ return _to_ms(cast("datetime", oldest_join.sent_at))
+
+
+def _to_ms(moment: datetime) -> int:
+ return int(moment.timestamp() * 1000)
+
+
+async def _oldest_recorded_join(session: AsyncSession, room_id: str) -> Message | None:
+ """The first arrival the log holds for this room, which bounds join checking."""
+ result = await session.execute(
+ select(Message)
+ .where(Message.room_id == room_id, Message.event_type == MEMBERSHIP_EVENT_TYPE)
+ .order_by(Message.seq)
+ .limit(1)
+ )
+ return result.scalars().first()
+
+
+async def _oldest_recorded(session: AsyncSession, room_id: str) -> Message | None:
+ """The row recording began with, which anchors the window.
+
+ Ordered by `seq` rather than `sent_at`: within a room `seq` is a total
+ order with no ties, so "the first row" is a fact rather than whichever of
+ two equal timestamps the planner returned first.
+ """
+ result = await session.execute(
+ select(Message).where(Message.room_id == room_id).order_by(Message.seq).limit(1)
+ )
+ return result.scalars().first()
+
+
+async def _recorded_since(
+ session: AsyncSession, room_id: str, since: datetime
+) -> dict[str, Message]:
+ result = await session.execute(
+ select(Message)
+ .where(Message.room_id == room_id, Message.sent_at >= since)
+ .order_by(Message.seq)
+ )
+ return {row.transport_event_id: row for row in result.scalars().all()}
+
+
+async def _read_back_to(
+ transport: MessageTransport,
+ matrix_room_id: str,
+ *,
+ anchor_event_id: str | None,
+ floor_ms: int,
+ window_start_ms: int,
+ joins_from_ms: int | None,
+ join_anchor_id: str | None,
+) -> tuple[dict[str, InboundEvent], dict[str, int], bool]:
+ """Page backwards until the window is covered.
+
+ Stops on `anchor_event_id` — the oldest recorded row's own event — which
+ puts the boundary on an identity rather than on two clocks that disagree
+ by however long a write takes. `floor_ms` only ends a walk that never
+ finds it, and the third return value says which of the two happened.
+
+ Unbounded within those limits on purpose, unlike the read path: a
+ reconciliation that gave up after a page budget would report the events it
+ never looked at as agreeing, which is the one answer it must never give.
+ """
+ events: dict[str, InboundEvent] = {}
+ ignored: dict[str, int] = {}
+ start: str | None = None
+ anchored = False
+ done = False
+ while not done:
+ page = await transport.read_history(
+ matrix_room_id, start=start, limit=PAGE_SIZE
+ )
+ for raw in page.events:
+ if not isinstance(raw, InboundEvent):
+ ignored["unrecognised"] = ignored.get("unrecognised", 0) + 1
+ continue
+ # History comes back newest first, so reaching either limit is the
+ # end of the walk rather than an event to skip past.
+ if raw.timestamp < floor_ms:
+ done = True
+ break
+ is_anchor = raw.event_id == anchor_event_id
+ # The anchor is the one event admitted from before the window: its
+ # row's `sent_at` is by construction later than it.
+ if raw.timestamp >= window_start_ms or is_anchor:
+ _classify(raw, events, ignored, joins_from_ms, join_anchor_id)
+ elif anchor_event_id is None:
+ done = True
+ break
+ if is_anchor:
+ anchored = True
+ done = True
+ break
+ if done:
+ break
+ end = page.next_token
+ if not end or end == start:
+ break
+ start = end
+ return events, ignored, anchored or anchor_event_id is None
+
+
+def _classify(
+ raw: InboundEvent,
+ events: dict[str, InboundEvent],
+ ignored: dict[str, int],
+ joins_from_ms: int | None,
+ join_anchor_id: str | None,
+) -> None:
+ """Sort one bus event into the comparison set or the ignored tally."""
+ if isinstance(raw, InboundCustomEvent) and not should_record(raw.event_type):
+ ignored[raw.event_type] = ignored.get(raw.event_type, 0) + 1
+ elif isinstance(raw, InboundMessage | InboundCustomEvent):
+ events[raw.event_id] = raw
+ elif isinstance(raw, InboundMembership):
+ _classify_membership(raw, events, ignored, joins_from_ms, join_anchor_id)
+ else:
+ name = type(raw).__name__
+ ignored[name] = ignored.get(name, 0) + 1
+
+
+def _classify_membership(
+ raw: InboundMembership,
+ events: dict[str, InboundEvent],
+ ignored: dict[str, int],
+ joins_from_ms: int | None,
+ join_anchor_id: str | None,
+) -> None:
+ """An arrival is comparable; anything else membership does is not.
+
+ Only a transition into membership is recorded, so an invite, a leave and a
+ profile change re-firing as a join all belong in the tally. So does a join
+ from before the log held any arrival at all.
+ """
+ arrived = raw.membership == "join" and raw.prev_membership != "join"
+ in_log_window = joins_from_ms is not None and (
+ raw.timestamp >= joins_from_ms or raw.event_id == join_anchor_id
+ )
+ if arrived and in_log_window:
+ events[raw.event_id] = raw
+ return
+ label = (
+ f"{MEMBERSHIP_EVENT_TYPE} (before arrivals were recorded)"
+ if arrived
+ else MEMBERSHIP_EVENT_TYPE
+ )
+ ignored[label] = ignored.get(label, 0) + 1
+
+
+def _compare(event_id: str, event: InboundEvent, row: Message) -> list[Mismatch]:
+ """Compare the fields a reader will depend on once the read path moves.
+
+ Not the whole content dict: the bus is free to hand back an event
+ annotated with fields it added itself, and reporting those as drift would
+ train everyone to ignore the report.
+ """
+ if isinstance(event, InboundMembership):
+ # The row is about the member who arrived, which is `state_key`; the
+ # sender of a membership event can be whoever admitted them.
+ return _mismatches(
+ event_id,
+ [
+ ("member", event.state_key, row.sender_matrix_id),
+ ("event_type", MEMBERSHIP_EVENT_TYPE, row.event_type),
+ ],
+ )
+
+ expected: list[tuple[str, object, object]] = [
+ ("sender", event.sender, row.sender_matrix_id),
+ ]
+ if isinstance(event, InboundCustomEvent):
+ expected.append(("event_type", event.event_type, row.event_type))
+ expected.append(("thread_root", event.thread_root_id, row.thread_root_event_id))
+ elif isinstance(event, InboundMessage):
+ expected.append(("event_type", "m.room.message", row.event_type))
+ expected.append(("body", event.body, row.body))
+ expected.append(("msgtype", event.msgtype, row.msgtype))
+ expected.append(("thread_root", event.thread_root_id, row.thread_root_event_id))
+ if isinstance(event, InboundMedia):
+ expected.append(("uri", event.uri, row.content.get("url")))
+
+ return _mismatches(event_id, expected)
+
+
+def _mismatches(
+ event_id: str, expected: list[tuple[str, object, object]]
+) -> list[Mismatch]:
+ return [
+ Mismatch(
+ event_id=event_id,
+ field_name=name,
+ on_the_bus=on_the_bus,
+ recorded=recorded,
+ )
+ for name, on_the_bus, recorded in expected
+ if on_the_bus != recorded
+ ]
diff --git a/core/switch_core/messages/recorded_types.py b/core/switch_core/messages/recorded_types.py
new file mode 100644
index 000000000..0ab7bffd5
--- /dev/null
+++ b/core/switch_core/messages/recorded_types.py
@@ -0,0 +1,82 @@
+"""Which sent events belong in the message log.
+
+The log and the bus are two different things. The bus carries everything a
+running system says to itself — a typing indicator, an RPC request, a task
+transition. The log is the conversation: what a person reading the room later
+would expect to find there. Only the second belongs in `messages`.
+
+This is a denylist rather than an allowlist on purpose. A type nobody
+classified is recorded, which costs a row; an allowlist would drop it, and a
+missing message the read path never knows to look for is the worse failure by
+far. `test_recorded_types.py` walks the dispatch table and fails on anything
+unclassified, so the denylist stays honest without the log going quiet.
+"""
+
+from __future__ import annotations
+
+# An arrival. Not a send, so it never reaches `should_record` — the recorder
+# has its own entry point for it — but the read path needs the name to tell an
+# arrival from something someone said.
+MEMBERSHIP_EVENT_TYPE = "m.room.member"
+
+# Ephemeral: presence-like state, superseded by the next one, null body.
+EPHEMERAL = frozenset({"com.switch.agent.runtime_state"})
+
+# Already durable in the `tasks` table, which is the record readers query.
+PERSISTED_ELSEWHERE = frozenset(
+ {
+ "com.switch.task.delegate",
+ "com.switch.task.accept",
+ "com.switch.task.update",
+ "com.switch.task.finalise",
+ "com.switch.task.cancel",
+ }
+)
+
+# Measurements of a run, not utterances in a room. If these are worth keeping
+# they want a table shaped for querying them, not the conversation log.
+TELEMETRY = frozenset({"com.switch.report.tool_call", "com.switch.report.llm_call"})
+
+# Types no code sends any more. The bus keeps its history forever, so events of
+# a retired type stay readable long after the last line that could produce one
+# was deleted — and anything walking that history has to be able to say what
+# they were. Without this, deleting a type turns every historical event of it
+# into an unclassified event that should have been recorded, which reconcile
+# reports as a missing row for good.
+#
+# APPEND ONLY. A name leaves this set only if the type is revived, in which
+# case it belongs in one of the categories above instead.
+RETIRED = frozenset(
+ {
+ # Deleted with the RPC round trips, which were switch-core talking to
+ # itself over the bus.
+ "com.switch.mediation.tool_request",
+ "com.switch.mediation.tool_result",
+ "com.switch.mediation.llm_request",
+ "com.switch.mediation.llm_response",
+ "com.switch.resource.load_request",
+ "com.switch.resource.load_response",
+ "com.switch.resource.room_document_create_request",
+ "com.switch.resource.room_document_create_response",
+ "com.switch.resource.room_document_update_request",
+ "com.switch.resource.room_document_update_response",
+ "com.switch.resource.room_document_delete_request",
+ "com.switch.resource.room_document_delete_response",
+ # Deleted as dead since the initial import.
+ "com.switch.permission.request",
+ "com.switch.permission.response",
+ }
+)
+
+NOT_RECORDED = EPHEMERAL | PERSISTED_ELSEWHERE | TELEMETRY | RETIRED
+
+# The observe prefix is reserved and unimplemented; no type under it exists to
+# name individually yet.
+NOT_RECORDED_PREFIXES = ("com.switch.observe.",)
+
+
+def should_record(event_type: str) -> bool:
+ """Whether an event of this type belongs in the message log."""
+ if event_type in NOT_RECORDED:
+ return False
+ return not event_type.startswith(NOT_RECORDED_PREFIXES)
diff --git a/core/switch_core/messages/recorder.py b/core/switch_core/messages/recorder.py
new file mode 100644
index 000000000..892d89ce1
--- /dev/null
+++ b/core/switch_core/messages/recorder.py
@@ -0,0 +1,214 @@
+"""Records into Postgres what was sent over the transport.
+
+The transport remains the source of truth for history; these rows are a
+parallel record that a later change reads from instead. Recording happens
+after the send has been accepted, so the database never delays or blocks
+delivery.
+
+That ordering has a consequence worth stating rather than hiding: a failure
+here leaves a row missing for a message that was really delivered. The
+alternative — failing the send because the database is unhappy — would make
+messaging less reliable than it is today, which is not a trade this step is
+willing to make. Failures are logged at error, never swallowed silently, and
+reconciling the two records is part of moving the read path over.
+
+What gets a row is decided in `recorded_types`: the conversation, not every
+event that crosses the bus.
+
+Arrivals are the exception to "record what you send". A join is not a send, but
+it is part of the timeline a reader expects — history shows who appeared and
+when. It is recorded by the arriving client about itself, which keeps the
+one-row-per-event property the send path gets for free: exactly one Switch
+client owns each participant, so exactly one of them records the arrival.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from switch_core.db.models import Message
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.db.stores.room_store import RoomStore
+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPE, should_record
+from switch_core.messages.row import attachments_in, text_field, thread_root_of
+
+if TYPE_CHECKING:
+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+ from switch_core.transport import InboundMembership, SendResult
+
+logger = logging.getLogger(__name__)
+
+
+class MessageRecorder:
+ def __init__(
+ self,
+ *,
+ session_factory: async_sessionmaker[AsyncSession],
+ room_store: RoomStore,
+ message_store: MessageStore,
+ ) -> None:
+ self._session_factory = session_factory
+ self._room_store = room_store
+ self._message_store = message_store
+ # A room's transport id never changes, so this only ever grows and
+ # never goes stale.
+ self._room_ids: dict[str, str] = {}
+
+ async def record(
+ self,
+ *,
+ transport_room_id: str,
+ result: SendResult,
+ sender_matrix_id: str,
+ sender_client_id: str,
+ sender_name: str,
+ ) -> None:
+ if not should_record(result.event_type):
+ return
+ try:
+ await self._record(
+ transport_room_id=transport_room_id,
+ result=result,
+ sender_matrix_id=sender_matrix_id,
+ sender_client_id=sender_client_id,
+ sender_name=sender_name,
+ )
+ except Exception:
+ logger.error(
+ "Delivered %s to %s but failed to record it as %s",
+ result.event_type,
+ transport_room_id,
+ result.event_id,
+ exc_info=True,
+ )
+
+ async def record_join(
+ self,
+ *,
+ transport_room_id: str,
+ event: InboundMembership,
+ client_id: str,
+ member_name: str,
+ ) -> None:
+ """Record an arrival, called by the client that arrived.
+
+ `member_name` is the arriving client's own name rather than the
+ display name on the membership event: the profile behind that name is
+ set from whatever the source platform calls the member, so taking it
+ would make the same participant read one way when they arrive and
+ another way when they speak.
+
+ Like `record`, a failure here leaves a gap rather than disturbing
+ anything: nothing about a join depends on it having been written.
+ """
+ try:
+ await self._record_join(
+ transport_room_id=transport_room_id,
+ event=event,
+ client_id=client_id,
+ member_name=member_name,
+ )
+ except Exception:
+ logger.error(
+ "Joined %s but failed to record the arrival as %s",
+ transport_room_id,
+ event.event_id,
+ exc_info=True,
+ )
+
+ async def _record_join(
+ self,
+ *,
+ transport_room_id: str,
+ event: InboundMembership,
+ client_id: str,
+ member_name: str,
+ ) -> None:
+ async with self._session_factory() as session:
+ room_id = await self._resolve_room(session, transport_room_id)
+ if room_id is None:
+ logger.warning(
+ "Not recording %s: %s is not a Switch room",
+ event.event_id,
+ transport_room_id,
+ )
+ return
+
+ # A join can be observed twice — a redelivered sync, a restart that
+ # re-reads the same member event — and the second one is not a
+ # second arrival. The unique constraint on `transport_event_id` is
+ # the backstop; this keeps the ordinary case off the error log.
+ existing = await self._message_store.get_by_transport_event_id(
+ session, event.event_id
+ )
+ if existing is not None:
+ return
+
+ # No body: what an arrival reads as is the reader's to phrase, and
+ # a rendered sentence in the log would freeze today's wording into
+ # every row ever written.
+ message = Message(
+ room_id=room_id,
+ transport_event_id=event.event_id,
+ sender_matrix_id=event.state_key,
+ sender_client_id=client_id,
+ sender_name=member_name,
+ event_type=MEMBERSHIP_EVENT_TYPE,
+ msgtype=None,
+ body=None,
+ formatted_body=None,
+ thread_root_event_id=None,
+ content=dict(event.content),
+ )
+ await self._message_store.create(session, message, [])
+ await session.commit()
+
+ async def _record(
+ self,
+ *,
+ transport_room_id: str,
+ result: SendResult,
+ sender_matrix_id: str,
+ sender_client_id: str,
+ sender_name: str,
+ ) -> None:
+ async with self._session_factory() as session:
+ room_id = await self._resolve_room(session, transport_room_id)
+ if room_id is None:
+ logger.warning(
+ "Not recording %s: %s is not a Switch room",
+ result.event_id,
+ transport_room_id,
+ )
+ return
+
+ content = result.content
+ message = Message(
+ room_id=room_id,
+ transport_event_id=result.event_id,
+ sender_matrix_id=sender_matrix_id,
+ sender_client_id=sender_client_id,
+ sender_name=sender_name,
+ event_type=result.event_type,
+ msgtype=text_field(content.get("msgtype")),
+ body=text_field(content.get("body")),
+ formatted_body=text_field(content.get("formatted_body")),
+ thread_root_event_id=thread_root_of(content),
+ content=content,
+ )
+ await self._message_store.create(session, message, attachments_in(content))
+ await session.commit()
+
+ async def _resolve_room(
+ self, session: AsyncSession, transport_room_id: str
+ ) -> str | None:
+ cached = self._room_ids.get(transport_room_id)
+ if cached is not None:
+ return cached
+ room = await self._room_store.get_by_matrix_room_id(session, transport_room_id)
+ if room is None:
+ return None
+ self._room_ids[transport_room_id] = room.id
+ return room.id
diff --git a/core/switch_core/messages/recording.py b/core/switch_core/messages/recording.py
new file mode 100644
index 000000000..508f86faa
--- /dev/null
+++ b/core/switch_core/messages/recording.py
@@ -0,0 +1,75 @@
+"""Whether a client has to write down what it sent.
+
+Recording exists because the bus was the delivery and the table was a copy.
+When the table *is* the delivery there is nothing to copy, and a client that
+recorded anyway would write every message twice.
+
+So which recorder a client gets is chosen with its transport, by the same
+factory, and the pairing is the invariant: a transport that stores what it
+carries takes `NoRecording`, and one that does not takes `MessageRecorder`.
+Getting the pair wrong is visible immediately — duplicate rows one way, a
+silent log the other — which is the argument for making it one decision in one
+place rather than a flag each side reads.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+ from switch_core.transport import InboundMembership, SendResult
+
+
+@runtime_checkable
+class MessageRecording(Protocol):
+ """Writes the message log, or knows that something else already did."""
+
+ async def record(
+ self,
+ *,
+ transport_room_id: str,
+ result: SendResult,
+ sender_matrix_id: str,
+ sender_client_id: str,
+ sender_name: str,
+ ) -> None: ...
+
+ async def record_join(
+ self,
+ *,
+ transport_room_id: str,
+ event: InboundMembership,
+ client_id: str,
+ member_name: str,
+ ) -> None: ...
+
+
+class NoRecording:
+ """For a transport whose own write is the record.
+
+ Not a disabled feature: the rows still exist, and are still exactly one per
+ event. They are written by the transport, in the same transaction that
+ accepted the send, which is stronger than what this replaces — the
+ recorder ran after delivery and could leave a gap.
+ """
+
+ async def record(
+ self,
+ *,
+ transport_room_id: str,
+ result: SendResult,
+ sender_matrix_id: str,
+ sender_client_id: str,
+ sender_name: str,
+ ) -> None:
+ return None
+
+ async def record_join(
+ self,
+ *,
+ transport_room_id: str,
+ event: InboundMembership,
+ client_id: str,
+ member_name: str,
+ ) -> None:
+ return None
diff --git a/core/switch_core/messages/row.py b/core/switch_core/messages/row.py
new file mode 100644
index 000000000..4252a9d9d
--- /dev/null
+++ b/core/switch_core/messages/row.py
@@ -0,0 +1,48 @@
+"""How an event's content becomes the columns beside it.
+
+`messages` keeps the whole event in `content` and denormalises a few fields out
+of it for querying. Which fields, and how they are read out, is one rule — the
+writer and anything reconstructing a row from history have to agree on it, or
+the same event stored twice would be two different rows.
+"""
+
+from __future__ import annotations
+
+from switch_core.db.models import MessageAttachment
+
+
+def text_field(value: object) -> str | None:
+ return value if isinstance(value, str) else None
+
+
+def thread_root_of(content: dict[str, object]) -> str | None:
+ relation = content.get("m.relates_to")
+ if not isinstance(relation, dict) or relation.get("rel_type") != "m.thread":
+ return None
+ return text_field(relation.get("event_id"))
+
+
+def attachments_in(content: dict[str, object]) -> list[MessageAttachment]:
+ """A media event carries exactly one file.
+
+ A message with several files is sent as one event per file sharing a group
+ id, so each of those events records a single attachment. The column exists
+ as a list because reassembling the group is the reader's job, not the
+ writer's.
+ """
+ uri = text_field(content.get("url"))
+ if uri is None:
+ return []
+ info = content.get("info")
+ info = info if isinstance(info, dict) else {}
+ size = info.get("size")
+ return [
+ MessageAttachment(
+ uri=uri,
+ filename=text_field(content.get("filename"))
+ or text_field(content.get("body")),
+ mimetype=text_field(info.get("mimetype")),
+ size=size if isinstance(size, int) else None,
+ position=0,
+ )
+ ]
diff --git a/core/switch_core/migrations/versions/a1d7f3c95b60_media_blobs.py b/core/switch_core/migrations/versions/a1d7f3c95b60_media_blobs.py
new file mode 100644
index 000000000..def43b269
--- /dev/null
+++ b/core/switch_core/migrations/versions/a1d7f3c95b60_media_blobs.py
@@ -0,0 +1,39 @@
+"""media blobs
+
+Where an attachment's bytes live once the homeserver is not there to hold
+them. Nothing reads this table until the Postgres transport is the one in use,
+so applying it early is free and keeps the flip to a restart.
+
+Revision ID: a1d7f3c95b60
+Revises: f4c2a8e6d193
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "a1d7f3c95b60"
+down_revision = "f4c2a8e6d193"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+ op.create_table(
+ "media_blobs",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column("uri", sa.Text(), nullable=False, unique=True),
+ sa.Column("content_type", sa.Text(), nullable=True),
+ sa.Column("filename", sa.Text(), nullable=True),
+ sa.Column("size", sa.BigInteger(), nullable=False),
+ sa.Column("data", sa.LargeBinary(), nullable=False),
+ sa.Column(
+ "created_at",
+ sa.DateTime(timezone=True),
+ server_default=sa.func.now(),
+ nullable=False,
+ ),
+ )
+
+
+def downgrade() -> None:
+ op.drop_table("media_blobs")
diff --git a/core/switch_core/migrations/versions/a3f7c91b8e24_messages_and_attachments.py b/core/switch_core/migrations/versions/a3f7c91b8e24_messages_and_attachments.py
new file mode 100644
index 000000000..bbcc4d53c
--- /dev/null
+++ b/core/switch_core/migrations/versions/a3f7c91b8e24_messages_and_attachments.py
@@ -0,0 +1,100 @@
+"""messages and message attachments
+
+A parallel record of every message sent into a room, written alongside the
+send. Nothing reads these tables yet; the read path moves onto them in a
+later change.
+
+Revision ID: a3f7c91b8e24
+Revises: c81f4a06d2b7
+Create Date: 2026-09-03 21:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision: str = "a3f7c91b8e24"
+down_revision: str | None = "c81f4a06d2b7"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.create_table(
+ "messages",
+ sa.Column("id", sa.Text(), primary_key=True, nullable=False),
+ sa.Column(
+ "seq",
+ sa.BigInteger(),
+ sa.Identity(always=True),
+ unique=True,
+ nullable=False,
+ ),
+ sa.Column(
+ "room_id",
+ sa.Text(),
+ sa.ForeignKey("rooms.id", ondelete="CASCADE"),
+ nullable=False,
+ ),
+ sa.Column("transport_event_id", sa.Text(), unique=True, nullable=False),
+ sa.Column("sender_matrix_id", sa.Text(), nullable=False),
+ sa.Column(
+ "sender_client_id",
+ sa.Text(),
+ sa.ForeignKey("clients.id", ondelete="SET NULL"),
+ nullable=True,
+ ),
+ sa.Column("sender_name", sa.Text(), nullable=True),
+ sa.Column("event_type", sa.Text(), nullable=False),
+ sa.Column("msgtype", sa.Text(), nullable=True),
+ sa.Column("body", sa.Text(), nullable=True),
+ sa.Column("formatted_body", sa.Text(), nullable=True),
+ sa.Column("thread_root_event_id", sa.Text(), nullable=True),
+ sa.Column("content", JSONB(), nullable=False),
+ sa.Column(
+ "sent_at",
+ sa.DateTime(timezone=True),
+ server_default=sa.func.now(),
+ nullable=False,
+ ),
+ )
+ op.create_index("ix_messages_room_seq", "messages", ["room_id", "seq"])
+ op.create_index(
+ "ix_messages_thread_root",
+ "messages",
+ ["room_id", "thread_root_event_id"],
+ postgresql_where=sa.text("thread_root_event_id IS NOT NULL"),
+ )
+
+ op.create_table(
+ "message_attachments",
+ sa.Column("id", sa.Text(), primary_key=True, nullable=False),
+ sa.Column(
+ "message_id",
+ sa.Text(),
+ sa.ForeignKey("messages.id", ondelete="CASCADE"),
+ nullable=False,
+ ),
+ sa.Column("position", sa.Integer(), nullable=False),
+ sa.Column("uri", sa.Text(), nullable=False),
+ sa.Column("filename", sa.Text(), nullable=True),
+ sa.Column("mimetype", sa.Text(), nullable=True),
+ sa.Column("size", sa.BigInteger(), nullable=True),
+ sa.Column(
+ "created_at",
+ sa.DateTime(timezone=True),
+ server_default=sa.func.now(),
+ nullable=False,
+ ),
+ )
+ op.create_index(
+ "ix_message_attachments_message", "message_attachments", ["message_id"]
+ )
+
+
+def downgrade() -> None:
+ op.drop_table("message_attachments")
+ op.drop_table("messages")
diff --git a/core/switch_core/migrations/versions/b5d2e08c17af_message_seq_per_room.py b/core/switch_core/migrations/versions/b5d2e08c17af_message_seq_per_room.py
new file mode 100644
index 000000000..0fdae387c
--- /dev/null
+++ b/core/switch_core/migrations/versions/b5d2e08c17af_message_seq_per_room.py
@@ -0,0 +1,79 @@
+"""number messages per room, in commit order
+
+`seq` was a global identity column. A sequence allocates when a statement
+runs, not when it commits, so a row could commit behind one with a higher
+number and a cursor paging on `seq > n` would step over it permanently. The
+column is now assigned per room by the store under an advisory lock, which
+makes sequence order and commit order the same order.
+
+Existing rows are renumbered by their old global order, which preserves the
+order they were written in.
+
+Revision ID: b5d2e08c17af
+Revises: a3f7c91b8e24
+Create Date: 2026-09-03 23:30:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "b5d2e08c17af"
+down_revision: str | None = "a3f7c91b8e24"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ # The identity has to go before the values can be rewritten: an
+ # `always` identity rejects a plain UPDATE.
+ op.execute("ALTER TABLE messages ALTER COLUMN seq DROP IDENTITY IF EXISTS")
+ op.drop_constraint("messages_seq_key", "messages", type_="unique")
+ op.drop_index("ix_messages_room_seq", table_name="messages")
+ op.execute(
+ """
+ UPDATE messages AS m
+ SET seq = renumbered.position
+ FROM (
+ SELECT id, row_number() OVER (PARTITION BY room_id ORDER BY seq)
+ AS position
+ FROM messages
+ ) AS renumbered
+ WHERE m.id = renumbered.id
+ """
+ )
+ op.create_unique_constraint("uq_messages_room_seq", "messages", ["room_id", "seq"])
+
+
+def downgrade() -> None:
+ op.drop_constraint("uq_messages_room_seq", "messages", type_="unique")
+ # Per-room numbers collide across rooms, so a global identity cannot be
+ # restored over them. Renumber globally by the order rows were sent in.
+ op.execute(
+ """
+ UPDATE messages AS m
+ SET seq = renumbered.position
+ FROM (
+ SELECT id, row_number() OVER (ORDER BY sent_at, room_id, seq)
+ AS position
+ FROM messages
+ ) AS renumbered
+ WHERE m.id = renumbered.id
+ """
+ )
+ op.create_index("ix_messages_room_seq", "messages", ["room_id", "seq"])
+ op.create_unique_constraint("messages_seq_key", "messages", ["seq"])
+ op.execute(
+ "ALTER TABLE messages ALTER COLUMN seq "
+ "ADD GENERATED ALWAYS AS IDENTITY (START WITH 1)"
+ )
+ op.execute(
+ sa.text(
+ "SELECT setval("
+ " pg_get_serial_sequence('messages', 'seq'),"
+ " coalesce((SELECT max(seq) FROM messages), 1)"
+ ")"
+ )
+ )
diff --git a/core/switch_core/migrations/versions/b6d1f04ae932_rooms_history_backfilled_at.py b/core/switch_core/migrations/versions/b6d1f04ae932_rooms_history_backfilled_at.py
new file mode 100644
index 000000000..16e00001c
--- /dev/null
+++ b/core/switch_core/migrations/versions/b6d1f04ae932_rooms_history_backfilled_at.py
@@ -0,0 +1,36 @@
+"""record when a room's history has been reconstructed
+
+Revision ID: b6d1f04ae932
+Revises: a1d7f3c95b60
+
+The backfill always walks from a room's newest message towards its start, so
+it cannot tell from the rows alone that it has already finished — a second run
+reads every page of every room again to discover it has nothing to write. On a
+deployment where the backfill runs unattended at startup, that is the whole
+history re-read on every boot.
+
+Null means never completed, which deliberately includes a walk that stopped at
+the page limit: that room is only partly reconstructed, and treating it as done
+would strand the rest.
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "b6d1f04ae932"
+down_revision: str | Sequence[str] | None = "a1d7f3c95b60"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.add_column(
+ "rooms",
+ sa.Column("history_backfilled_at", sa.DateTime(timezone=True), nullable=True),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("rooms", "history_backfilled_at")
diff --git a/core/switch_core/migrations/versions/c71a4f9d2b83_message_sent_at_index.py b/core/switch_core/migrations/versions/c71a4f9d2b83_message_sent_at_index.py
new file mode 100644
index 000000000..e2d718132
--- /dev/null
+++ b/core/switch_core/migrations/versions/c71a4f9d2b83_message_sent_at_index.py
@@ -0,0 +1,28 @@
+"""index messages by room and sent_at
+
+The read path filters history by time window and orders it by `seq`. `seq`
+already has an index through the room uniqueness constraint; `sent_at` had
+none, so a windowed read had to scan the room.
+
+Revision ID: c71a4f9d2b83
+Revises: b5d2e08c17af
+Create Date: 2026-09-03 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "c71a4f9d2b83"
+down_revision: str | None = "b5d2e08c17af"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.create_index("ix_messages_room_sent_at", "messages", ["room_id", "sent_at"])
+
+
+def downgrade() -> None:
+ op.drop_index("ix_messages_room_sent_at", table_name="messages")
diff --git a/core/switch_core/migrations/versions/d4e17b90c3a5_message_notify_and_cursors.py b/core/switch_core/migrations/versions/d4e17b90c3a5_message_notify_and_cursors.py
new file mode 100644
index 000000000..7260b7121
--- /dev/null
+++ b/core/switch_core/migrations/versions/d4e17b90c3a5_message_notify_and_cursors.py
@@ -0,0 +1,83 @@
+"""announce new messages, and remember how far each agent has been delivered
+
+The trigger makes an insert into `messages` announce itself on commit, so
+delivery can be driven by the table rather than by a live bus connection. The
+payload is a hint — room, position, row id — and consumers read the row, which
+is what keeps a lost notification a latency problem rather than a data one.
+
+`delivery_cursors` persists what the event buffer held in memory, so an agent's
+position outlives the process that was serving it.
+
+The DDL below is a verbatim copy of `switch_core/db/notify_ddl.py` as it stood
+when this migration was written. It is copied rather than imported on purpose:
+a migration is a record of a change that already happened, and importing the
+live module would make an old migration mean something new.
+
+Revision ID: d4e17b90c3a5
+Revises: c71a4f9d2b83
+Create Date: 2026-09-03 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "d4e17b90c3a5"
+down_revision: str | None = "c71a4f9d2b83"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+CREATE_NOTIFY_FUNCTION = """
+CREATE OR REPLACE FUNCTION switch_notify_message() RETURNS trigger AS $$
+BEGIN
+ PERFORM pg_notify(
+ 'switch_message',
+ json_build_object(
+ 'room_id', NEW.room_id,
+ 'seq', NEW.seq,
+ 'id', NEW.id
+ )::text
+ );
+ RETURN NULL;
+END;
+$$ LANGUAGE plpgsql
+"""
+
+CREATE_NOTIFY_TRIGGER = """
+CREATE TRIGGER messages_notify
+ AFTER INSERT ON messages
+ FOR EACH ROW EXECUTE FUNCTION switch_notify_message()
+"""
+
+
+def upgrade() -> None:
+ op.execute(CREATE_NOTIFY_FUNCTION)
+ op.execute(CREATE_NOTIFY_TRIGGER)
+
+ op.create_table(
+ "delivery_cursors",
+ sa.Column("id", sa.Text(), nullable=False),
+ sa.Column("agent_id", sa.Text(), nullable=False),
+ sa.Column("room_id", sa.Text(), nullable=False),
+ sa.Column("last_seq", sa.BigInteger(), nullable=False),
+ sa.Column(
+ "updated_at",
+ sa.DateTime(timezone=True),
+ server_default=sa.text("now()"),
+ nullable=False,
+ ),
+ sa.ForeignKeyConstraint(["agent_id"], ["agents.id"], ondelete="CASCADE"),
+ sa.ForeignKeyConstraint(["room_id"], ["rooms.id"], ondelete="CASCADE"),
+ sa.PrimaryKeyConstraint("id"),
+ sa.UniqueConstraint(
+ "agent_id", "room_id", name="uq_delivery_cursors_agent_room"
+ ),
+ )
+
+
+def downgrade() -> None:
+ op.drop_table("delivery_cursors")
+ op.execute("DROP TRIGGER IF EXISTS messages_notify ON messages")
+ op.execute("DROP FUNCTION IF EXISTS switch_notify_message()")
diff --git a/core/switch_core/migrations/versions/e83c5a17f4d2_backfill_seq_and_cursors.py b/core/switch_core/migrations/versions/e83c5a17f4d2_backfill_seq_and_cursors.py
new file mode 100644
index 000000000..1e7594499
--- /dev/null
+++ b/core/switch_core/migrations/versions/e83c5a17f4d2_backfill_seq_and_cursors.py
@@ -0,0 +1,66 @@
+"""do not announce reconstructed history
+
+Backfilled messages are numbered below zero — positive is what Switch recorded
+as it happened, negative is what was reconstructed from the bus afterwards.
+Announcing them would wake every subscriber in the room to read nothing, since
+a delivery cursor starts at 0 and is above these positions by construction.
+
+Replaces the trigger function in place; the trigger itself is unchanged.
+
+Revision ID: e83c5a17f4d2
+Revises: d4e17b90c3a5
+Create Date: 2026-09-03 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "e83c5a17f4d2"
+down_revision: str | None = "d4e17b90c3a5"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+WITH_BACKFILL_GUARD = """
+CREATE OR REPLACE FUNCTION switch_notify_message() RETURNS trigger AS $$
+BEGIN
+ IF NEW.seq <= 0 THEN
+ RETURN NULL;
+ END IF;
+ PERFORM pg_notify(
+ 'switch_message',
+ json_build_object(
+ 'room_id', NEW.room_id,
+ 'seq', NEW.seq,
+ 'id', NEW.id
+ )::text
+ );
+ RETURN NULL;
+END;
+$$ LANGUAGE plpgsql
+"""
+
+WITHOUT_BACKFILL_GUARD = """
+CREATE OR REPLACE FUNCTION switch_notify_message() RETURNS trigger AS $$
+BEGIN
+ PERFORM pg_notify(
+ 'switch_message',
+ json_build_object(
+ 'room_id', NEW.room_id,
+ 'seq', NEW.seq,
+ 'id', NEW.id
+ )::text
+ );
+ RETURN NULL;
+END;
+$$ LANGUAGE plpgsql
+"""
+
+
+def upgrade() -> None:
+ op.execute(WITH_BACKFILL_GUARD)
+
+
+def downgrade() -> None:
+ op.execute(WITHOUT_BACKFILL_GUARD)
diff --git a/core/switch_core/migrations/versions/f4c2a8e6d193_drop_resource_manager_client.py b/core/switch_core/migrations/versions/f4c2a8e6d193_drop_resource_manager_client.py
new file mode 100644
index 000000000..6e8ed8486
--- /dev/null
+++ b/core/switch_core/migrations/versions/f4c2a8e6d193_drop_resource_manager_client.py
@@ -0,0 +1,42 @@
+"""remove the resource manager client record
+
+The resource manager stopped being a Matrix client when the four resource
+operations became direct calls on `resource_service`. Nothing registers the
+type any more, so a leftover row makes `ClientFactory.create` raise
+`Unknown client type: 'resource_manager'` and takes the whole startup with it.
+
+The Matrix account itself is left alone: this migration owns the Switch
+database, not the homeserver, and an account nobody logs into costs nothing.
+
+Revision ID: f4c2a8e6d193
+Revises: e83c5a17f4d2
+Create Date: 2026-09-04 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "f4c2a8e6d193"
+down_revision: str | None = "e83c5a17f4d2"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.execute(
+ """
+ DELETE FROM client_rooms
+ WHERE client_id IN (SELECT id FROM clients WHERE type = 'resource_manager')
+ """
+ )
+ op.execute("DELETE FROM clients WHERE type = 'resource_manager'")
+
+
+def downgrade() -> None:
+ """Not reversible.
+
+ The row carried a Matrix password and access token that are not recoverable
+ from anything left behind, and no code path reads the type any more.
+ """
diff --git a/core/switch_core/provisioning/__init__.py b/core/switch_core/provisioning/__init__.py
new file mode 100644
index 000000000..c1ad6a7a8
--- /dev/null
+++ b/core/switch_core/provisioning/__init__.py
@@ -0,0 +1,8 @@
+"""Provisioning for Switch: accounts, rooms and membership.
+
+`Provisioning` (in `port`) is the contract; implementations live beside it.
+"""
+
+from switch_core.provisioning.port import Provisioning
+
+__all__ = ["Provisioning"]
diff --git a/core/switch_core/provisioning/port.py b/core/switch_core/provisioning/port.py
new file mode 100644
index 000000000..75d4162a6
--- /dev/null
+++ b/core/switch_core/provisioning/port.py
@@ -0,0 +1,69 @@
+"""The provisioning port: accounts, rooms and membership.
+
+`MessageTransport` covers what a participant does once it exists. This covers
+bringing participants and rooms into existence in the first place — the second
+and last thing switch-core asks a homeserver for. The two are separate ports
+because they are used by different callers at different times: the transport by
+every client for the life of the process, this once per account, room or
+membership change, by room provisioning and the client/bridge lifecycles.
+
+The contract is derived from the call sites, not from the endpoints behind it:
+create an account, create a room, add and remove a member, discard a room, and
+check a password. `verify_login` is the odd one — it exists so a cutover can
+tell an empty target server from one that already has accounts under the same
+names — and it is the operation most likely to have no counterpart in a future
+implementation.
+
+Membership is expressed as invite/kick because that is what the operations
+mean, not because of how a homeserver spells them. An implementation that can
+simply write a row is free to do so; `invite_to_room` promises the user ends up
+in the room, and callers already rely on that rather than on an invitation
+being separately accepted.
+
+Both operations are idempotent by contract: inviting a member who is already
+in, or kicking one who is already out, is success and not an error. Every other
+failure raises.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Provisioning(Protocol):
+ """Creates the accounts and rooms the transport then talks over."""
+
+ async def register_user(
+ self,
+ user_id: str,
+ password: str,
+ display_name: str | None = None,
+ is_admin: bool = False,
+ ) -> None:
+ """Create an account, or do nothing if it already exists."""
+ ...
+
+ async def verify_login(self, user_id: str, password: str) -> bool:
+ """Whether `password` authenticates `user_id`."""
+ ...
+
+ async def create_room(self, name: str, topic: str) -> str:
+ """Create a room and return its transport-side id."""
+ ...
+
+ async def invite_to_room(self, room_id: str, user_id: str) -> None:
+ """Put a user in a room. Already a member is success."""
+ ...
+
+ async def kick_user(self, room_id: str, user_id: str) -> None:
+ """Take a user out of a room. Already out is success."""
+ ...
+
+ async def delete_room(self, room_id: str) -> None:
+ """Discard a room. Callers remove the other members first."""
+ ...
+
+ async def close(self) -> None:
+ """Release whatever the implementation holds open."""
+ ...
diff --git a/core/switch_core/provisioning/postgres.py b/core/switch_core/provisioning/postgres.py
new file mode 100644
index 000000000..880b98098
--- /dev/null
+++ b/core/switch_core/provisioning/postgres.py
@@ -0,0 +1,183 @@
+"""Provisioning without a homeserver: every operation is a row.
+
+What the Matrix implementation did over HTTP, this does against the same
+database Switch already keeps the answer in. Two of the six turn out to be
+almost nothing, and that is the finding rather than a shortcut:
+
+- **An account is the `clients` row.** `register_user` created a homeserver
+ account so that a row Switch was about to write would have something to
+ authenticate as. There is no second system to register with now, so there is
+ nothing to do — the caller writes the row immediately afterwards, and that
+ row is the account.
+- **A password is a Switch password.** `verify_login` asked the homeserver
+ whether a password worked; it asks the `clients` table instead. Its one
+ caller is a cutover check for a target server that already has accounts,
+ which no longer has a homeserver to be true of.
+
+The other four are writes:
+
+- **A room** gets an id minted here and stored by the caller, exactly as the
+ homeserver's `room_id` was.
+- **Membership** is a `client_rooms` row plus the arrival that explains it.
+ Over Matrix an invitation was a durable event a client picked up whenever it
+ next synced; here a live client is woken through the invite bus and joins
+ itself, which is what keeps its transport watching the room. When nobody is
+ live the membership is written directly, because a client that is not
+ running has nothing to wake and will find the room when it starts.
+- **Removal** deletes the membership. No leave event is written: a departure
+ is not something a reader of the room needs explained, and the timeline the
+ log serves is what was said.
+- **Discarding a room** is left to the caller's own delete, which cascades.
+ Nothing here has a second copy to clean up.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import TYPE_CHECKING
+
+from switch_core.db.models import ClientRoom, Message
+
+if TYPE_CHECKING:
+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+ from switch_core.db.stores.client_store import ClientStore
+ from switch_core.db.stores.message_store import MessageStore
+ from switch_core.db.stores.room_store import RoomStore
+ from switch_core.transport.invites import InviteBus
+
+logger = logging.getLogger(__name__)
+
+MEMBERSHIP_EVENT_TYPE = "m.room.member"
+
+
+class ProvisioningError(RuntimeError):
+ """A provisioning operation could not be carried out."""
+
+
+def new_room_id() -> str:
+ """A room's transport-side id.
+
+ Stored in the column that held the homeserver's, and opaque in the same
+ way: the prefix is for a human reading a row during the window where both
+ kinds exist, and no code may branch on it.
+ """
+ return f"sw_room_{uuid.uuid4().hex}"
+
+
+class PostgresProvisioning:
+ """Accounts, rooms and membership as rows in Switch's own database."""
+
+ def __init__(
+ self,
+ *,
+ session_factory: async_sessionmaker[AsyncSession],
+ room_store: RoomStore,
+ client_store: ClientStore,
+ message_store: MessageStore,
+ invites: InviteBus,
+ ) -> None:
+ self._session_factory = session_factory
+ self._room_store = room_store
+ self._client_store = client_store
+ self._message_store = message_store
+ self._invites = invites
+
+ async def register_user(
+ self,
+ user_id: str,
+ password: str,
+ display_name: str | None = None,
+ is_admin: bool = False,
+ ) -> None:
+ """Nothing to register: the caller's `clients` row is the account."""
+
+ async def verify_login(self, user_id: str, password: str) -> bool:
+ async with self._session_factory() as session:
+ client = await self._client_store.get_by_matrix_user_id(session, user_id)
+ return client is not None and client.password == password
+
+ async def create_room(self, name: str, topic: str) -> str:
+ """Mint the id the caller will store on its own room row.
+
+ No row is written here. The room is the caller's to create, and
+ writing a second record of it would be a second thing to keep in step.
+ """
+ return new_room_id()
+
+ async def invite_to_room(self, room_id: str, user_id: str) -> None:
+ """Put a user in a room, waking them if they are running.
+
+ A live client joins itself, which is what leaves its transport
+ watching the room. Already a member is success, per the port.
+
+ The wake-up is rung even when the membership is already recorded, and
+ that is deliberate. A row is no longer proof that a running client is
+ subscribed to the room — something else may have written it, and there
+ is a window at startup where a client is running but not yet on the
+ bus. Returning early on the row would make that state permanent, since
+ every later invitation would find the same row and stop. Membership is
+ what has to be exactly-once; a wake-up is cheap and idempotent.
+ """
+ async with self._session_factory() as session:
+ switch_room_id, client_id, display_name = await self._resolve(
+ session, room_id, user_id
+ )
+ existing = await session.get(
+ ClientRoom, {"client_id": client_id, "room_id": switch_room_id}
+ )
+
+ if await self._invites.invite(user_id, room_id):
+ return
+ if existing is not None:
+ return
+
+ async with self._session_factory() as session:
+ await self._room_store.add_client(session, client_id, switch_room_id)
+ arrival = Message(
+ room_id=switch_room_id,
+ transport_event_id=f"sw_{uuid.uuid4().hex}",
+ sender_matrix_id=user_id,
+ sender_client_id=client_id,
+ sender_name=display_name,
+ event_type=MEMBERSHIP_EVENT_TYPE,
+ msgtype=None,
+ body=None,
+ formatted_body=None,
+ thread_root_event_id=None,
+ content={"membership": "join", "displayname": display_name},
+ )
+ await self._message_store.create(session, arrival, [])
+ await session.commit()
+
+ async def kick_user(self, room_id: str, user_id: str) -> None:
+ """Remove a membership. Already out is success, per the port."""
+ async with self._session_factory() as session:
+ switch_room_id, client_id, _ = await self._resolve(
+ session, room_id, user_id
+ )
+ await self._room_store.remove_client(session, client_id, switch_room_id)
+ await session.commit()
+
+ async def delete_room(self, room_id: str) -> None:
+ """Nothing of its own to discard.
+
+ The caller deletes the room, and its messages and memberships go with
+ it. The Matrix implementation had a second copy of the room to abandon;
+ this has none.
+ """
+
+ async def close(self) -> None:
+ """Nothing held open."""
+
+ async def _resolve(
+ self, session: AsyncSession, transport_room_id: str, user_id: str
+ ) -> tuple[str, str, str]:
+ room = await self._room_store.get_by_matrix_room_id(session, transport_room_id)
+ if room is None:
+ raise ProvisioningError(f"{transport_room_id} is not a Switch room")
+ client = await self._client_store.get_by_matrix_user_id(session, user_id)
+ if client is None:
+ raise ProvisioningError(f"{user_id} is not a Switch client")
+ return room.id, client.id, client.display_name
diff --git a/core/switch_core/room_service.py b/core/switch_core/room_service.py
index 770c15e7f..952b6a780 100644
--- a/core/switch_core/room_service.py
+++ b/core/switch_core/room_service.py
@@ -33,7 +33,7 @@ from switch_core.db.models import Room, RoomGroup, RoomRole
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore
from switch_core.db.stores.room_store import RoomStore
-from switch_core.matrix_admin import MatrixAdmin
+from switch_core.provisioning import Provisioning
if TYPE_CHECKING:
from switch_core.bridges.collaboration.bridge_core import BridgeCore
@@ -43,7 +43,7 @@ if TYPE_CHECKING:
logger = logging.getLogger(__name__)
-SYSTEM_CLIENT_TYPES = ("resource_manager", "observe", "admin")
+SYSTEM_CLIENT_TYPES = ("observe", "admin")
class LinkedRoomSpec(BaseModel):
@@ -127,7 +127,7 @@ class RoomService:
def __init__(
self,
*,
- matrix_admin: MatrixAdmin,
+ matrix_admin: Provisioning,
room_store: RoomStore,
agent_store: AgentStore,
client_lifecycle: ClientLifecycleService,
diff --git a/core/switch_core/transport/__init__.py b/core/switch_core/transport/__init__.py
new file mode 100644
index 000000000..8e1a370af
--- /dev/null
+++ b/core/switch_core/transport/__init__.py
@@ -0,0 +1,52 @@
+"""Message transport for Switch.
+
+`MessageTransport` (in `port`) is the contract; implementations live beside it.
+Only modules inside this package may import a transport library — everything
+else talks to the port and the neutral types in `types`.
+"""
+
+from switch_core.transport.port import (
+ Handler,
+ MessageTransport,
+ SyncErrorHandler,
+ SyncHandler,
+ TransportHandlers,
+)
+from switch_core.transport.types import (
+ DownloadResult,
+ HistoryPage,
+ InboundCustomEvent,
+ InboundEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+ MessageFormat,
+ NotConnectedError,
+ RoomRef,
+ SeekDirection,
+ SendResult,
+ TransportError,
+ UploadResult,
+)
+
+__all__ = [
+ "DownloadResult",
+ "Handler",
+ "HistoryPage",
+ "InboundCustomEvent",
+ "InboundEvent",
+ "InboundMedia",
+ "InboundMembership",
+ "InboundMessage",
+ "MessageFormat",
+ "MessageTransport",
+ "NotConnectedError",
+ "RoomRef",
+ "SeekDirection",
+ "SendResult",
+ "SyncErrorHandler",
+ "SyncHandler",
+ "TransportError",
+ "TransportHandlers",
+ "UploadResult",
+]
diff --git a/core/switch_core/transport/content.py b/core/switch_core/transport/content.py
new file mode 100644
index 000000000..615096eba
--- /dev/null
+++ b/core/switch_core/transport/content.py
@@ -0,0 +1,107 @@
+"""The event bodies Switch sends, assembled once for every transport.
+
+A message's content dict is not Matrix's — it is Switch's own shape, which the
+collaboration bridges, the agent read path and the message log all read. Only
+the delivery of it is a transport's business. Two transports assembling it
+separately would drift, and the drift would show up as a bridge that renders a
+caption on one deployment and a filename on another.
+
+The shapes keep their `m.`-prefixed keys. They are what is in every row already
+written and what three shipped connectors read; renaming them is a protocol
+change, and it is not this module's to make.
+"""
+
+from __future__ import annotations
+
+import markdown
+
+from switch_core.attachments import ATTACHMENT_GROUP_KEY
+from switch_core.transport.types import MessageFormat
+
+
+def thread_relation(thread_root_id: str) -> dict[str, object]:
+ """A pure `m.thread` relation, with no `m.in_reply_to` fallback.
+
+ The root id must already be an actual thread root; mid-thread ids are
+ normalised upstream.
+ """
+ return {"rel_type": "m.thread", "event_id": thread_root_id}
+
+
+def message_content(
+ body: str,
+ *,
+ sender_name: str,
+ format: MessageFormat = "text",
+ mentions: list[str] | None = None,
+ thread_root_id: str | None = None,
+ extra_content: dict[str, object] | None = None,
+) -> dict[str, object]:
+ content: dict[str, object] = {
+ "msgtype": "m.text",
+ "body": body,
+ "sender_name": sender_name,
+ }
+ # Caller-supplied content fields (e.g. a `com.switch.*` marker) are merged
+ # in. They ride on the plain message — the body still renders normally; the
+ # extra keys are metadata other clients can read.
+ if extra_content:
+ content.update(extra_content)
+
+ if format == "markdown":
+ content["format"] = "org.matrix.custom.html"
+ content["formatted_body"] = _rendered(body, mentions)
+
+ if thread_root_id is not None:
+ content["m.relates_to"] = thread_relation(thread_root_id)
+
+ return content
+
+
+def media_content(
+ uri: str,
+ filename: str,
+ mimetype: str,
+ size: int,
+ *,
+ sender_name: str,
+ msgtype: str,
+ caption: str | None = None,
+ thread_root_id: str | None = None,
+ group: dict[str, object] | None = None,
+) -> dict[str, object]:
+ # When a caption is given it becomes the event body, with the real filename
+ # carried separately per the rich-media-caption convention.
+ content: dict[str, object] = {
+ "msgtype": msgtype,
+ "body": caption if caption else filename,
+ "url": uri,
+ "info": {"mimetype": mimetype, "size": size},
+ "sender_name": sender_name,
+ }
+ if caption:
+ content["filename"] = filename
+ if group is not None:
+ content[ATTACHMENT_GROUP_KEY] = group
+ if thread_root_id is not None:
+ content["m.relates_to"] = thread_relation(thread_root_id)
+ return content
+
+
+def _rendered(body: str, mentions: list[str] | None) -> str:
+ """Markdown as HTML, with each mentioned id turned into a link.
+
+ The link target is a matrix.to URL because that is what a Matrix client
+ renders as a mention pill, and it is the one addressing signal with no
+ plain-text equivalent — `AddressingResolver.mentions_name` looks for the
+ id inside the rendered body. A transport with no pill convention of its own
+ still wants the id there for exactly that reason, so the form is shared
+ rather than being made Matrix-only.
+ """
+ html: str = markdown.markdown(body)
+ for user_id in mentions or ():
+ local = user_id.split(":")[0].lstrip("@")
+ html = html.replace(
+ f"@{local}", f'<a href="https://matrix.to/#/{user_id}">{local}</a>'
+ )
+ return html
diff --git a/core/switch_core/transport/ephemeral.py b/core/switch_core/transport/ephemeral.py
new file mode 100644
index 000000000..76dfeb494
--- /dev/null
+++ b/core/switch_core/transport/ephemeral.py
@@ -0,0 +1,70 @@
+"""How presence reaches the clients watching a room.
+
+Some events are announced and never stored: runtime state today, typing if it
+ever returns. Their next value replaces them, so a row in `messages` would put
+something in the room's ordering that no reader is ever shown, and a delivery
+cursor would faithfully replay a status that stopped being true minutes ago.
+The message log is deliberately not their home.
+
+But a Postgres transport delivers by reading rows, so dropping the write also
+dropped the delivery: runtime state was captured in `agent_runtime_states` and
+reached nobody, which is why an agent going busy stopped showing up on a
+bridged channel.
+
+This is the delivery, without the storage: an in-process fan-out to the
+transports watching that room, carrying the event itself rather than a
+position — the opposite of the notify listener, and correct for the opposite
+reason. A position is right when the value is durable and the reader can go and
+fetch it. Presence has nowhere to fetch from, so the announcement has to be the
+value, and a missed one costs a briefly stale indicator rather than data.
+
+**It is in-process, the same limitation `InviteBus` documents**, and it should
+be lifted at the same time and in the same way. A second replica needs a
+cross-process signal for both; until switch-core can run more than one, this is
+no worse than the Matrix sessions it replaces.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+
+from switch_core.transport.types import InboundCustomEvent
+
+logger = logging.getLogger(__name__)
+
+EphemeralHandler = Callable[[InboundCustomEvent], Awaitable[None]]
+
+
+class EphemeralBus:
+ """Routes an unstored room event to whoever is watching that room."""
+
+ def __init__(self) -> None:
+ self._handlers: dict[str, set[EphemeralHandler]] = {}
+
+ def subscribe(self, transport_room_id: str, handler: EphemeralHandler) -> None:
+ self._handlers.setdefault(transport_room_id, set()).add(handler)
+
+ def unsubscribe(self, transport_room_id: str, handler: EphemeralHandler) -> None:
+ self._handlers.get(transport_room_id, set()).discard(handler)
+
+ async def publish(self, transport_room_id: str, event: InboundCustomEvent) -> None:
+ """Hand the event to every watcher, and let none of them stop another.
+
+ A handler that raises is logged rather than propagated: this is
+ presence, and failing the send of a status update because one listener
+ mishandled it would turn a cosmetic problem into a real one.
+ """
+ for handler in list(self._handlers.get(transport_room_id, ())):
+ try:
+ await handler(event)
+ except asyncio.CancelledError:
+ raise
+ except Exception:
+ logger.error(
+ "A watcher failed handling %s in room %s",
+ event.event_type,
+ transport_room_id,
+ exc_info=True,
+ )
diff --git a/core/switch_core/transport/invites.py b/core/switch_core/transport/invites.py
new file mode 100644
index 000000000..14a94c601
--- /dev/null
+++ b/core/switch_core/transport/invites.py
@@ -0,0 +1,57 @@
+"""How a client is told it has been added to a room.
+
+Over Matrix this was an event: the admin invited a user, the user's sync loop
+saw the invitation and `ClientBase.on_invite` joined. Nothing else had to know
+the order things happened in, because the invitation was durable and the client
+picked it up whenever it next synced.
+
+A Postgres transport watches the rooms it knew about when it started, so a
+membership written underneath it would be a room it never reads — a client
+sitting in a room in silence, which is precisely the failure this stack keeps
+refusing to ship. This is the missing signal, in the shape the clients already
+handle: an invitation, delivered to a live client, auto-accepted by the same
+code path as before.
+
+**It is in-process, and that is a real limitation.** A client running in
+another replica of switch-core would not hear it. That is the same constraint
+Matrix sync sessions imposed and the reason switch-core is single-replica
+today; lifting it is its own step, and until then this is no worse than what it
+replaces. When nobody is listening for a user the caller writes the membership
+itself, so the room is still joined the next time that client starts — the
+invitation is a wake-up, never the record.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+
+logger = logging.getLogger(__name__)
+
+InviteHandler = Callable[[str], Awaitable[None]]
+
+
+class InviteBus:
+ """Routes an invitation to the live transport for a user, if there is one."""
+
+ def __init__(self) -> None:
+ self._handlers: dict[str, InviteHandler] = {}
+
+ def register(self, user_id: str, handler: InviteHandler) -> None:
+ self._handlers[user_id] = handler
+
+ def unregister(self, user_id: str) -> None:
+ self._handlers.pop(user_id, None)
+
+ async def invite(self, user_id: str, transport_room_id: str) -> bool:
+ """Tell `user_id` it is in `transport_room_id`.
+
+ Returns whether anyone was listening. False is not an error — a client
+ that is not running has nothing to wake — but the caller then owns
+ writing the membership, so the answer must not be ignored.
+ """
+ handler = self._handlers.get(user_id)
+ if handler is None:
+ return False
+ await handler(transport_room_id)
+ return True
diff --git a/core/switch_core/transport/matrix.py b/core/switch_core/transport/matrix.py
new file mode 100644
index 000000000..082672222
--- /dev/null
+++ b/core/switch_core/transport/matrix.py
@@ -0,0 +1,459 @@
+"""Matrix implementation of `MessageTransport`.
+
+This is the only module in Switch that may import matrix-nio. Everything
+Matrix-shaped lives here: content dicts, `m.relates_to` threading, mxc URIs,
+pagination tokens and the sync loop.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from nio import (
+ AsyncClient,
+ DownloadError,
+ InviteMemberEvent,
+ JoinedRoomsError,
+ LoginError,
+ ProfileSetDisplayNameError,
+ ReactionEvent,
+ RoomGetEventError,
+ RoomMemberEvent,
+ RoomMessageMedia,
+ RoomMessagesError,
+ RoomMessageText,
+ RoomSendError,
+ RoomTypingError,
+ SyncError,
+ SyncResponse,
+ UnknownEvent,
+ UploadError,
+)
+
+from switch_core.attachments import ATTACHMENT_GROUP_KEY
+from switch_core.transport.content import media_content, message_content
+from switch_core.transport.port import TransportHandlers
+from switch_core.transport.types import (
+ DownloadResult,
+ HistoryPage,
+ InboundCustomEvent,
+ InboundEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+ MessageFormat,
+ NotConnectedError,
+ RoomRef,
+ SendResult,
+ TransportError,
+ UploadResult,
+)
+
+logger = logging.getLogger(__name__)
+
+SYNC_TIMEOUT_MS = 30000
+
+
+@dataclass(frozen=True)
+class _RoomIdOnly:
+ """Stands in for a room object when only the id is known.
+
+ History and single-event fetches return events without the room they came
+ from, but the converters only ever read the id.
+ """
+
+ room_id: str
+
+
+def _content(event: Any) -> dict[str, object]:
+ source = getattr(event, "source", None) or {}
+ content = source.get("content") or {}
+ return dict(content)
+
+
+def _thread_root_of(content: dict[str, object], event_id: str) -> str | None:
+ """The thread this event belongs to, or None when it is top level.
+
+ Matrix threads are flat: an event either relates to a root or is one.
+ """
+ relates = content.get("m.relates_to") or {}
+ if isinstance(relates, dict) and relates.get("rel_type") == "m.thread":
+ root = relates.get("event_id")
+ return str(root) if root else None
+ return None
+
+
+def to_room_ref(room: Any) -> RoomRef:
+ return RoomRef(room_id=room.room_id)
+
+
+def to_inbound_message(room: Any, event: Any) -> InboundMessage:
+ content = _content(event)
+ return InboundMessage(
+ room_id=room.room_id,
+ event_id=event.event_id,
+ sender=event.sender,
+ timestamp=event.server_timestamp,
+ content=content,
+ body=getattr(event, "body", "") or "",
+ sender_name=content.get("sender_name"), # type: ignore[arg-type]
+ formatted_body=getattr(event, "formatted_body", None),
+ msgtype=str(content.get("msgtype") or "m.text"),
+ thread_root_id=_thread_root_of(content, event.event_id),
+ )
+
+
+def to_inbound_media(room: Any, event: Any) -> InboundMedia:
+ content = _content(event)
+ info = content.get("info") or {}
+ if not isinstance(info, dict):
+ info = {}
+ return InboundMedia(
+ room_id=room.room_id,
+ event_id=event.event_id,
+ sender=event.sender,
+ timestamp=event.server_timestamp,
+ content=content,
+ body=getattr(event, "body", "") or "",
+ sender_name=content.get("sender_name"), # type: ignore[arg-type]
+ uri=str(getattr(event, "url", "") or ""),
+ filename=content.get("filename") or getattr(event, "body", None), # type: ignore[arg-type]
+ mimetype=info.get("mimetype"),
+ size=info.get("size"),
+ msgtype=str(content.get("msgtype") or "m.file"),
+ thread_root_id=_thread_root_of(content, event.event_id),
+ group=content.get(ATTACHMENT_GROUP_KEY), # type: ignore[arg-type]
+ )
+
+
+def to_inbound_membership(room: Any, event: Any) -> InboundMembership:
+ content = _content(event)
+ return InboundMembership(
+ room_id=room.room_id,
+ event_id=getattr(event, "event_id", ""),
+ sender=getattr(event, "sender", ""),
+ timestamp=getattr(event, "server_timestamp", 0),
+ content=content,
+ state_key=getattr(event, "state_key", ""),
+ membership=getattr(event, "membership", ""),
+ prev_membership=getattr(event, "prev_membership", None),
+ display_name=content.get("displayname"), # type: ignore[arg-type]
+ )
+
+
+def to_inbound_custom(room: Any, event: Any) -> InboundCustomEvent:
+ content = _content(event)
+ return InboundCustomEvent(
+ room_id=room.room_id,
+ event_id=event.event_id,
+ sender=event.sender,
+ timestamp=getattr(event, "server_timestamp", 0),
+ content=content,
+ event_type=event.type,
+ thread_root_id=_thread_root_of(content, event.event_id),
+ )
+
+
+def to_inbound(room: Any, event: Any) -> InboundEvent:
+ """Convert a timeline event to the DTO matching its kind."""
+ if isinstance(event, RoomMessageMedia):
+ return to_inbound_media(room, event)
+ if isinstance(event, RoomMessageText):
+ return to_inbound_message(room, event)
+ if isinstance(event, RoomMemberEvent):
+ return to_inbound_membership(room, event)
+ if isinstance(event, UnknownEvent):
+ return to_inbound_custom(room, event)
+ return to_inbound_event(room, event)
+
+
+def to_inbound_event(room: Any, event: Any) -> InboundEvent:
+ return InboundEvent(
+ room_id=room.room_id,
+ event_id=getattr(event, "event_id", ""),
+ sender=getattr(event, "sender", ""),
+ timestamp=getattr(event, "server_timestamp", 0),
+ content=_content(event),
+ )
+
+
+def _carries_durable_events(response: SyncResponse) -> bool:
+ """Whether a sync response holds anything a restart would need to replay.
+
+ Timeline events, room state and invites are dispatched to handlers, so the
+ cursor must move past them durably. Presence, typing, receipts and account
+ data are not — they only advance the token.
+ """
+ if response.rooms.invite or response.to_device_events:
+ return True
+ return any(
+ room.timeline.events or room.state
+ for room in (*response.rooms.join.values(), *response.rooms.leave.values())
+ )
+
+
+class MatrixTransport:
+ """Carries Switch messages over a Matrix homeserver."""
+
+ def __init__(
+ self,
+ *,
+ server_url: str,
+ user_id: str,
+ password: str,
+ device_id: str | None = None,
+ access_token: str | None = None,
+ client: AsyncClient | None = None,
+ ) -> None:
+ self.server_url = server_url
+ self.user_id = user_id
+ self.password = password
+ self.device_id = device_id
+ self.access_token = access_token
+ self._client: AsyncClient | None = client
+ self._handlers = TransportHandlers()
+
+ # ── Session ───────────────────────────────────────────────────────────────
+
+ @property
+ def raw_client(self) -> AsyncClient:
+ """The underlying nio client.
+
+ An escape hatch for call sites not yet expressed on the port. New code
+ must use the port; this exists so the migration can proceed in steps.
+ """
+ if self._client is None:
+ raise NotConnectedError(
+ f"Transport for {self.user_id} is not connected — call connect() first"
+ )
+ return self._client
+
+ @property
+ def session_state(self) -> dict[str, str | None]:
+ return {"access_token": self.access_token, "device_id": self.device_id}
+
+ async def connect(self) -> None:
+ if self._client is None:
+ self._client = AsyncClient(self.server_url, self.user_id)
+
+ if self.access_token and self.device_id:
+ self._client.access_token = self.access_token
+ self._client.device_id = self.device_id
+ logger.info("Transport %s restored session from stored token", self.user_id)
+ return
+
+ if not self.password:
+ raise TransportError(f"No credentials available for {self.user_id}")
+
+ resp = await self._client.login(self.password)
+ if isinstance(resp, LoginError):
+ raise TransportError(f"Login failed for {self.user_id}: {resp.message}")
+ self.device_id = resp.device_id
+ self.access_token = self._client.access_token
+ logger.info("Transport %s authenticated via password", self.user_id)
+
+ async def close(self) -> None:
+ if self._client is not None:
+ await self._client.close()
+
+ async def relogin(self) -> None:
+ """Re-authenticate an existing connection after a session failure."""
+ if not self.password:
+ return
+ resp = await self.raw_client.login(self.password)
+ if isinstance(resp, LoginError):
+ raise TransportError(f"Re-login failed for {self.user_id}: {resp.message}")
+ self.device_id = resp.device_id
+ self.access_token = self.raw_client.access_token
+
+ def register_handlers(self, handlers: TransportHandlers) -> None:
+ self._handlers = handlers
+ client = self.raw_client
+
+ def bind(handler: Any, convert: Any, kind: Any) -> None:
+ if handler is None:
+ return
+
+ async def _cb(room: Any, event: Any) -> None:
+ await handler(to_room_ref(room), convert(room, event))
+
+ client.add_event_callback(_cb, kind)
+
+ bind(handlers.on_message, to_inbound_message, RoomMessageText)
+ # RoomMessageMedia is the base of RoomMessageImage / RoomMessageFile, so
+ # one callback covers every media msgtype.
+ bind(handlers.on_media, to_inbound_media, RoomMessageMedia)
+ bind(handlers.on_reaction, to_inbound_event, ReactionEvent)
+ bind(handlers.on_member_event, to_inbound_membership, RoomMemberEvent)
+ bind(handlers.on_custom_event, to_inbound_custom, UnknownEvent)
+ bind(handlers.on_invite, to_inbound_membership, InviteMemberEvent)
+
+ if handlers.on_sync is not None:
+ on_sync = handlers.on_sync
+
+ async def _sync_cb(response: SyncResponse) -> None:
+ await on_sync(response.next_batch, _carries_durable_events(response))
+
+ client.add_response_callback(_sync_cb, SyncResponse) # type: ignore[arg-type]
+
+ if handlers.on_sync_error is not None:
+ on_sync_error = handlers.on_sync_error
+
+ async def _sync_error_cb(response: SyncError) -> None:
+ await on_sync_error(response.message)
+
+ client.add_response_callback(_sync_error_cb, SyncError) # type: ignore[arg-type]
+
+ async def receive_forever(self, *, since: str | None) -> None:
+ await self.raw_client.sync_forever(timeout=SYNC_TIMEOUT_MS, since=since)
+
+ # ── Outbound ──────────────────────────────────────────────────────────────
+
+ async def send_message(
+ self,
+ room_id: str,
+ body: str,
+ *,
+ sender_name: str,
+ format: MessageFormat = "text",
+ mentions: list[str] | None = None,
+ thread_root_id: str | None = None,
+ extra_content: dict[str, object] | None = None,
+ ) -> SendResult:
+ content = message_content(
+ body,
+ sender_name=sender_name,
+ format=format,
+ mentions=mentions,
+ thread_root_id=thread_root_id,
+ extra_content=extra_content,
+ )
+ return await self._room_send(room_id, "m.room.message", content)
+
+ async def send_event(
+ self,
+ room_id: str,
+ event_type: str,
+ content: dict[str, object],
+ ) -> SendResult:
+ return await self._room_send(room_id, event_type, content)
+
+ async def send_media(
+ self,
+ room_id: str,
+ uri: str,
+ filename: str,
+ mimetype: str,
+ size: int,
+ *,
+ sender_name: str,
+ msgtype: str,
+ caption: str | None = None,
+ thread_root_id: str | None = None,
+ group: dict[str, object] | None = None,
+ ) -> SendResult:
+ content = media_content(
+ uri,
+ filename,
+ mimetype,
+ size,
+ sender_name=sender_name,
+ msgtype=msgtype,
+ caption=caption,
+ thread_root_id=thread_root_id,
+ group=group,
+ )
+ return await self._room_send(room_id, "m.room.message", content)
+
+ async def _room_send(
+ self, room_id: str, event_type: str, content: dict[str, object]
+ ) -> SendResult:
+ resp = await self.raw_client.room_send(room_id, event_type, content)
+ if isinstance(resp, RoomSendError):
+ raise TransportError(
+ f"Failed to send {event_type} to {room_id}: {resp.message}"
+ )
+ return SendResult(
+ event_id=resp.event_id, event_type=event_type, content=content
+ )
+
+ async def upload_media(
+ self, data: bytes, content_type: str, filename: str
+ ) -> UploadResult:
+ resp, _ = await self.raw_client.upload(
+ data_provider=io.BytesIO(data),
+ content_type=content_type,
+ filename=filename,
+ filesize=len(data),
+ )
+ if isinstance(resp, UploadError):
+ raise TransportError(
+ f"Failed to upload media '{filename}' to Matrix: {resp.message}"
+ )
+ return UploadResult(uri=resp.content_uri)
+
+ async def download_media(self, uri: str) -> DownloadResult:
+ resp = await self.raw_client.download(mxc=uri)
+ if isinstance(resp, DownloadError):
+ raise TransportError(f"Failed to download {uri}: {resp.message}")
+ return DownloadResult(
+ body=resp.body,
+ content_type=getattr(resp, "content_type", None),
+ filename=getattr(resp, "filename", None),
+ )
+
+ async def set_typing(self, room_id: str, is_typing: bool) -> None:
+ logger.debug(
+ "Setting typing %s in room %s for %s", is_typing, room_id, self.user_id
+ )
+ resp = await self.raw_client.room_typing(room_id, is_typing)
+ if isinstance(resp, RoomTypingError):
+ logger.error("Failed to set typing in %s: %s", room_id, resp.message)
+
+ # ── History ───────────────────────────────────────────────────────────────
+
+ async def get_event(self, room_id: str, event_id: str) -> InboundEvent | None:
+ resp = await self.raw_client.room_get_event(room_id, event_id)
+ if isinstance(resp, RoomGetEventError):
+ return None
+ return to_inbound(_RoomIdOnly(room_id), resp.event)
+
+ async def read_history(
+ self, room_id: str, *, start: str | None, limit: int
+ ) -> HistoryPage:
+ resp = await self.raw_client.room_messages(room_id, start=start, limit=limit)
+ if isinstance(resp, RoomMessagesError):
+ raise TransportError(f"Failed to read history in {room_id}: {resp.message}")
+ room = _RoomIdOnly(room_id)
+ return HistoryPage(
+ events=[to_inbound(room, event) for event in resp.chunk],
+ next_token=resp.end,
+ )
+
+ # ── Rooms ─────────────────────────────────────────────────────────────────
+
+ async def join_room(self, room_id: str) -> bool:
+ resp = await self.raw_client.join(room_id)
+ if hasattr(resp, "room_id"):
+ return True
+ logger.error("Transport %s failed to join %s: %s", self.user_id, room_id, resp)
+ return False
+
+ async def joined_rooms(self) -> list[str]:
+ resp = await self.raw_client.joined_rooms()
+ if isinstance(resp, JoinedRoomsError):
+ logger.error(
+ "Failed to list joined rooms for %s: %s", self.user_id, resp.message
+ )
+ return []
+ return list(resp.rooms)
+
+ async def set_display_name(self, display_name: str) -> None:
+ resp = await self.raw_client.set_displayname(display_name)
+ if isinstance(resp, ProfileSetDisplayNameError):
+ raise TransportError(
+ f"Could not set the display name of {self.user_id}: {resp}"
+ )
diff --git a/core/switch_core/transport/port.py b/core/switch_core/transport/port.py
new file mode 100644
index 000000000..cd4e866be
--- /dev/null
+++ b/core/switch_core/transport/port.py
@@ -0,0 +1,177 @@
+"""The message-transport port.
+
+`MessageTransport` is the whole contract between Switch and whatever carries
+its messages. Implementations live beside this module; nothing outside the
+`switch_core.transport` package may import a transport library directly.
+
+The contract is deliberately narrow and derived from what callers actually do:
+send a message, send a typed event, move media, read history back, and receive
+events. Operations raise `TransportError` on failure instead of returning an
+error object.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from switch_core.transport.types import (
+ DownloadResult,
+ HistoryPage,
+ MessageFormat,
+ SendResult,
+ UploadResult,
+)
+
+Handler = Callable[[Any, Any], Awaitable[None]]
+# (cursor, durable). `durable` says whether the batch carried anything a
+# restart would have to replay, so the client can decide how urgently to
+# persist the cursor. The transport decides it: only it can see what the batch
+# held, and saying so as a bool keeps its event classes out of the client.
+SyncHandler = Callable[[str, bool], Awaitable[None]]
+SyncErrorHandler = Callable[[str], Awaitable[None]]
+
+
+@dataclass
+class TransportHandlers:
+ """Inbound callbacks a client registers with its transport.
+
+ Each is optional so a client only pays for the events it cares about. The
+ transport decides how to bind them; the client never names an event class.
+ """
+
+ on_message: Handler | None = None
+ on_media: Handler | None = None
+ on_reaction: Handler | None = None
+ on_member_event: Handler | None = None
+ on_custom_event: Handler | None = None
+ on_invite: Handler | None = None
+ on_sync: SyncHandler | None = None
+ on_sync_error: SyncErrorHandler | None = None
+
+
+@runtime_checkable
+class MessageTransport(Protocol):
+ """Carries messages between Switch and its participants."""
+
+ # ── Session ───────────────────────────────────────────────────────────────
+
+ @property
+ def session_state(self) -> dict[str, str | None]:
+ """Opaque credentials to persist so a restart can resume.
+
+ The shape is transport-defined; callers store and hand it back
+ unread.
+ """
+ ...
+
+ async def connect(self) -> None:
+ """Authenticate, restoring a stored session when one is available."""
+ ...
+
+ async def close(self) -> None:
+ """Release the connection. Safe to call when never connected."""
+ ...
+
+ async def relogin(self) -> None:
+ """Re-authenticate after the session was rejected mid-stream."""
+ ...
+
+ def register_handlers(self, handlers: TransportHandlers) -> None:
+ """Bind inbound callbacks. Call before `receive_forever`."""
+ ...
+
+ async def receive_forever(self, *, since: str | None) -> None:
+ """Deliver inbound events to the registered handlers until closed.
+
+ `since` resumes from a cursor previously reported to `on_sync`.
+ """
+ ...
+
+ # ── Outbound ──────────────────────────────────────────────────────────────
+
+ async def send_message(
+ self,
+ room_id: str,
+ body: str,
+ *,
+ sender_name: str,
+ format: MessageFormat = "text",
+ mentions: list[str] | None = None,
+ thread_root_id: str | None = None,
+ extra_content: dict[str, object] | None = None,
+ ) -> SendResult:
+ """Post a text message. Raises `TransportError` if it is not accepted."""
+ ...
+
+ async def send_event(
+ self,
+ room_id: str,
+ event_type: str,
+ content: dict[str, object],
+ ) -> SendResult:
+ """Post a typed non-message event, e.g. a `com.switch.*` payload."""
+ ...
+
+ async def send_media(
+ self,
+ room_id: str,
+ uri: str,
+ filename: str,
+ mimetype: str,
+ size: int,
+ *,
+ sender_name: str,
+ msgtype: str,
+ caption: str | None = None,
+ thread_root_id: str | None = None,
+ group: dict[str, object] | None = None,
+ ) -> SendResult:
+ """Post an event pointing at an already-uploaded `uri`.
+
+ `group` marks this as one part of a multi-attachment message —
+ `{"id": ..., "index": i, "total": n}` — for transports that cannot
+ carry several files on one event.
+ """
+ ...
+
+ async def upload_media(
+ self, data: bytes, content_type: str, filename: str
+ ) -> UploadResult:
+ """Store bytes and return the handle to reference them by."""
+ ...
+
+ async def download_media(self, uri: str) -> DownloadResult:
+ """Retrieve bytes for a handle returned by `upload_media`."""
+ ...
+
+ async def set_typing(self, room_id: str, is_typing: bool) -> None:
+ """Signal composing state. Best-effort: never raises."""
+ ...
+
+ # ── History ───────────────────────────────────────────────────────────────
+
+ async def get_event(self, room_id: str, event_id: str) -> Any | None:
+ """Fetch one event by id, or None when it cannot be retrieved."""
+ ...
+
+ async def read_history(
+ self, room_id: str, *, start: str | None, limit: int
+ ) -> HistoryPage:
+ """Read one page of history backwards from `start`."""
+ ...
+
+ # ── Rooms ─────────────────────────────────────────────────────────────────
+
+ async def join_room(self, room_id: str) -> bool:
+ """Join a room. Returns whether the join was accepted."""
+ ...
+
+ async def joined_rooms(self) -> list[str]:
+ """Rooms this connection is currently a member of."""
+ ...
+
+ async def set_display_name(self, display_name: str) -> None:
+ """Change the name this connection shows under."""
+ ...
diff --git a/core/switch_core/transport/postgres.py b/core/switch_core/transport/postgres.py
new file mode 100644
index 000000000..10313f6c3
--- /dev/null
+++ b/core/switch_core/transport/postgres.py
@@ -0,0 +1,739 @@
+"""Postgres implementation of `MessageTransport`.
+
+The homeserver's remaining job is to carry an event from the client that sent
+it to the clients that should see it, and to remember it in between. A table
+does all three, and Switch already writes that table: every send is recorded
+into `messages` today, beside the send, so the rows exist and have been
+verified against the bus.
+
+This turns that parallel record into the thing itself. **The write is the
+send.** There is no second store to agree with, which is why the reconciler
+this stack built has no work left once the flip happens — it exists to compare
+two records of the same event, and there is only one.
+
+Three consequences worth stating up front:
+
+- **A send now fails when the database does.** The recorder deliberately could
+ not fail a send, because a row was a nice-to-have next to a delivered
+ message. Here the row *is* the delivery, so there is nothing left to protect:
+ a write that fails is a message that was not sent, and the caller must hear
+ about it.
+- **Every durable event gets a row, not only the conversation.** The bus
+ carried commands and task events too, and they have to reach their handlers.
+ `recorded_types` therefore stops meaning "what is written" and starts meaning
+ "what a reader is shown" — a projection applied on the way out. The one
+ category with no row is the genuinely ephemeral: presence-like state whose
+ next value replaces it, which is announced and never stored.
+- **Ids are opaque, and these are not `$event` ids.** Nothing in Switch parses
+ one; the columns holding them are already named `transport_event_id`.
+
+History is the one method left unimplemented, and deliberately: the read path
+already queries these rows directly, and the only callers left are the walkers
+that exist to compare a bus against them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from switch_core.attachments import ATTACHMENT_GROUP_KEY
+from switch_core.db.models import ClientRoom, MediaBlob, Message, MessageAttachment
+from switch_core.messages.recorded_types import EPHEMERAL
+from switch_core.messages.row import attachments_in, text_field, thread_root_of
+from switch_core.transport.content import media_content, message_content
+from switch_core.transport.ephemeral import EphemeralBus
+from switch_core.transport.invites import InviteBus
+from switch_core.transport.port import Handler, TransportHandlers
+from switch_core.transport.types import (
+ DownloadResult,
+ HistoryPage,
+ InboundCustomEvent,
+ InboundEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+ MessageFormat,
+ RoomRef,
+ SendResult,
+ TransportError,
+ UploadResult,
+)
+
+if TYPE_CHECKING:
+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+ from switch_core.db.stores.media_store import MediaStore
+ from switch_core.db.stores.message_store import MessageStore
+ from switch_core.db.stores.room_store import RoomStore
+ from switch_core.messages.notify import MessageListener
+
+logger = logging.getLogger(__name__)
+
+# How many rows one wake-up reads at a time. A page rather than everything
+# outstanding, so a room that moved a long way while a handler was busy is
+# delivered in bounded steps instead of one unbounded read.
+_DELIVERY_PAGE = 200
+
+MEMBERSHIP_EVENT_TYPE = "m.room.member"
+
+
+def new_event_id() -> str:
+ """A fresh event id.
+
+ Prefixed so that a row's origin is readable at a glance during the window
+ where a room holds both these and ids minted by the old bus. The prefix is
+ decoration for humans — no code may branch on it.
+ """
+ return f"sw_{uuid.uuid4().hex}"
+
+
+class PostgresTransport:
+ """Carries a room's events in the `messages` table.
+
+ One instance per client, as with the Matrix transport: it sends as that
+ client and, once receiving lands, delivers to that client's handlers.
+ """
+
+ def __init__(
+ self,
+ *,
+ user_id: str,
+ client_id: str,
+ display_name: str,
+ session_factory: async_sessionmaker[AsyncSession],
+ room_store: RoomStore,
+ message_store: MessageStore,
+ media_store: MediaStore,
+ listener: MessageListener,
+ invites: InviteBus,
+ ephemeral: EphemeralBus,
+ ) -> None:
+ self.user_id = user_id
+ self.client_id = client_id
+ self.display_name = display_name
+ self._session_factory = session_factory
+ self._room_store = room_store
+ self._message_store = message_store
+ self._media_store = media_store
+ self._listener = listener
+ self._invites = invites
+ self._ephemeral = ephemeral
+ self._handlers = TransportHandlers()
+ # Per-room delivery position, and the transport-side id to hand back
+ # to a handler. Both are keyed by the Switch room id, which is what
+ # the listener announces.
+ self._cursors: dict[str, int] = {}
+ self._watching: dict[str, str] = {}
+ self._receiving = False
+ self._closed = asyncio.Event()
+ # Rooms this client has been told moved but has not read yet, and the
+ # signal its delivery loop waits on. A set because a room that moved
+ # twice while the loop was busy is still one read.
+ self._pending: set[str] = set()
+ self._wake = asyncio.Event()
+ self._delivering = False
+ # A room's transport id never changes, so this only grows and never
+ # goes stale.
+ self._room_ids: dict[str, str] = {}
+
+ # ── Session ───────────────────────────────────────────────────────────────
+
+ @property
+ def session_state(self) -> dict[str, str | None]:
+ """Nothing to resume.
+
+ The Matrix transport persisted an access token and a device id because
+ logging in again cost a round trip and a new device. Here the client's
+ identity is a row it already owns, so there is no credential to carry
+ across a restart. The empty dict is the honest answer, and callers
+ store it unread.
+ """
+ return {}
+
+ async def connect(self) -> None:
+ """Nothing to authenticate: the caller already knows who it is."""
+
+ async def close(self) -> None:
+ """Stop receiving. Sessions are borrowed per operation, so that is all
+ there is to release."""
+ self._closed.set()
+
+ async def relogin(self) -> None:
+ """Never called: there is no session to be rejected."""
+
+ def register_handlers(self, handlers: TransportHandlers) -> None:
+ self._handlers = handlers
+
+ async def receive_forever(self, *, since: str | None) -> None:
+ """Deliver every row written to this client's rooms from now on.
+
+ `since` is ignored, and that is the behaviour to keep rather than an
+ omission. A Matrix client resumed from its stored sync token and then
+ threw away everything older than the process (`ClientBase._should_ignore`),
+ so what was actually delivered on a restart was "whatever happened
+ while I was up". Starting each room at its current head says the same
+ thing without the cursor that lied about it. What an agent missed
+ while it was away is a delivery-cursor question, and delivery cursors
+ are a layer above this one.
+ """
+ rooms = await self.joined_rooms()
+ if not rooms:
+ logger.error(
+ "Client %s is receiving but is a member of no room: it will "
+ "hear nothing until something adds it to one. Under Matrix "
+ "membership lived on the homeserver; here it is the "
+ "client_rooms table, so a client whose rows were never "
+ "written is silent rather than broken",
+ self.user_id,
+ )
+ delivery = asyncio.create_task(self._deliver_forever())
+ for transport_room_id in rooms:
+ await self._watch(transport_room_id)
+ self._receiving = True
+ self._invites.register(self.user_id, self._on_invited)
+ try:
+ await self._closed.wait()
+ finally:
+ self._receiving = False
+ self._invites.unregister(self.user_id)
+ self._unwatch_all()
+ delivery.cancel()
+
+ async def _deliver_forever(self) -> None:
+ """This client's own delivery loop: its rooms, one at a time.
+
+ The listener fans out to every subscriber from a single task, so
+ anything a waker awaits is awaited by every other client's delivery
+ too — and a waker awaits its handler, which for a bridge is an HTTP
+ call to Slack that can sit in a rate limit for seconds. Doing the work
+ here instead means a stalled bridge stalls itself.
+
+ Serial within the client, deliberately. Two concurrent runs for one
+ room would both read the same cursor and deliver the same rows twice,
+ and a redelivered message is indistinguishable to a reader from a new
+ one. Overlapping wake-ups collapse into one more pass instead, which
+ also bounds this client to one outstanding read.
+ """
+ while True:
+ await self._wake.wait()
+ self._wake.clear()
+ rooms = list(self._pending)
+ self._pending.clear()
+ self._delivering = True
+ try:
+ for room_id in rooms:
+ try:
+ await self._drain_room(room_id)
+ except asyncio.CancelledError:
+ raise
+ except Exception:
+ # One room's failure is not the other rooms' problem,
+ # and this loop is the only delivery this client has.
+ logger.error(
+ "Delivery failed for client %s in room %s",
+ self.user_id,
+ room_id,
+ exc_info=True,
+ )
+ finally:
+ self._delivering = False
+
+ async def _on_invited(self, transport_room_id: str) -> None:
+ """Someone added this client to a room while it was running.
+
+ Handed to `on_invite` rather than joined here, because auto-accepting
+ is the client's decision and it already has one — the same one it made
+ when the invitation arrived over sync.
+ """
+ handler = self._handlers.on_invite
+ if handler is None:
+ return
+ await handler(
+ RoomRef(room_id=transport_room_id),
+ InboundMembership(
+ room_id=transport_room_id,
+ event_id=new_event_id(),
+ sender=self.user_id,
+ timestamp=_now_ms(),
+ state_key=self.user_id,
+ membership="invite",
+ display_name=self.display_name,
+ ),
+ )
+
+ async def _watch(
+ self, transport_room_id: str, *, from_seq: int | None = None
+ ) -> None:
+ """Start delivering a room, from its head or from a given position.
+
+ `from_seq` exists so a client can hear its own arrival. Over Matrix a
+ join came back down the joining client's own connection — the
+ homeserver turned it into an event and delivered it to everyone,
+ including the person it was about — and code downstream learned it had
+ joined by being told. Writing the row and then watching from the head
+ steps over the client's own footprint: the room hears the arrival and
+ the arriving client does not.
+
+ Restoring the loop-back rather than dispatching the one handler that
+ noticed keeps every guard downstream in play, and covers whatever else
+ depended on hearing its own join.
+ """
+ async with self._session_factory() as session:
+ room_id = await self._resolve_room(session, transport_room_id)
+ if room_id in self._cursors:
+ return
+ self._cursors[room_id] = (
+ from_seq
+ if from_seq is not None
+ else await self._message_store.head_seq(session, room_id)
+ )
+ self._watching[room_id] = transport_room_id
+ self._listener.subscribe(room_id, self._on_room_advanced)
+ self._ephemeral.subscribe(transport_room_id, self._on_ephemeral)
+ if from_seq is not None:
+ # The announcement for anything already written went out before
+ # this subscription existed, so nothing will wake the loop for it.
+ self._pending.add(room_id)
+ self._wake.set()
+
+ def _unwatch_all(self) -> None:
+ for room_id, transport_room_id in self._watching.items():
+ self._listener.unsubscribe(room_id, self._on_room_advanced)
+ self._ephemeral.unsubscribe(transport_room_id, self._on_ephemeral)
+ self._watching.clear()
+ self._cursors.clear()
+
+ async def _on_ephemeral(self, event: InboundCustomEvent) -> None:
+ """An unstored event in a room this client watches.
+
+ It arrives already assembled, unlike a row: there is nothing to read
+ back, which is the whole difference between announcing a position and
+ announcing a value.
+ """
+ handler = self._handlers.on_custom_event
+ if handler is None:
+ return
+ await handler(RoomRef(room_id=event.room_id), event)
+
+ async def _on_room_advanced(self, room_id: str) -> None:
+ """The listener's waker: note the room and return.
+
+ It must not deliver. The listener fans out from one task, so time
+ spent here is time no other client in the process is being delivered
+ to.
+ """
+ if room_id not in self._watching:
+ return
+ self._pending.add(room_id)
+ self._wake.set()
+
+ async def _drain_room(self, room_id: str) -> None:
+ """Read what this client has not seen in one room, and hand it over.
+
+ Driven by this client's own loop, which promises only that the room
+ moved — and never that it moved once. The
+ cursor is this transport's own, so a coalesced announcement, a
+ duplicate, or a wake-up after a reconnect all reduce to the same
+ thing: read from where I was, and advance.
+
+ The cursor advances per row rather than at the end, so a handler that
+ raises does not cost the rows already delivered — the failure belongs
+ to one event, and redelivering its neighbours would be worse than
+ dropping it.
+ """
+ transport_room_id = self._watching.get(room_id)
+ if transport_room_id is None:
+ return
+ while True:
+ async with self._session_factory() as session:
+ rows = await self._message_store.list_for_room(
+ session,
+ room_id,
+ after_seq=self._cursors[room_id],
+ limit=_DELIVERY_PAGE,
+ )
+ attachments = await self._message_store.attachments_for(
+ session, [row.id for row in rows]
+ )
+ if not rows:
+ return
+ for row in rows:
+ self._cursors[room_id] = row.seq
+ await self._deliver(transport_room_id, row, attachments.get(row.id, []))
+ if len(rows) < _DELIVERY_PAGE:
+ return
+
+ async def _deliver(
+ self,
+ transport_room_id: str,
+ row: Message,
+ attachments: list[MessageAttachment],
+ ) -> None:
+ room = RoomRef(room_id=transport_room_id)
+ event = to_inbound(row, attachments, transport_room_id=transport_room_id)
+ handler = self._handler_for(event)
+ if handler is None:
+ return
+ await handler(room, event)
+
+ def _handler_for(self, event: InboundEvent) -> Handler | None:
+ if isinstance(event, InboundMedia):
+ return self._handlers.on_media
+ if isinstance(event, InboundMembership):
+ return self._handlers.on_member_event
+ if isinstance(event, InboundCustomEvent):
+ return self._handlers.on_custom_event
+ return self._handlers.on_message
+
+ # ── Outbound ──────────────────────────────────────────────────────────────
+
+ async def send_message(
+ self,
+ room_id: str,
+ body: str,
+ *,
+ sender_name: str,
+ format: MessageFormat = "text",
+ mentions: list[str] | None = None,
+ thread_root_id: str | None = None,
+ extra_content: dict[str, object] | None = None,
+ ) -> SendResult:
+ content = message_content(
+ body,
+ sender_name=sender_name,
+ format=format,
+ mentions=mentions,
+ thread_root_id=thread_root_id,
+ extra_content=extra_content,
+ )
+ return await self._send(room_id, "m.room.message", content, sender_name)
+
+ async def send_event(
+ self,
+ room_id: str,
+ event_type: str,
+ content: dict[str, object],
+ ) -> SendResult:
+ return await self._send(room_id, event_type, content, self.display_name)
+
+ async def send_media(
+ self,
+ room_id: str,
+ uri: str,
+ filename: str,
+ mimetype: str,
+ size: int,
+ *,
+ sender_name: str,
+ msgtype: str,
+ caption: str | None = None,
+ thread_root_id: str | None = None,
+ group: dict[str, object] | None = None,
+ ) -> SendResult:
+ content = media_content(
+ uri,
+ filename,
+ mimetype,
+ size,
+ sender_name=sender_name,
+ msgtype=msgtype,
+ caption=caption,
+ thread_root_id=thread_root_id,
+ group=group,
+ )
+ return await self._send(room_id, "m.room.message", content, sender_name)
+
+ async def _send(
+ self,
+ transport_room_id: str,
+ event_type: str,
+ content: dict[str, object],
+ sender_name: str,
+ ) -> SendResult:
+ """Write the event, which is what sending it means here.
+
+ The commit is the acceptance: the trigger on `messages` announces the
+ row as part of it, so no subscriber can be woken for a row that a later
+ rollback removes.
+ """
+ result = SendResult(
+ event_id=new_event_id(), event_type=event_type, content=content
+ )
+ if event_type in EPHEMERAL:
+ # Presence-like state, replaced by its own next value. Storing it
+ # would put a row in the room's order for something no reader is
+ # ever shown, so it is delivered live instead of written: the
+ # announcement carries the value, because there is nowhere for a
+ # reader to go and fetch it.
+ await self._ephemeral.publish(
+ transport_room_id,
+ InboundCustomEvent(
+ room_id=transport_room_id,
+ event_id=result.event_id,
+ sender=self.user_id,
+ timestamp=_now_ms(),
+ content=content,
+ event_type=event_type,
+ ),
+ )
+ return result
+
+ async with self._session_factory() as session:
+ room_id = await self._resolve_room(session, transport_room_id)
+ message = Message(
+ room_id=room_id,
+ transport_event_id=result.event_id,
+ sender_matrix_id=self.user_id,
+ sender_client_id=self.client_id,
+ sender_name=sender_name,
+ event_type=event_type,
+ msgtype=text_field(content.get("msgtype")),
+ body=text_field(content.get("body")),
+ formatted_body=text_field(content.get("formatted_body")),
+ thread_root_event_id=thread_root_of(content),
+ content=content,
+ )
+ await self._message_store.create(session, message, attachments_in(content))
+ await session.commit()
+ return result
+
+ async def set_typing(self, room_id: str, is_typing: bool) -> None:
+ """Not carried. Composing state is presence, and nothing consumes it."""
+
+ async def upload_media(
+ self, data: bytes, content_type: str, filename: str
+ ) -> UploadResult:
+ """Store the bytes and return the handle the message will carry.
+
+ The handle is a key and nothing more. Callers already treat it as
+ opaque — it crosses the agent protocol as `mxc` and comes back as a
+ query parameter — so what is behind it can become object storage later
+ without the protocol noticing.
+ """
+ uri = f"switch-media://{uuid.uuid4().hex}"
+ async with self._session_factory() as session:
+ await self._media_store.put(
+ session,
+ MediaBlob(
+ uri=uri,
+ content_type=content_type,
+ filename=filename,
+ size=len(data),
+ data=data,
+ ),
+ )
+ await session.commit()
+ return UploadResult(uri=uri)
+
+ async def download_media(self, uri: str) -> DownloadResult:
+ """The bytes for a handle.
+
+ A handle with nothing behind it raises rather than returning empty
+ bytes: an attachment the sender was told had been stored and a reader
+ gets back as a zero-byte file is the worst of the available answers.
+ """
+ async with self._session_factory() as session:
+ blob = await self._media_store.get(session, uri)
+ if blob is None:
+ raise TransportError(f"No media stored under {uri}")
+ return DownloadResult(
+ body=blob.data,
+ content_type=blob.content_type,
+ filename=blob.filename,
+ )
+
+ # ── History ───────────────────────────────────────────────────────────────
+
+ async def get_event(self, room_id: str, event_id: str) -> Any | None:
+ """One event by id, or None.
+
+ Scoped to the room, so an id from elsewhere cannot be read through it —
+ the caller is resolving a thread root supplied by an agent.
+ """
+ async with self._session_factory() as session:
+ switch_room_id = await self._resolve_room(session, room_id)
+ rows = await self._message_store.list_by_transport_event_ids(
+ session, switch_room_id, [event_id]
+ )
+ return rows[0] if rows else None
+
+ async def read_history(
+ self, room_id: str, *, start: str | None, limit: int
+ ) -> HistoryPage:
+ raise NotImplementedError(
+ "PostgresTransport does not serve history: the read path already "
+ "queries `messages` directly, and the history walkers that use "
+ "this method exist to compare the bus against those same rows."
+ )
+
+ # ── Rooms ─────────────────────────────────────────────────────────────────
+
+ async def join_room(self, room_id: str) -> bool:
+ """Membership is a row, and so is the arrival that announces it.
+
+ Over Matrix these were one thing: the homeserver turned a join into an
+ `m.room.member` event every other member saw, and Switch recorded that
+ event separately so history could explain who appeared. Here the write
+ does both jobs at once, which removes the case the recorder had to
+ guard against — an arrival that happened but was never written.
+
+ Returns True for an existing membership as well as a new one: the
+ caller asked to be in the room, and it is.
+
+ Watching is decided separately from the row, and that split is the
+ point. Membership and subscription used to be one fact — the
+ homeserver's join *was* what a sync loop delivered — but a row can now
+ be written by something other than this client, and a client that
+ returned early on finding one would be a member of a room it never
+ reads, with no later join able to repair it. So the row is written
+ once and the subscription is taken whenever it is missing.
+ """
+ async with self._session_factory() as session:
+ switch_room_id = await self._resolve_room(session, room_id)
+ existing = await session.get(
+ ClientRoom, {"client_id": self.client_id, "room_id": switch_room_id}
+ )
+ if existing is not None:
+ if self._receiving:
+ await self._watch(room_id)
+ return True
+ await self._room_store.add_client(session, self.client_id, switch_room_id)
+ arrival = Message(
+ room_id=switch_room_id,
+ transport_event_id=new_event_id(),
+ sender_matrix_id=self.user_id,
+ sender_client_id=self.client_id,
+ sender_name=self.display_name,
+ event_type=MEMBERSHIP_EVENT_TYPE,
+ msgtype=None,
+ body=None,
+ formatted_body=None,
+ thread_root_event_id=None,
+ # No rendered sentence: how an arrival reads is the reader's to
+ # phrase, and freezing today's wording into every row is not
+ # something a later change can take back.
+ content={"membership": "join", "displayname": self.display_name},
+ )
+ await self._message_store.create(session, arrival, [])
+ await session.commit()
+ arrival_seq = arrival.seq
+ if self._receiving:
+ # From just before the arrival, so this client reads its own join
+ # the way every other member does.
+ await self._watch(room_id, from_seq=arrival_seq - 1)
+ return True
+
+ async def joined_rooms(self) -> list[str]:
+ """The transport-side ids of this client's rooms."""
+ async with self._session_factory() as session:
+ rooms = await self._room_store.get_for_client(session, self.client_id)
+ return [room.matrix_room_id for room in rooms if room.matrix_room_id]
+
+ async def set_display_name(self, display_name: str) -> None:
+ """Held on the client row, which is where every reader already looks."""
+ self.display_name = display_name
+
+ # ── Internals ─────────────────────────────────────────────────────────────
+
+ async def _resolve_room(self, session: AsyncSession, transport_room_id: str) -> str:
+ cached = self._room_ids.get(transport_room_id)
+ if cached is not None:
+ return cached
+ room = await self._room_store.get_by_matrix_room_id(session, transport_room_id)
+ if room is None:
+ raise TransportError(f"{transport_room_id} is not a Switch room")
+ self._room_ids[transport_room_id] = room.id
+ return room.id
+
+
+def to_inbound(
+ row: Message,
+ attachments: list[MessageAttachment],
+ *,
+ transport_room_id: str,
+) -> InboundEvent:
+ """One stored row as the event a handler expects.
+
+ Which of the four inbound shapes a row becomes is read off the row itself,
+ the same way the Matrix transport reads it off the event class: an
+ arrival, a file, a `com.switch.*` payload, or a message. The row keeps the
+ whole content dict, so nothing is reconstructed here that was not sent.
+ """
+ content = dict(row.content)
+ room_id = transport_room_id
+ event_id = row.transport_event_id
+ sender = row.sender_matrix_id
+ timestamp = _epoch_ms(row.sent_at)
+
+ if row.event_type == MEMBERSHIP_EVENT_TYPE:
+ return InboundMembership(
+ room_id=room_id,
+ event_id=event_id,
+ sender=sender,
+ timestamp=timestamp,
+ content=content,
+ state_key=row.sender_matrix_id,
+ membership=text_field(content.get("membership")) or "join",
+ # Only an arrival is ever written, so there is no previous state
+ # to read back — and a row that carries one is honoured rather
+ # than second-guessed.
+ prev_membership=text_field(content.get("prev_membership")),
+ display_name=row.sender_name,
+ )
+
+ if row.event_type != "m.room.message":
+ return InboundCustomEvent(
+ room_id=room_id,
+ event_id=event_id,
+ sender=sender,
+ timestamp=timestamp,
+ content=content,
+ event_type=row.event_type,
+ thread_root_id=row.thread_root_event_id,
+ )
+
+ if not attachments:
+ return InboundMessage(
+ room_id=room_id,
+ event_id=event_id,
+ sender=sender,
+ timestamp=timestamp,
+ content=content,
+ body=row.body or "",
+ sender_name=row.sender_name,
+ formatted_body=row.formatted_body,
+ msgtype=row.msgtype or "m.text",
+ thread_root_id=row.thread_root_event_id,
+ )
+
+ file = attachments[0]
+ group = content.get(ATTACHMENT_GROUP_KEY)
+ return InboundMedia(
+ room_id=room_id,
+ event_id=event_id,
+ sender=sender,
+ timestamp=timestamp,
+ content=content,
+ body=row.body or "",
+ sender_name=row.sender_name,
+ formatted_body=row.formatted_body,
+ msgtype=row.msgtype or "m.file",
+ thread_root_id=row.thread_root_event_id,
+ uri=file.uri,
+ filename=file.filename,
+ mimetype=file.mimetype,
+ size=file.size,
+ group=group if isinstance(group, dict) else None,
+ )
+
+
+def _now_ms() -> int:
+ return int(datetime.now(UTC).timestamp() * 1000)
+
+
+def _epoch_ms(sent_at: Any) -> int:
+ return int(sent_at.timestamp() * 1000)
diff --git a/core/switch_core/transport/types.py b/core/switch_core/transport/types.py
new file mode 100644
index 000000000..1e934f332
--- /dev/null
+++ b/core/switch_core/transport/types.py
@@ -0,0 +1,150 @@
+"""Transport-neutral types crossing the message-transport boundary.
+
+Nothing here names Matrix. Identifiers are opaque strings: an `event_id` is
+whatever the transport calls a message handle, and `uri` is whatever it calls
+an uploaded blob. Callers must not parse either.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+MessageFormat = Literal["text", "markdown"]
+SeekDirection = Literal["forward", "backward"]
+
+
+class TransportError(RuntimeError):
+ """A transport operation failed.
+
+ Operations raise this rather than returning an error object, so a caller
+ cannot proceed on a failure it forgot to check.
+ """
+
+
+class NotConnectedError(TransportError):
+ """An operation was attempted before the transport was connected."""
+
+
+# ── Outbound results ──────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class SendResult:
+ """A message or event accepted by the transport.
+
+ `event_type` and `content` are what was actually put on the wire, which
+ the transport assembles and the caller therefore does not otherwise see.
+ Reporting them back means a caller recording what it sent transcribes the
+ transport's own dict rather than reconstructing it and drifting from it.
+ """
+
+ event_id: str
+ event_type: str
+ content: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class UploadResult:
+ """A blob accepted by the transport's media store."""
+
+ uri: str
+
+
+@dataclass(frozen=True)
+class DownloadResult:
+ """Bytes retrieved for a media URI."""
+
+ body: bytes
+ content_type: str | None = None
+ filename: str | None = None
+
+
+# ── Inbound events ────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class RoomRef:
+ """The room an inbound event arrived in.
+
+ Consumers only ever needed the id; this exists so handler signatures do not
+ have to name a transport's room object.
+ """
+
+ room_id: str
+
+
+@dataclass(frozen=True)
+class InboundEvent:
+ """Fields common to every inbound event."""
+
+ room_id: str
+ event_id: str
+ sender: str
+ timestamp: int
+ content: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class InboundMessage(InboundEvent):
+ """A text message.
+
+ `content` is retained deliberately: `com.switch.*` markers ride on ordinary
+ messages, and hiding them behind named fields would mean a new field for
+ every marker.
+ """
+
+ body: str = ""
+ sender_name: str | None = None
+ formatted_body: str | None = None
+ msgtype: str = "m.text"
+ thread_root_id: str | None = None
+
+
+@dataclass(frozen=True)
+class InboundMedia(InboundMessage):
+ """An attachment. `uri` is the handle to pass back to `download_media`.
+
+ A media event is a message that happens to carry a file, so code that only
+ cares about sender, body or thread can treat the two alike.
+ """
+
+ uri: str = ""
+ filename: str | None = None
+ mimetype: str | None = None
+ size: int | None = None
+ group: dict[str, object] | None = None
+
+
+@dataclass(frozen=True)
+class InboundMembership(InboundEvent):
+ """A membership change.
+
+ `state_key` names the member the change is about, which is not the same as
+ `sender` — one member can change another's membership.
+ """
+
+ state_key: str = ""
+ membership: str = ""
+ prev_membership: str | None = None
+ display_name: str | None = None
+
+
+@dataclass(frozen=True)
+class InboundCustomEvent(InboundEvent):
+ """A non-message event carrying a `com.switch.*` payload in `content`."""
+
+ event_type: str = ""
+ thread_root_id: str | None = None
+
+
+@dataclass(frozen=True)
+class HistoryPage:
+ """One page of backwards history.
+
+ `next_token` is an opaque cursor for the following page, or None when the
+ transport reports no more history.
+ """
+
+ events: list[object]
+ next_token: str | None
diff --git a/core/tests/integration/conftest.py b/core/tests/integration/conftest.py
index cc0be4289..9e2099852 100644
--- a/core/tests/integration/conftest.py
+++ b/core/tests/integration/conftest.py
@@ -49,16 +49,18 @@ from switch_core.bridges.agent.protocol.types import (
RegistrationResult,
TaskProtocolConfig,
)
-from switch_core.bridges.agent.request_tracker import RequestTracker
from switch_core.bridges.resource.service import ResourceService
-from switch_core.bridges.resource.tracker import ResourceRequestTracker
from switch_core.clients.agent_client import AgentClient
from switch_core.clients.client_base import ClientBase
from switch_core.clients.client_factory import ClientFactory
from switch_core.clients.client_lifecycle_service import ClientLifecycleService
from switch_core.config import SwitchConfig
from switch_core.db.base import Base
-from switch_core.db.engine import create_engine_from_config, create_session_factory
+from switch_core.db.engine import (
+ create_engine_from_config,
+ create_session_factory,
+ create_unpooled_engine,
+)
from switch_core.db.models import User
from switch_core.db.stores.agent_session_store import AgentSessionStore
from switch_core.db.stores.agent_store import AgentStore
@@ -67,6 +69,8 @@ from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStore
from switch_core.db.stores.document_store import DocumentStore
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.package_store import PackageStore
from switch_core.db.stores.reference_store import ReferenceStore
from switch_core.db.stores.reference_type_store import ReferenceTypeStore
@@ -80,7 +84,11 @@ from switch_core.matrix_admin import (
ensure_admin_exists,
wait_for_homeserver,
)
+from switch_core.messages import MessageRecorder
+from switch_core.messages.notify import MessageListener
from switch_core.room_service import RoomService
+from switch_core.transport.ephemeral import EphemeralBus
+from switch_core.transport.invites import InviteBus
# ── Mirrors deploy/local/docker-compose.yml — keep in sync ──────────────────────
POSTGRES_IMAGE = "postgres:16-alpine"
@@ -437,8 +445,6 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:
# events and client registrations never leak across tests.
event_buffer = EventBuffer()
connections = ConnectionRegistry()
- request_tracker = RequestTracker()
- resource_request_tracker = ResourceRequestTracker()
collab_lifecycle = _NoBridges()
resource_service = ResourceService(
@@ -454,6 +460,17 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:
client_store=session_env.client_store,
session_factory=session_factory,
config=config,
+ message_recorder=MessageRecorder(
+ session_factory=session_factory,
+ room_store=session_env.room_store,
+ message_store=MessageStore(),
+ ),
+ room_store=session_env.room_store,
+ message_store=MessageStore(),
+ media_store=MediaStore(),
+ listener=MessageListener(lambda: create_unpooled_engine(config)),
+ invites=InviteBus(),
+ ephemeral=EphemeralBus(),
)
client_factory.register(
"agent",
@@ -467,8 +484,6 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:
agent_session_store=session_env.agent_session_store,
room_role_store=session_env.room_role_store,
external_user_store=session_env.external_user_store,
- request_tracker=request_tracker,
- resource_request_tracker=resource_request_tracker,
connections=connections,
frontend_base_url=config.frontend_base_url,
)
@@ -503,8 +518,6 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:
collab_lifecycle=collab_lifecycle, # type: ignore[arg-type]
event_buffer=event_buffer,
task_store=session_env.task_store,
- request_tracker=request_tracker,
- resource_request_tracker=resource_request_tracker,
resource_service=resource_service,
api_key_store=session_env.api_key_store,
api_key_cache=ApiKeyCache(
diff --git a/core/tests/switch_core/bridges/agent/protocol/test_read_context.py b/core/tests/switch_core/bridges/agent/protocol/test_read_context.py
new file mode 100644
index 000000000..76064c5a8
--- /dev/null
+++ b/core/tests/switch_core/bridges/agent/protocol/test_read_context.py
@@ -0,0 +1,593 @@
+"""read_context, now that history comes from the message log.
+
+The homeserver page-walk is gone, and with it the seek budget, the read budget
+and the per-thread root refetch. What replaces them is a single windowed query,
+so these tests write rows and read them back rather than feeding pages to a
+fake transport.
+
+Two behaviours are worth naming because they changed rather than moved:
+`truncated` is exact — the query asks for one row more than the caller wanted
+and reports whether it exists — and an arrival is stored with no body, so the
+sentence a reader sees is composed here and can be reworded without rewriting
+history.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+from types import SimpleNamespace
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.attachments import ATTACHMENT_GROUP_KEY
+from switch_core.bridges.agent.protocol.connections import ConnectionRegistry
+from switch_core.bridges.agent.protocol.service import ProtocolService
+from switch_core.db.models import Client, Message, MessageAttachment, Room
+from switch_core.db.stores.message_store import MessageStore
+
+BASE = datetime(2026, 1, 1, 12, 0, tzinfo=UTC)
+
+
+def _at(seconds: int) -> datetime:
+ return BASE + timedelta(seconds=seconds)
+
+
+def _ms(seconds: int) -> int:
+ return int(_at(seconds).timestamp() * 1000)
+
+
+async def _make_room(session: AsyncSession) -> tuple[str, str]:
+ """Insert the Room and Client a recorded row depends on."""
+ suffix = uuid.uuid4().hex[:8]
+ client = Client(
+ matrix_user_id=f"@agent-{suffix}:test",
+ display_name="agent one",
+ type="agent",
+ password="x",
+ )
+ session.add(client)
+ await session.flush()
+ room = Room(
+ matrix_room_id=f"!room-{suffix}:test",
+ name="a room",
+ description="",
+ )
+ session.add(room)
+ await session.flush()
+ return room.id, client.id
+
+
+async def _write(
+ session: AsyncSession,
+ room_id: str,
+ client_id: str,
+ event_id: str,
+ *,
+ body: str | None = "hello",
+ at: int = 0,
+ sender: str = "@alice:s",
+ sender_name: str | None = "Alice",
+ thread_root: str | None = None,
+ event_type: str = "m.room.message",
+ msgtype: str | None = "m.text",
+ attachments: list[MessageAttachment] | None = None,
+ content: dict[str, object] | None = None,
+) -> Message:
+ message = Message(
+ room_id=room_id,
+ transport_event_id=event_id,
+ sender_matrix_id=sender,
+ sender_client_id=client_id,
+ sender_name=sender_name,
+ event_type=event_type,
+ msgtype=msgtype,
+ body=body,
+ formatted_body=None,
+ thread_root_event_id=thread_root,
+ content=content if content is not None else ({"body": body} if body else {}),
+ sent_at=_at(at),
+ )
+ return await MessageStore().create(session, message, attachments or [])
+
+
+def _service(session_factory: async_sessionmaker[AsyncSession]) -> ProtocolService:
+ async def _require(agent_id: str, room_id: str):
+ return SimpleNamespace(id=room_id)
+
+ svc = object.__new__(ProtocolService)
+ svc.connections = ConnectionRegistry()
+ svc.session_factory = session_factory
+ svc.message_store = MessageStore()
+ svc.require_room_member = _require # type: ignore[assignment]
+ return svc
+
+
+class TestEntries:
+ async def test_a_message_is_its_own_thread(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(session, room_id, client_id, "$txt", body="hello")
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert len(result["threads"]) == 1
+ root = result["threads"][0]["root"]
+ assert root["id"] == "$txt"
+ assert root["kind"] == "message"
+ assert root["body"] == "hello"
+ assert root["sender"] == "@alice:s"
+ assert root["sender_name"] == "Alice"
+ assert root["timestamp"] == _ms(0)
+ assert root["attachments"] == []
+
+ async def test_a_file_comes_back_with_the_message(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(
+ session,
+ room_id,
+ client_id,
+ "$img",
+ body="what's this?",
+ msgtype="m.image",
+ attachments=[
+ MessageAttachment(
+ uri="mxc://s/abc",
+ filename="cat.png",
+ mimetype="image/png",
+ size=1234,
+ position=0,
+ )
+ ],
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert result["threads"][0]["root"]["attachments"] == [
+ {
+ "filename": "cat.png",
+ "mimetype": "image/png",
+ "size": 1234,
+ "mxc": "mxc://s/abc",
+ "msgtype": "m.image",
+ }
+ ]
+
+ async def test_several_files_come_back_on_one_message(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """In the order they were sent, which is what `position` records."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(
+ session,
+ room_id,
+ client_id,
+ "$multi",
+ body="two files",
+ msgtype="m.file",
+ attachments=[
+ MessageAttachment(uri="mxc://s/one", filename="one.pdf"),
+ MessageAttachment(uri="mxc://s/two", filename="two.pdf"),
+ ],
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ names = [a["filename"] for a in result["threads"][0]["root"]["attachments"]]
+ assert names == ["one.pdf", "two.pdf"]
+
+ async def test_a_multi_file_message_is_reassembled_from_its_parts(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The bus has no event that carries two files, so a two-file message
+ is two events sharing a group marker and two rows. History has to put
+ them back together the way a live receiver does — otherwise it reads as
+ two messages, the second captioned with a filename."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ for index, (event_id, body, name) in enumerate(
+ [("$part0", "two files", "one.pdf"), ("$part1", "two.pdf", "two.pdf")]
+ ):
+ await _write(
+ session,
+ room_id,
+ client_id,
+ event_id,
+ body=body,
+ at=index,
+ msgtype="m.file",
+ attachments=[
+ MessageAttachment(uri=f"mxc://s/{name}", filename=name)
+ ],
+ content={
+ "body": body,
+ ATTACHMENT_GROUP_KEY: {"id": "g1", "index": index, "total": 2},
+ },
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert len(result["threads"]) == 1
+ root = result["threads"][0]["root"]
+ assert root["id"] == "$part0"
+ assert root["body"] == "two files"
+ assert [a["filename"] for a in root["attachments"]] == ["one.pdf", "two.pdf"]
+
+ async def test_a_group_cut_off_by_the_window_returns_what_is_there(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A page ending mid-group shows the parts it read rather than dropping
+ them: the lowest index present leads."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(
+ session,
+ room_id,
+ client_id,
+ "$part1",
+ body="two.pdf",
+ at=1,
+ msgtype="m.file",
+ attachments=[MessageAttachment(uri="mxc://s/two", filename="two.pdf")],
+ content={
+ "body": "two.pdf",
+ ATTACHMENT_GROUP_KEY: {"id": "g1", "index": 1, "total": 2},
+ },
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ root = result["threads"][0]["root"]
+ assert root["id"] == "$part1"
+ assert [a["filename"] for a in root["attachments"]] == ["two.pdf"]
+
+ async def test_an_arrival_is_labelled_and_phrased_on_read(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The row holds no sentence; this is where one is composed."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(
+ session,
+ room_id,
+ client_id,
+ "$join",
+ body=None,
+ msgtype=None,
+ event_type="m.room.member",
+ sender="@bob:s",
+ sender_name="Bob",
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ root = result["threads"][0]["root"]
+ assert root["kind"] == "room_join"
+ assert root["body"] == "Bob joined the room"
+ assert root["sender"] == "@bob:s"
+
+ async def test_an_unnamed_sender_falls_back_to_their_address(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(
+ session, room_id, client_id, "$anon", sender_name=None, sender="@x:s"
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert result["threads"][0]["root"]["sender_name"] == "@x:s"
+
+
+class TestTruncation:
+ """`truncated` is now exact rather than conservative.
+
+ The old walk could not tell "the page cap stopped me" from "the room ended
+ there", so it reported truncated whenever it ended on the limit. One extra
+ row answers the question outright.
+ """
+
+ async def test_a_room_shorter_than_the_limit_is_not_truncated(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ for n in range(3):
+ await _write(session, room_id, client_id, f"$m{n}", at=n)
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, limit=10
+ )
+
+ assert result["truncated"] is False
+ assert len(result["threads"]) == 3
+
+ async def test_a_room_exactly_the_limit_is_not_truncated(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The case the old walk had to guess at, and always guessed wrong."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ for n in range(3):
+ await _write(session, room_id, client_id, f"$m{n}", at=n)
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, limit=3
+ )
+
+ assert result["truncated"] is False
+ assert len(result["threads"]) == 3
+
+ async def test_older_history_beyond_the_limit_is_reported(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ for n in range(5):
+ await _write(session, room_id, client_id, f"$m{n}", at=n)
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, limit=3
+ )
+
+ assert result["truncated"] is True
+ assert len(result["threads"]) == 3
+
+ async def test_the_newest_entries_are_the_ones_kept(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ for n in range(5):
+ await _write(session, room_id, client_id, f"$m{n}", at=n)
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, limit=2
+ )
+
+ assert [t["root"]["id"] for t in result["threads"]] == ["$m3", "$m4"]
+ assert result["oldest_timestamp"] == _ms(3)
+
+ async def test_an_empty_room_reads_as_empty_not_truncated(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, _ = await _make_room(session)
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert result == {
+ "threads": [],
+ "truncated": False,
+ "oldest_timestamp": None,
+ }
+
+
+class TestWindowing:
+ async def test_before_excludes_the_boundary(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ for n in range(4):
+ await _write(session, room_id, client_id, f"$m{n}", at=n)
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, before_ms=_ms(2)
+ )
+
+ assert [t["root"]["id"] for t in result["threads"]] == ["$m0", "$m1"]
+
+ async def test_since_includes_the_boundary(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ for n in range(4):
+ await _write(session, room_id, client_id, f"$m{n}", at=n)
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, since_ms=_ms(2)
+ )
+
+ assert [t["root"]["id"] for t in result["threads"]] == ["$m2", "$m3"]
+
+ async def test_a_window_far_from_the_present_costs_one_query(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The old path had to page over everything newer to arrive here, and
+ gave up loudly when the seek budget ran out."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ for n in range(200):
+ await _write(session, room_id, client_id, f"$m{n}", at=n)
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, limit=2, since_ms=_ms(3), before_ms=_ms(6)
+ )
+
+ assert [t["root"]["id"] for t in result["threads"]] == ["$m4", "$m5"]
+ assert result["truncated"] is True
+
+ async def test_other_rooms_are_not_visible(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ other_id, other_client = await _make_room(session)
+ await _write(session, room_id, client_id, "$mine")
+ await _write(session, other_id, other_client, "$theirs")
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert [t["root"]["id"] for t in result["threads"]] == ["$mine"]
+
+
+class TestThreads:
+ async def test_replies_group_under_their_root_oldest_first(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(session, room_id, client_id, "$root", body="q", at=0)
+ await _write(
+ session, room_id, client_id, "$r1", body="a", at=1, thread_root="$root"
+ )
+ await _write(
+ session, room_id, client_id, "$r2", body="b", at=2, thread_root="$root"
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert len(result["threads"]) == 1
+ thread = result["threads"][0]
+ assert thread["root"]["id"] == "$root"
+ assert [r["id"] for r in thread["replies"]] == ["$r1", "$r2"]
+
+ async def test_threads_are_ordered_by_latest_activity(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Freshest last, so the tail of the list is what just happened."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(session, room_id, client_id, "$a", at=0)
+ await _write(session, room_id, client_id, "$b", at=1)
+ await _write(session, room_id, client_id, "$a1", at=5, thread_root="$a")
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert [t["root"]["id"] for t in result["threads"]] == ["$b", "$a"]
+
+ async def test_a_root_older_than_the_window_is_still_returned(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A reply whose root fell outside the window keeps its root, fetched
+ for the whole page at once rather than one query per thread."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(session, room_id, client_id, "$root", body="q", at=0)
+ for n in range(3):
+ await _write(session, room_id, client_id, f"$noise{n}", at=n + 1)
+ await _write(
+ session,
+ room_id,
+ client_id,
+ "$late",
+ body="a",
+ at=9,
+ thread_root="$root",
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, limit=2
+ )
+
+ threads = {t["root"]["id"]: t for t in result["threads"]}
+ assert "$root" in threads
+ assert threads["$root"]["root"]["body"] == "q"
+ assert [r["id"] for r in threads["$root"]["replies"]] == ["$late"]
+
+ async def test_a_root_with_no_recorded_row_is_elided_not_dropped(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Losing the root must not take the replies with it."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(
+ session,
+ room_id,
+ client_id,
+ "$orphan",
+ body="a",
+ thread_root="$vanished",
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert len(result["threads"]) == 1
+ thread = result["threads"][0]
+ assert thread["root"] == {
+ "id": "$vanished",
+ "kind": "message",
+ "sender": None,
+ "sender_name": None,
+ "body": None,
+ "timestamp": None,
+ "elided": True,
+ }
+ assert [r["id"] for r in thread["replies"]] == ["$orphan"]
+
+ async def test_a_root_in_another_room_is_not_borrowed(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Resolving roots is scoped to the room, so an id cannot be read
+ across a room boundary by claiming it as a thread parent."""
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ other_id, other_client = await _make_room(session)
+ await _write(session, other_id, other_client, "$elsewhere", body="secret")
+ await _write(
+ session, room_id, client_id, "$reply", thread_root="$elsewhere"
+ )
+ await session.commit()
+
+ result = await _service(session_factory).read_context("agent-1", room_id)
+
+ assert result["threads"][0]["root"]["elided"] is True
+
+
+class TestLimits:
+ async def test_an_absurd_limit_is_clamped(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(session, room_id, client_id, "$m")
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, limit=10_000
+ )
+
+ assert len(result["threads"]) == 1
+
+ async def test_a_nonsense_limit_still_returns_something(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, client_id = await _make_room(session)
+ await _write(session, room_id, client_id, "$m")
+ await session.commit()
+
+ result = await _service(session_factory).read_context(
+ "agent-1", room_id, limit=0
+ )
+
+ assert len(result["threads"]) == 1
diff --git a/core/tests/switch_core/bridges/agent/protocol/test_read_context_attachments.py b/core/tests/switch_core/bridges/agent/protocol/test_read_context_attachments.py
deleted file mode 100644
index 07a1575a4..000000000
--- a/core/tests/switch_core/bridges/agent/protocol/test_read_context_attachments.py
+++ /dev/null
@@ -1,93 +0,0 @@
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-import nio
-
-from switch_core.bridges.agent.protocol.connections import ConnectionRegistry
-from switch_core.bridges.agent.protocol.service import ProtocolService
-
-
-def _image_event() -> nio.RoomMessageImage:
- return nio.RoomMessageImage.from_dict(
- {
- "type": "m.room.message",
- "event_id": "$img",
- "sender": "@alice:s",
- "origin_server_ts": 1700000000000,
- "content": {
- "msgtype": "m.image",
- "body": "what's this?",
- "filename": "cat.png",
- "url": "mxc://s/abc",
- "info": {"mimetype": "image/png", "size": 1234},
- "sender_name": "Alice",
- },
- }
- )
-
-
-def _text_event() -> nio.RoomMessageText:
- return nio.RoomMessageText.from_dict(
- {
- "type": "m.room.message",
- "event_id": "$txt",
- "sender": "@bob:s",
- "origin_server_ts": 1700000001000,
- "content": {"msgtype": "m.text", "body": "hello", "sender_name": "Bob"},
- }
- )
-
-
-def _build_service(chunk: list[object]) -> ProtocolService:
- async def _room_messages(matrix_room_id: str, start: str | None, limit: int):
- # No continuation token: this page is the start of the room.
- return SimpleNamespace(chunk=chunk, end=None)
-
- fake_client = SimpleNamespace(
- nio_client=SimpleNamespace(room_messages=_room_messages)
- )
-
- async def _require(agent_id: str, room_id: str):
- return SimpleNamespace(matrix_room_id="!room")
-
- svc = object.__new__(ProtocolService)
- # Presence unions the heartbeat rows with the live connections
- # (CHOO-1857); an empty registry means "rows only".
- svc.connections = ConnectionRegistry()
- svc.require_room_member = _require # type: ignore[assignment]
- svc.client_lifecycle = SimpleNamespace( # type: ignore[assignment]
- get_by_agent_id=lambda agent_id: fake_client
- )
- return svc
-
-
-async def test_image_event_carries_attachment() -> None:
- svc = _build_service([_image_event()])
-
- # read_context returns thread groups; a standalone message is its own root.
- groups = (await svc.read_context("agent-1", "room-1"))["threads"]
-
- assert len(groups) == 1
- root = groups[0]["root"]
- assert root["body"] == "what's this?"
- assert root["attachments"] == [
- {
- "filename": "cat.png",
- "mimetype": "image/png",
- "size": 1234,
- "mxc": "mxc://s/abc",
- "msgtype": "m.image",
- }
- ]
-
-
-async def test_text_event_has_empty_attachments() -> None:
- svc = _build_service([_text_event()])
-
- groups = (await svc.read_context("agent-1", "room-1"))["threads"]
-
- assert len(groups) == 1
- root = groups[0]["root"]
- assert root["body"] == "hello"
- assert root["attachments"] == []
diff --git a/core/tests/switch_core/bridges/agent/protocol/test_read_context_pagination.py b/core/tests/switch_core/bridges/agent/protocol/test_read_context_pagination.py
deleted file mode 100644
index b2e29979b..000000000
--- a/core/tests/switch_core/bridges/agent/protocol/test_read_context_pagination.py
+++ /dev/null
@@ -1,268 +0,0 @@
-"""read_context must page the homeserver, not read one page and stop.
-
-The bug this covers (CHOO-2034): a single /messages call returned whatever
-fitted in one server-capped page, state events ate into that page, and `since`
-/ `before` were applied as filters over it — so `before` could never reach
-older history and a truncated read was indistinguishable from a complete one.
-"""
-
-from __future__ import annotations
-
-from types import SimpleNamespace
-from typing import Any
-
-import nio
-
-from switch_core.bridges.agent.protocol import service
-from switch_core.bridges.agent.protocol.connections import ConnectionRegistry
-from switch_core.bridges.agent.protocol.service import ProtocolService
-
-
-def _msg(event_id: str, ts: int, body: str = "hi") -> SimpleNamespace:
- return SimpleNamespace(
- event_id=event_id,
- sender="@u:s",
- server_timestamp=ts,
- body=body,
- source={"content": {"sender_name": "U"}},
- )
-
-
-def _join(event_id: str, ts: int, user: str, displayname: str) -> nio.RoomMemberEvent:
- return nio.RoomMemberEvent.from_dict(
- {
- "type": "m.room.member",
- "event_id": event_id,
- "sender": user,
- "state_key": user,
- "origin_server_ts": ts,
- "content": {"membership": "join", "displayname": displayname},
- }
- )
-
-
-def _rename(event_id: str, ts: int, user: str, displayname: str) -> nio.RoomMemberEvent:
- """A display-name change: membership join, but they were already here."""
- return nio.RoomMemberEvent.from_dict(
- {
- "type": "m.room.member",
- "event_id": event_id,
- "sender": user,
- "state_key": user,
- "origin_server_ts": ts,
- "content": {"membership": "join", "displayname": displayname},
- "unsigned": {"prev_content": {"membership": "join"}},
- }
- )
-
-
-class _PagedNio:
- """Homeserver stand-in that hands out history one page at a time.
-
- `seek_to` mimics a server that answers timestamp_to_event: the page index
- the token lands on. None means the server cannot answer, so the caller has
- to scan back instead.
- """
-
- access_token = "tok"
-
- def __init__(self, pages: list[list[Any]], seek_to: int | None = None) -> None:
- self._pages = pages
- self._seek_to = seek_to
- self.requested_starts: list[str | None] = []
-
- async def room_messages(
- self, room_id: str, start: str | None = None, limit: int = 0
- ) -> SimpleNamespace:
- self.requested_starts.append(start)
- index = 0 if start is None else int(start)
- if index >= len(self._pages):
- return SimpleNamespace(chunk=[], end=None)
- is_last = index == len(self._pages) - 1
- return SimpleNamespace(
- chunk=self._pages[index],
- end=None if is_last else str(index + 1),
- )
-
- async def send(self, method: str, path: str, headers: Any = None) -> Any:
- if self._seek_to is None:
- return SimpleNamespace(status=404)
-
- async def _json() -> dict[str, str]:
- return {"event_id": "$anchor"}
-
- return SimpleNamespace(status=200, json=_json)
-
- async def room_context(self, room_id: str, event_id: str, limit: int = 1) -> Any:
- return SimpleNamespace(start=str(self._seek_to))
-
- async def room_get_event(self, room_id: str, event_id: str) -> Any:
- return object.__new__(nio.RoomGetEventError)
-
-
-def _service(nio_client: _PagedNio) -> ProtocolService:
- svc = object.__new__(ProtocolService)
- svc.connections = ConnectionRegistry()
-
- async def _require(agent_id: str, room_id: str) -> SimpleNamespace:
- return SimpleNamespace(matrix_room_id="!room:s")
-
- svc.require_room_member = _require # type: ignore[assignment]
- svc.client_lifecycle = SimpleNamespace( # type: ignore[assignment]
- get_by_agent_id=lambda agent_id: SimpleNamespace(nio_client=nio_client)
- )
- return svc
-
-
-def _roots(result: dict[str, Any]) -> list[str]:
- return [g["root"]["id"] for g in result["threads"]]
-
-
-class TestPagination:
- async def test_follows_continuation_token_across_pages(self) -> None:
- # Three pages of one message each — the old code saw only the first.
- nio_client = _PagedNio(
- [[_msg("e3", 300)], [_msg("e2", 200)], [_msg("e1", 100)]]
- )
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=10)
-
- assert sorted(_roots(result)) == ["e1", "e2", "e3"]
- assert nio_client.requested_starts == [None, "1", "2"]
-
- async def test_state_events_do_not_consume_the_message_budget(self) -> None:
- # A page full of events that reach nobody must not end the read.
- noise = [
- SimpleNamespace(
- event_id=f"$n{i}",
- sender="@s:s",
- server_timestamp=500 - i,
- body=None,
- source={"content": {}},
- )
- for i in range(20)
- ]
- nio_client = _PagedNio([noise, [_msg("e1", 100)]])
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=5)
-
- assert _roots(result) == ["e1"]
-
- async def test_stops_at_limit_and_reports_truncated(self) -> None:
- nio_client = _PagedNio([[_msg("e3", 300), _msg("e2", 200)], [_msg("e1", 100)]])
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=2)
-
- assert sorted(_roots(result)) == ["e2", "e3"]
- assert result["truncated"] is True
- assert result["oldest_timestamp"] == 200
-
- async def test_reaching_room_start_is_not_truncated(self) -> None:
- nio_client = _PagedNio([[_msg("e2", 200)], [_msg("e1", 100)]])
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=50)
-
- assert result["truncated"] is False
- assert result["oldest_timestamp"] == 100
-
-
-class TestWindowing:
- async def test_before_pages_backwards_instead_of_filtering(self) -> None:
- # Everything older than the cutoff lives on later pages. The old code
- # filtered page one, found nothing, and returned empty.
- nio_client = _PagedNio(
- [
- [_msg("new2", 900), _msg("new1", 800)],
- [_msg("old2", 200), _msg("old1", 100)],
- ]
- )
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=10, before_ms=500)
-
- assert sorted(_roots(result)) == ["old1", "old2"]
-
- async def test_seeking_to_the_window_does_not_spend_the_read_budget(self) -> None:
- # The bug Louis hit: reaching a `before` deep in a busy room meant
- # paging over everything newer, and those pages came out of the same
- # budget as the read — so a far-enough-back window returned nothing at
- # all, and raising `limit` could not help because `limit` never
- # governed the walk.
- newer = [
- [_msg(f"n{p}{i}", 10_000 - p * 100 - i) for i in range(50)]
- for p in range(service.HISTORY_MAX_PAGES + 5)
- ]
- pages = [*newer, [_msg("wanted", 100)]]
- svc = _service(_PagedNio(pages))
-
- result = await svc.read_context("agent", "room", limit=10, before_ms=500)
-
- assert _roots(result) == ["wanted"]
-
- async def test_gives_up_loudly_rather_than_scanning_forever(self) -> None:
- endless = [[_msg(f"n{p}", 10_000 - p)] for p in range(200)]
- svc = _service(_PagedNio(endless))
-
- result = await svc.read_context("agent", "room", limit=10, before_ms=500)
-
- # Nothing was reachable, and the caller is told so rather than being
- # handed an empty list that looks like "the room is empty".
- assert result["threads"] == []
- assert result["truncated"] is True
-
- async def test_uses_the_server_timestamp_anchor_when_offered(self) -> None:
- pages = [
- [_msg("new", 9_000)],
- [_msg("old", 100)],
- ]
- nio_client = _PagedNio(pages, seek_to=1)
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=10, before_ms=500)
-
- assert _roots(result) == ["old"]
- # Jumped straight to the window instead of paging over page 0.
- assert nio_client.requested_starts == ["1"]
-
- async def test_since_stops_the_walk_once_the_window_is_covered(self) -> None:
- nio_client = _PagedNio([[_msg("e2", 900)], [_msg("e1", 100)]])
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=50, since_ms=500)
-
- assert _roots(result) == ["e2"]
- # The window was fully covered — this is not a truncated read.
- assert result["truncated"] is False
-
-
-class TestJoins:
- async def test_join_appears_in_the_timeline(self) -> None:
- nio_client = _PagedNio([[_join("$j", 100, "@alice:s", "Alice")]])
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=10)
-
- entry = result["threads"][0]["root"]
- assert entry["kind"] == "room_join"
- assert entry["body"] == "Alice joined the room"
- assert entry["sender"] == "@alice:s"
-
- async def test_display_name_change_is_not_an_arrival(self) -> None:
- nio_client = _PagedNio([[_rename("$r", 100, "@alice:s", "Alice II")]])
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=10)
-
- assert result["threads"] == []
-
- async def test_messages_are_labelled_as_messages(self) -> None:
- nio_client = _PagedNio([[_msg("e1", 100)]])
- svc = _service(nio_client)
-
- result = await svc.read_context("agent", "room", limit=10)
-
- assert result["threads"][0]["root"]["kind"] == "message"
diff --git a/core/tests/switch_core/bridges/agent/protocol/test_threads.py b/core/tests/switch_core/bridges/agent/protocol/test_threads.py
index f5ebef013..1d5641098 100644
--- a/core/tests/switch_core/bridges/agent/protocol/test_threads.py
+++ b/core/tests/switch_core/bridges/agent/protocol/test_threads.py
@@ -1,13 +1,13 @@
from __future__ import annotations
from types import SimpleNamespace
-from typing import Any
import pytest
-from nio import RoomGetEventError
from switch_core.bridges.agent.protocol.connections import ConnectionRegistry
from switch_core.bridges.agent.protocol.service import ProtocolService
+from switch_core.transport import HistoryPage, InboundMessage
+from tests.switch_core.transport.fake import FakeTransport
def _ev(
@@ -17,44 +17,21 @@ def _ev(
*,
thread_root: str | None = None,
sender: str = "@u:server",
-) -> SimpleNamespace:
- content: dict[str, Any] = {"sender_name": "U"}
- if thread_root is not None:
- content["m.relates_to"] = {"rel_type": "m.thread", "event_id": thread_root}
- return SimpleNamespace(
+) -> InboundMessage:
+ return InboundMessage(
+ room_id="!matrix:server",
event_id=event_id,
sender=sender,
- server_timestamp=ts,
+ timestamp=ts,
+ content={"sender_name": "U"},
body=body,
- source={"content": content},
+ sender_name="U",
+ thread_root_id=thread_root,
)
-class _FakeNio:
- """Minimal nio AsyncClient stand-in for read paths."""
-
- def __init__(
- self,
- chunk: list[SimpleNamespace] | None = None,
- events: dict[str, SimpleNamespace] | None = None,
- ) -> None:
- self._chunk = chunk or []
- self._events = events or {}
-
- async def room_messages(
- self, room_id: str, start: str | None = None, limit: int = 0
- ) -> SimpleNamespace:
- return SimpleNamespace(chunk=self._chunk, end=None)
-
- async def room_get_event(self, room_id: str, event_id: str) -> Any:
- ev = self._events.get(event_id)
- if ev is None:
- return object.__new__(RoomGetEventError)
- return SimpleNamespace(event=ev)
-
-
-def _service_with_client(nio: _FakeNio) -> ProtocolService:
- client = SimpleNamespace(nio_client=nio)
+def _service_with_transport(transport: FakeTransport) -> ProtocolService:
+ client = SimpleNamespace(transport=transport)
svc = object.__new__(ProtocolService)
# Presence unions the heartbeat rows with the live connections
# (CHOO-1857); an empty registry means "rows only".
@@ -70,10 +47,21 @@ def _service_with_client(nio: _FakeNio) -> ProtocolService:
return svc
+def _transport(
+ chunk: list[InboundMessage] | None = None,
+ events: dict[str, InboundMessage] | None = None,
+) -> FakeTransport:
+ # No continuation token: the single page is the start of the room.
+ transport = FakeTransport(
+ history=HistoryPage(events=list(chunk or []), next_token=None)
+ )
+ transport.events_by_id = dict(events or {})
+ return transport
+
+
class TestResolveThreadRoot:
async def test_passthrough_for_root(self) -> None:
- nio = _FakeNio(events={"e1": _ev("e1", "root", 100)})
- svc = _service_with_client(nio)
+ svc = _service_with_transport(_transport(events={"e1": _ev("e1", "root", 100)}))
client = svc.client_lifecycle.get_by_agent_id("a")
root = await svc._resolve_thread_root(client, "!m:s", "e1")
@@ -81,8 +69,9 @@ class TestResolveThreadRoot:
assert root == "e1"
async def test_normalizes_mid_thread_reply_to_root(self) -> None:
- nio = _FakeNio(events={"e2": _ev("e2", "reply", 200, thread_root="e1")})
- svc = _service_with_client(nio)
+ svc = _service_with_transport(
+ _transport(events={"e2": _ev("e2", "reply", 200, thread_root="e1")})
+ )
client = svc.client_lifecycle.get_by_agent_id("a")
root = await svc._resolve_thread_root(client, "!m:s", "e2")
@@ -90,54 +79,12 @@ class TestResolveThreadRoot:
assert root == "e1"
async def test_raises_when_event_missing(self) -> None:
- nio = _FakeNio(events={})
- svc = _service_with_client(nio)
+ svc = _service_with_transport(_transport(events={}))
client = svc.client_lifecycle.get_by_agent_id("a")
with pytest.raises(ValueError, match="thread_id not found"):
await svc._resolve_thread_root(client, "!m:s", "nope")
-class TestReadContextThreads:
- async def test_groups_threads_ordered_by_latest_activity(self) -> None:
- # chunk is newest-first, as the homeserver returns it.
- chunk = [
- _ev("e2", "reply to e1", 200, thread_root="e1"),
- _ev("e3", "later top-level", 150),
- _ev("e1", "root", 100),
- ]
- svc = _service_with_client(_FakeNio(chunk=chunk))
-
- result = (await svc.read_context("agent", "room"))["threads"]
-
- # Two threads: e3 (latest 150) then e1 (latest 200) — most-active last.
- assert [g["root"]["id"] for g in result] == ["e3", "e1"]
- assert result[0]["replies"] == []
- assert [m["id"] for m in result[1]["replies"]] == ["e2"]
- # Each message exposes its id.
- assert result[1]["root"]["id"] == "e1"
-
- async def test_fetches_orphan_root_outside_window(self) -> None:
- chunk = [_ev("e9", "reply", 200, thread_root="e1")]
- events = {"e1": _ev("e1", "old root", 100)}
- svc = _service_with_client(_FakeNio(chunk=chunk, events=events))
-
- result = (await svc.read_context("agent", "room"))["threads"]
-
- assert len(result) == 1
- assert result[0]["root"]["id"] == "e1"
- assert result[0]["root"]["body"] == "old root"
- assert "elided" not in result[0]["root"]
- assert [m["id"] for m in result[0]["replies"]] == ["e9"]
-
- async def test_orphan_root_elided_when_fetch_fails(self) -> None:
- chunk = [_ev("e9", "reply", 200, thread_root="e1")]
- svc = _service_with_client(_FakeNio(chunk=chunk, events={}))
-
- result = (await svc.read_context("agent", "room"))["threads"]
-
- assert len(result) == 1
- assert result[0]["root"]["id"] == "e1"
- assert result[0]["root"]["elided"] is True
- assert result[0]["root"]["body"] is None
- assert [m["id"] for m in result[0]["replies"]] == ["e9"]
+# Thread grouping in read_context is covered by test_read_context.py, which
+# reads the message log rather than a transport.
diff --git a/core/tests/switch_core/bridges/agent/test_command_result_threading.py b/core/tests/switch_core/bridges/agent/test_command_result_threading.py
index 107335a65..bcfce72aa 100644
--- a/core/tests/switch_core/bridges/agent/test_command_result_threading.py
+++ b/core/tests/switch_core/bridges/agent/test_command_result_threading.py
@@ -5,6 +5,7 @@ from types import SimpleNamespace
from switch_core.bridges.agent.commands import _cmd_help, _reply
from switch_core.clients.client_base import ClientBase
from switch_core.events import CommandEvent
+from switch_core.transport import InboundCustomEvent, RoomRef
class _Recorder:
@@ -36,7 +37,7 @@ class TestReplyThreading:
async def test_threads_under_command_thread_id(self) -> None:
send = _Recorder()
client = SimpleNamespace(reply_command=send)
- await _reply(client, SimpleNamespace(room_id="!m"), _event("$cmd-root"), "hi")
+ await _reply(client, RoomRef("!m"), _event("$cmd-root"), "hi")
assert len(send.calls) == 1
assert send.calls[0]["thread_root_id"] == "$cmd-root"
@@ -47,7 +48,7 @@ class TestReplyThreading:
async def test_top_level_when_no_thread_id(self) -> None:
send = _Recorder()
client = SimpleNamespace(reply_command=send)
- await _reply(client, SimpleNamespace(room_id="!m"), _event(None), "hi")
+ await _reply(client, RoomRef("!m"), _event(None), "hi")
assert len(send.calls) == 1
assert send.calls[0]["thread_root_id"] is None
@@ -60,9 +61,7 @@ class TestHandlerThreads:
async def test_help_result_is_threaded(self) -> None:
send = _Recorder()
client = SimpleNamespace(reply_command=send)
- await _cmd_help(
- client, SimpleNamespace(room_id="!m"), _event("$cmd-root"), True
- )
+ await _cmd_help(client, RoomRef("!m"), _event("$cmd-root"), True)
assert len(send.calls) == 1
assert send.calls[0]["thread_root_id"] == "$cmd-root"
@@ -74,7 +73,9 @@ class TestDispatchPopulatesThreadId:
root at dispatch (it is not part of the event content)."""
@staticmethod
- async def _dispatch(content: dict[str, object], event_id: str) -> CommandEvent:
+ async def _dispatch(
+ content: dict[str, object], event_id: str, thread_root_id: str | None = None
+ ) -> CommandEvent:
captured: list[CommandEvent] = []
async def _on_command(_room: object, event: CommandEvent) -> None:
@@ -85,19 +86,21 @@ class TestDispatchPopulatesThreadId:
_EVENT_DISPATCH=ClientBase._EVENT_DISPATCH,
on_command=_on_command,
)
- unknown = SimpleNamespace(
- type="com.switch.command",
+ custom = InboundCustomEvent(
+ room_id="!m",
event_id=event_id,
- source={"content": content},
- )
- await ClientBase._handle_custom_event(
- fake_self, SimpleNamespace(room_id="!m"), unknown
+ sender="@u:s",
+ timestamp=1700000000000,
+ content=content,
+ event_type="com.switch.command",
+ thread_root_id=thread_root_id,
)
+ await ClientBase._handle_custom_event(fake_self, RoomRef("!m"), custom)
assert len(captured) == 1
return captured[0]
async def test_top_level_command_gets_its_own_event_id(self) -> None:
- # No m.thread relation → the command roots its own thread.
+ # No thread relation → the command roots its own thread.
event = await self._dispatch(
{"command": "status", "args": "", "user_id": "u1", "user_name": "louisa"},
"$the-command-event",
@@ -119,5 +122,6 @@ class TestDispatchPopulatesThreadId:
},
},
"$the-command-event",
+ thread_root_id="$matrix-thread-root",
)
assert event.thread_id == "$matrix-thread-root"
diff --git a/core/tests/switch_core/bridges/agent/test_mediation.py b/core/tests/switch_core/bridges/agent/test_mediation.py
new file mode 100644
index 000000000..18ddda078
--- /dev/null
+++ b/core/tests/switch_core/bridges/agent/test_mediation.py
@@ -0,0 +1,142 @@
+"""Pre-invocation mediation says yes to what an agent has and no to the rest.
+
+There was no test for this at all while it ran over Matrix — the round trip
+made it awkward to exercise, which is its own argument. Against a direct call
+it is four cases.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.bridges.agent.mediation import BLOCKED, PROCEED, MediationService
+from switch_core.db.models import Agent, ApiKey, Client, Model, Tool, User
+from switch_core.db.stores.agent_store import AgentStore
+
+
+async def _agent(session: AsyncSession) -> Agent:
+ name = f"agent-{uuid.uuid4().hex[:8]}"
+ user = User(name=name, email=f"{name}@test", role="user", password_hash="x")
+ session.add(user)
+ await session.flush()
+ api_key = ApiKey(
+ user_id=user.id,
+ key_hash=f"hash-{name}",
+ encrypted_key="enc",
+ label=name,
+ type="agent",
+ )
+ client = Client(
+ matrix_user_id=f"@{name}:test", display_name=name, type="agent", password="x"
+ )
+ session.add_all([api_key, client])
+ await session.flush()
+ agent = Agent(
+ name=name,
+ description="",
+ agent_type="always_on",
+ connector_type="claude_code",
+ integration_profile={"connection_model": "always_on"},
+ client_id=client.id,
+ api_key_id=api_key.id,
+ )
+ session.add(agent)
+ await session.flush()
+ return agent
+
+
+def _service(session_factory: async_sessionmaker[AsyncSession]) -> MediationService:
+ return MediationService(session_factory=session_factory, agent_store=AgentStore())
+
+
+class TestToolAccess:
+ async def test_an_attached_tool_proceeds(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ agent = await _agent(session)
+ session.add(Tool(name="grep", description="", agent_id=agent.id))
+ await session.commit()
+ agent_id = agent.id
+
+ verdict = await _service(session_factory).tool_access(agent_id, "grep")
+
+ assert verdict.verdict == PROCEED
+ assert verdict.reason is None
+
+ async def test_a_tool_the_agent_does_not_have_is_blocked_with_a_reason(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A refusal a user cannot act on is barely better than a crash, so
+ the reason names both the agent and the tool."""
+ async with session_factory() as session:
+ agent = await _agent(session)
+ session.add(Tool(name="grep", description="", agent_id=agent.id))
+ await session.commit()
+ agent_id = agent.id
+
+ verdict = await _service(session_factory).tool_access(agent_id, "rm")
+
+ assert verdict.verdict == BLOCKED
+ assert verdict.reason is not None
+ assert "rm" in verdict.reason
+ assert agent_id in verdict.reason
+
+ async def test_an_agent_with_no_tools_is_blocked(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ agent = await _agent(session)
+ await session.commit()
+ agent_id = agent.id
+
+ verdict = await _service(session_factory).tool_access(agent_id, "grep")
+
+ assert verdict.verdict == BLOCKED
+
+ async def test_another_agent_s_tool_does_not_count(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Tools are per agent. A name existing somewhere in the table is not
+ the question being asked."""
+ async with session_factory() as session:
+ mine = await _agent(session)
+ theirs = await _agent(session)
+ session.add(Tool(name="grep", description="", agent_id=theirs.id))
+ await session.commit()
+ agent_id = mine.id
+
+ verdict = await _service(session_factory).tool_access(agent_id, "grep")
+
+ assert verdict.verdict == BLOCKED
+
+
+class TestModelAccess:
+ async def test_an_attached_model_proceeds(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ agent = await _agent(session)
+ session.add(Model(name="a-model", description="", agent_id=agent.id))
+ await session.commit()
+ agent_id = agent.id
+
+ verdict = await _service(session_factory).model_access(agent_id, "a-model")
+
+ assert verdict.verdict == PROCEED
+
+ async def test_a_model_the_agent_does_not_have_is_blocked_with_a_reason(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ agent = await _agent(session)
+ await session.commit()
+ agent_id = agent.id
+
+ verdict = await _service(session_factory).model_access(agent_id, "a-model")
+
+ assert verdict.verdict == BLOCKED
+ assert verdict.reason is not None
+ assert "a-model" in verdict.reason
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_admin_rendering.py b/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_admin_rendering.py
index 5ecacc150..1ffa1a677 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_admin_rendering.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_admin_rendering.py
@@ -12,10 +12,10 @@ relay path at the time, so nothing caught it.
from __future__ import annotations
-from types import SimpleNamespace
from typing import Any
from switch_core.bridges.collaboration.bridge_core import ADMIN_MARKER, BridgeCore
+from switch_core.transport import InboundMessage, RoomRef
BODY = "**Agents in this room:**\n- **scout** — Claude Code"
@@ -84,17 +84,18 @@ async def _none(*_args: Any, **_kwargs: Any) -> None:
return None
-def _event(*, admin: bool) -> Any:
+def _event(*, admin: bool) -> InboundMessage:
content: dict[str, Any] = {}
if admin:
content[ADMIN_MARKER] = {"type": "command_result"}
- else:
- content["sender_name"] = "scout"
- return SimpleNamespace(
+ return InboundMessage(
+ room_id="!r:switch.local",
+ event_id="$e1",
sender="@someone:switch.local",
+ timestamp=1700000000000,
+ content=content,
body=BODY,
- event_id="$e1",
- source={"content": content},
+ sender_name=None if admin else "scout",
)
@@ -102,7 +103,7 @@ async def test_an_admin_event_reaches_the_adapter_unrendered() -> None:
adapter = _RecordingAdapter()
await _bridge(adapter).handle_outbound_message(
- SimpleNamespace(room_id="!r:switch.local"), _event(admin=True)
+ RoomRef("!r:switch.local"), _event(admin=True)
)
# Handed on as written, for admin_message to render once.
@@ -116,7 +117,7 @@ async def test_an_admin_event_is_not_rendered_twice() -> None:
adapter = _RecordingAdapter()
await _bridge(adapter).handle_outbound_message(
- SimpleNamespace(room_id="!r:switch.local"), _event(admin=True)
+ RoomRef("!r:switch.local"), _event(admin=True)
)
rendered = adapter.translate_outbound(adapter.admin_calls[0])
@@ -130,7 +131,7 @@ async def test_an_agent_message_is_still_rendered_by_the_relay() -> None:
adapter = _RecordingAdapter()
await _bridge(adapter).handle_outbound_message(
- SimpleNamespace(room_id="!r:switch.local"), _event(admin=False)
+ RoomRef("!r:switch.local"), _event(admin=False)
)
assert adapter.admin_calls == []
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_media.py b/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_media.py
index 8747c032f..aa23f0190 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_media.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_outbound_media.py
@@ -4,10 +4,13 @@ import asyncio
from types import SimpleNamespace
from typing import Any
-import nio
-from nio import DownloadError
-
from switch_core.bridges.collaboration.bridge_core import BridgeCore
+from switch_core.transport import (
+ DownloadResult,
+ InboundMedia,
+ RoomRef,
+ TransportError,
+)
def _media_event(
@@ -21,7 +24,7 @@ def _media_event(
group: dict[str, Any] | None = None,
mimetype: str = "image/png",
event_id: str = "$media-event",
-) -> nio.RoomMessageMedia:
+) -> InboundMedia:
content: dict[str, Any] = {
"msgtype": msgtype,
"body": body,
@@ -36,15 +39,21 @@ def _media_event(
content["sender_name"] = sender_name
if thread_root is not None:
content["m.relates_to"] = {"rel_type": "m.thread", "event_id": thread_root}
- cls = nio.RoomMessageImage if msgtype == "m.image" else nio.RoomMessageFile
- return cls.from_dict(
- {
- "type": "m.room.message",
- "event_id": event_id,
- "sender": sender,
- "origin_server_ts": 1700000000000,
- "content": content,
- }
+ return InboundMedia(
+ room_id="!room:s",
+ event_id=event_id,
+ sender=sender,
+ timestamp=1700000000000,
+ content=content,
+ body=body,
+ sender_name=sender_name,
+ msgtype=msgtype,
+ uri="mxc://s/abc",
+ filename=filename or body,
+ mimetype=mimetype,
+ size=5,
+ thread_root_id=thread_root,
+ group=group,
)
@@ -111,7 +120,7 @@ class _FakeAdapter:
def _fake_bridge(
*,
- download: object = SimpleNamespace(body=b"bytes"),
+ download: DownloadResult | TransportError = DownloadResult(body=b"bytes"),
matrix_to_external: dict[str, str] | None = None,
max_bytes: int = 1024,
) -> SimpleNamespace:
@@ -155,15 +164,19 @@ def _fake_bridge(
BridgeCore._flush_incomplete_outbound_group.__get__(ns)
)
- async def _nio_download(mxc: str):
+ async def _download_media(uri: str) -> DownloadResult:
+ if isinstance(download, TransportError):
+ raise download
return download
- ns.client = SimpleNamespace(nio_client=SimpleNamespace(download=_nio_download))
+ ns.client = SimpleNamespace(
+ transport=SimpleNamespace(download_media=_download_media)
+ )
return ns
-def _room() -> SimpleNamespace:
- return SimpleNamespace(room_id="!room:s")
+def _room() -> RoomRef:
+ return RoomRef("!room:s")
async def test_image_relays_via_send_attachment_and_records_map() -> None:
@@ -264,7 +277,7 @@ async def test_non_image_file_relays_natively() -> None:
async def test_download_failure_posts_disclosed_fallback() -> None:
- bridge = _fake_bridge(download=DownloadError("boom"))
+ bridge = _fake_bridge(download=TransportError("boom"))
await BridgeCore.handle_outbound_media(
bridge, _room(), _media_event(), bridge.client
@@ -276,7 +289,7 @@ async def test_download_failure_posts_disclosed_fallback() -> None:
async def test_oversize_media_posts_disclosed_fallback() -> None:
- bridge = _fake_bridge(download=SimpleNamespace(body=b"too big"), max_bytes=3)
+ bridge = _fake_bridge(download=DownloadResult(body=b"too big"), max_bytes=3)
await BridgeCore.handle_outbound_media(
bridge, _room(), _media_event(), bridge.client
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py b/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py
index c5db36072..34fafc77f 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py
@@ -47,6 +47,7 @@ def _service() -> CollaborationBridgeLifecycleService:
matrix_admin=None, # type: ignore[arg-type]
session_factory=None, # type: ignore[arg-type]
config=None, # type: ignore[arg-type]
+ client_factory=None, # type: ignore[arg-type]
)
diff --git a/core/tests/switch_core/bridges/collaboration/test_command_thread_mapping.py b/core/tests/switch_core/bridges/collaboration/test_command_thread_mapping.py
index 422fc4f8a..209f6fb49 100644
--- a/core/tests/switch_core/bridges/collaboration/test_command_thread_mapping.py
+++ b/core/tests/switch_core/bridges/collaboration/test_command_thread_mapping.py
@@ -2,10 +2,9 @@ from __future__ import annotations
from types import MethodType, SimpleNamespace
-from nio import RoomSendError
-
from switch_core.bridges.collaboration.bridge_core import BridgeCore
from switch_core.bridges.collaboration.models import InboundCommand
+from switch_core.transport import SendResult, TransportError
def _cmd(
@@ -28,7 +27,7 @@ def _cmd(
def _fake_bridge(
- room_send_result: object,
+ send_result: SendResult | TransportError,
*,
external_to_matrix: dict[str, str] | None = None,
translate_inbound: object = None,
@@ -48,13 +47,16 @@ def _fake_bridge(
pending[matrix_event_id] = external_post_id
async def _ensure_user_in_matrix_room(**_kw: object) -> SimpleNamespace:
- async def _room_send(_room_id: str, _type: str, content: dict) -> object:
+ async def _send_event(_room_id: str, _type: str, content: dict) -> str:
sent_content.append(content)
- return room_send_result
+ if isinstance(send_result, TransportError):
+ raise send_result
+ return send_result.event_id
return SimpleNamespace(
matrix_user_id="@puppet:switch.local",
- client=SimpleNamespace(room_send=_room_send),
+ client_id="puppet-1",
+ send_event=_send_event,
)
async def _matrix_event_for_external_post(external_post_id: str) -> str | None:
@@ -80,7 +82,11 @@ def _fake_bridge(
class TestCommandThreadMapping:
async def test_top_level_command_maps_to_its_own_post(self) -> None:
# No root_id: the command starts its own thread, rooted at its post.
- bridge = _fake_bridge(SimpleNamespace(event_id="$cmd-event"))
+ bridge = _fake_bridge(
+ SendResult(
+ event_id="$cmd-event", event_type="com.switch.command", content={}
+ )
+ )
await BridgeCore._handle_inbound_command(bridge, _cmd(message_ref="mm-post-1"))
assert bridge.recorded == [
@@ -98,7 +104,9 @@ class TestCommandThreadMapping:
# command event relates to the existing Matrix root, and we do NOT remap
# the (already-mapped) root post.
bridge = _fake_bridge(
- SimpleNamespace(event_id="$cmd-event"),
+ SendResult(
+ event_id="$cmd-event", event_type="com.switch.command", content={}
+ ),
external_to_matrix={"mm-root": "$matrix-root"},
)
await BridgeCore._handle_inbound_command(
@@ -114,7 +122,11 @@ class TestCommandThreadMapping:
async def test_in_thread_command_maps_root_when_unbridged(self) -> None:
# Thread root not yet bridged: map the command event to the thread root
# (a valid Mattermost root post), NOT to the mid-thread command post.
- bridge = _fake_bridge(SimpleNamespace(event_id="$cmd-event"))
+ bridge = _fake_bridge(
+ SendResult(
+ event_id="$cmd-event", event_type="com.switch.command", content={}
+ )
+ )
await BridgeCore._handle_inbound_command(
bridge, _cmd(message_ref="mm-reply", root_id="mm-root")
)
@@ -130,13 +142,17 @@ class TestCommandThreadMapping:
async def test_no_mapping_without_external_post_ref(self) -> None:
# Native (non-bridged) command: no external post to thread under.
- bridge = _fake_bridge(SimpleNamespace(event_id="$cmd-event"))
+ bridge = _fake_bridge(
+ SendResult(
+ event_id="$cmd-event", event_type="com.switch.command", content={}
+ )
+ )
await BridgeCore._handle_inbound_command(bridge, _cmd(message_ref=None))
assert bridge.recorded == []
async def test_no_mapping_when_send_fails(self) -> None:
- err = RoomSendError("boom")
+ err = TransportError("boom")
bridge = _fake_bridge(err)
await BridgeCore._handle_inbound_command(bridge, _cmd(message_ref="mm-post-1"))
@@ -192,12 +208,12 @@ class TestCommandResultThreadingRace:
resolved: dict[str, str | None] = {}
async def _ensure_user_in_matrix_room(**_kw: object) -> SimpleNamespace:
- async def _room_send(_room_id: str, _type: str, _content: dict) -> object:
- return SimpleNamespace(event_id="$cmd-event")
+ async def _send_event(_room_id: str, _type: str, _content: dict) -> str:
+ return "$cmd-event"
return SimpleNamespace(
matrix_user_id="@puppet:switch.local",
- client=SimpleNamespace(room_send=_room_send),
+ send_event=_send_event,
)
async def _matrix_event_for_external_post(_post: str) -> str | None:
diff --git a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py
index 33d0a8e29..cb4ed3342 100644
--- a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py
+++ b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py
@@ -50,6 +50,7 @@ def _service(
matrix_admin=MagicMock(),
session_factory=session_factory,
config=MagicMock(),
+ client_factory=MagicMock(),
)
@@ -225,3 +226,31 @@ class TestTheBridgeClientName:
localpart = _bridge_client_localpart("slack", "Ops & Eng (US)")
assert re.fullmatch(r"[a-z0-9._=/-]+", localpart)
+
+
+async def test_a_starting_bridge_is_recorded_in_the_rooms_it_carries(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ """Membership is a row now, and nothing had ever written the bridge's.
+
+ Its rooms were expressed by inviting it and letting the homeserver
+ remember; once a client reads its rooms from `client_rooms`, a bridge with
+ no rows is in none of them and relays nothing outward — while still
+ receiving, because inbound posts into a room by id.
+ """
+ service = _service(session_factory)
+ async with session_factory() as session:
+ bridge_id, client_id = await _make_bridge(session)
+ room_id = await _make_bridged_room(session, bridge_id=bridge_id)
+ other_bridge_id, _ = await _make_bridge(session)
+ elsewhere_id = await _make_bridged_room(session, bridge_id=other_bridge_id)
+ await session.commit()
+
+ await service._record_bridge_memberships(bridge_id, client_id)
+ # Again, because a bridge starts more than once.
+ await service._record_bridge_memberships(bridge_id, client_id)
+
+ async with session_factory() as session:
+ assert await RoomStore().get_client_ids(session, room_id) == [client_id]
+ assert await RoomStore().get_client_ids(session, elsewhere_id) == []
diff --git a/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py b/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py
index 130918879..120d18096 100644
--- a/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py
+++ b/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py
@@ -318,6 +318,7 @@ def _lifecycle() -> CollaborationBridgeLifecycleService:
matrix_admin=MagicMock(),
session_factory=MagicMock(),
config=MagicMock(),
+ client_factory=MagicMock(),
)
service.register_adapter("recording", _RecordingAdapter, _RecordingConfig)
return service
@@ -397,6 +398,7 @@ def _service_with_existing(existing: list[Any]) -> CollaborationBridgeLifecycleS
matrix_admin=MagicMock(),
session_factory=MagicMock(return_value=session),
config=MagicMock(),
+ client_factory=MagicMock(),
)
service.register_adapter("teams", TeamsAdapter, TeamsConnectionConfig)
return service
@@ -552,6 +554,7 @@ async def test_concurrent_registration_cannot_take_the_same_port_twice(
matrix_admin=MagicMock(),
session_factory=MagicMock(return_value=session),
config=MagicMock(),
+ client_factory=MagicMock(),
)
service.register_adapter("teams", TeamsAdapter, TeamsConnectionConfig)
monkeypatch.setattr(
@@ -616,6 +619,7 @@ async def test_start_refuses_a_second_bridge_already_holding_the_port() -> None:
matrix_admin=MagicMock(),
session_factory=MagicMock(return_value=session),
config=MagicMock(),
+ client_factory=MagicMock(),
)
service.register_adapter("teams", TeamsAdapter, TeamsConnectionConfig)
# A bridge already running and holding the port.
diff --git a/core/tests/switch_core/clients/test_addressing_enforcement.py b/core/tests/switch_core/clients/test_addressing_enforcement.py
index c7e6081d6..6d67e1df6 100644
--- a/core/tests/switch_core/clients/test_addressing_enforcement.py
+++ b/core/tests/switch_core/clients/test_addressing_enforcement.py
@@ -3,14 +3,23 @@ from __future__ import annotations
from contextlib import asynccontextmanager
from types import SimpleNamespace
-from switch_core.clients.agent_client import (
- _ADDRESSING_DENIED_MESSAGE,
- _ADDRESSING_UNCLAIMED_MESSAGE,
- AUTO_REPLY_FLAG,
- AgentClient,
- _AddressingDecision,
- _SenderPrincipal,
+from switch_core.clients.agent_client import AUTO_REPLY_FLAG, AgentClient
+from switch_core.delivery.addressing import (
+ ADDRESSING_DENIED_MESSAGE as _ADDRESSING_DENIED_MESSAGE,
)
+from switch_core.delivery.addressing import (
+ ADDRESSING_UNCLAIMED_MESSAGE as _ADDRESSING_UNCLAIMED_MESSAGE,
+)
+from switch_core.delivery.addressing import (
+ AddressingDecision as _AddressingDecision,
+)
+from switch_core.delivery.addressing import (
+ AddressingResolver,
+)
+from switch_core.delivery.addressing import (
+ SenderPrincipal as _SenderPrincipal,
+)
+from switch_core.transport import InboundMessage, RoomRef
@asynccontextmanager
@@ -22,17 +31,18 @@ def _meta(room_id: str = "room-1") -> SimpleNamespace:
return SimpleNamespace(room_id=room_id)
-def _event(
- sender: str = "@u:switch.local", auto_reply: bool = False
-) -> SimpleNamespace:
+def _event(sender: str = "@u:switch.local", auto_reply: bool = False) -> InboundMessage:
content: dict = {"sender_name": "human"}
if auto_reply:
content[AUTO_REPLY_FLAG] = True
- return SimpleNamespace(
+ return InboundMessage(
+ room_id="!matrix:switch.local",
+ event_id="$evt",
sender=sender,
+ timestamp=1700000000000,
+ content=content,
body="@fixer help",
- source={"content": content},
- event_id="$evt",
+ sender_name="human",
)
@@ -54,7 +64,7 @@ class TestResolveSenderPrincipal:
return list(claimants)
return SimpleNamespace(
- client_store=SimpleNamespace(get_by_matrix_user_id=_get_by_mxid),
+ _client_store=SimpleNamespace(get_by_matrix_user_id=_get_by_mxid),
_agent_store=SimpleNamespace(get_by_client_id=_agent_by_client),
_external_user_store=SimpleNamespace(
get_by_client_id=_ext_by_client, claimant_ids=_claimant_ids
@@ -69,7 +79,7 @@ class TestResolveSenderPrincipal:
agent=SimpleNamespace(id="agent-7", owner_id="user-1"),
external_user=None,
)
- result = await AgentClient._resolve_sender_principal(
+ result = await AddressingResolver.resolve_sender(
client, object(), "@a:switch.local"
)
assert result == ("agent", "agent-7", [], "user-1")
@@ -81,7 +91,7 @@ class TestResolveSenderPrincipal:
external_user=SimpleNamespace(id="ext-3"),
claimants=["user-1"],
)
- result = await AgentClient._resolve_sender_principal(
+ result = await AddressingResolver.resolve_sender(
client, object(), "@u:switch.local"
)
assert result == ("user", "ext-3", ["user-1"], None)
@@ -95,7 +105,7 @@ class TestResolveSenderPrincipal:
external_user=SimpleNamespace(id="ext-3"),
claimants=["user-1", "user-2"],
)
- result = await AgentClient._resolve_sender_principal(
+ result = await AddressingResolver.resolve_sender(
client, object(), "@u:switch.local"
)
assert result == ("user", "ext-3", ["user-1", "user-2"], None)
@@ -107,14 +117,14 @@ class TestResolveSenderPrincipal:
agent=None,
external_user=SimpleNamespace(id="ext-3"),
)
- result = await AgentClient._resolve_sender_principal(
+ result = await AddressingResolver.resolve_sender(
client, object(), "@u:switch.local"
)
assert result == ("user", "ext-3", [], None)
async def test_unknown_client_is_none(self) -> None:
client = self._client(client=None, agent=None, external_user=None)
- result = await AgentClient._resolve_sender_principal(
+ result = await AddressingResolver.resolve_sender(
client, object(), "@ghost:switch.local"
)
assert result is None
@@ -125,7 +135,7 @@ class TestResolveSenderPrincipal:
client = self._client(
client=SimpleNamespace(id="c1"), agent=None, external_user=None
)
- result = await AgentClient._resolve_sender_principal(
+ result = await AddressingResolver.resolve_sender(
client, object(), "@system:switch.local"
)
assert result is None
@@ -139,9 +149,9 @@ def _allowed_client(
group_id: str | None = None,
owner_id: str | None = None,
) -> SimpleNamespace:
- """Fake client for _addressing_allowed: the agent carries `policy` and is
- owned by `owner_id`, the sender resolves to `principal` (kind, id,
- claimants) owned by `sender_owner_id`, and the room has `group_id`."""
+ """Fake resolver for `permitted`: the agent carries `policy` and is owned
+ by `owner_id`, the sender resolves to `principal` (kind, id, claimants)
+ owned by `sender_owner_id`, and the room has `group_id`."""
agent = SimpleNamespace(name="fixer", addressing_policy=policy, owner_id=owner_id)
@@ -156,15 +166,16 @@ def _allowed_client(
return SimpleNamespace(
agent=agent,
- session_factory=_session_factory,
- _resolve_sender_principal=_resolve,
+ resolve_sender=_resolve,
_room_store=SimpleNamespace(get=_get_room),
)
async def _decide(client: SimpleNamespace, room_id: str = "room-1"): # type: ignore[no-untyped-def]
- return await AgentClient._addressing_allowed(
- client, None, client.agent, "@u:switch.local", room_id
+ # No session is opened here: the resolver reads through the one it is
+ # handed, so `permitted` never takes a pool slot of its own.
+ return await AddressingResolver.permitted(
+ client, object(), agent=client.agent, room_id=room_id, sender="@u:switch.local"
)
@@ -385,8 +396,8 @@ def _gate_client(*, allowed: bool, refusal: str = _ADDRESSING_DENIED_MESSAGE):
return client
-def _room() -> SimpleNamespace:
- return SimpleNamespace(room_id="!matrix:switch.local")
+def _room() -> RoomRef:
+ return RoomRef(room_id="!matrix:switch.local")
async def _gate(client: SimpleNamespace, event: SimpleNamespace): # type: ignore[no-untyped-def]
diff --git a/core/tests/switch_core/clients/test_admin_client.py b/core/tests/switch_core/clients/test_admin_client.py
index 2f0017bfe..a4768b004 100644
--- a/core/tests/switch_core/clients/test_admin_client.py
+++ b/core/tests/switch_core/clients/test_admin_client.py
@@ -8,6 +8,7 @@ from switch_core.bridges.agent.commands import dispatch_admin_command
from switch_core.clients.admin_client import AdminClient
from switch_core.clients.admin_messages import ADMIN_MARKER, AdminMessageType
from switch_core.events import CommandEvent
+from switch_core.transport import InboundMessage, RoomRef
# Matches a live `@<handle>` mention token (same char class Switch re-parses).
_MENTION = re.compile(r"@[A-Za-z0-9._-]+")
@@ -30,18 +31,22 @@ def _no_connections() -> SimpleNamespace:
)
-def _event(body: str, sender_name: str = "alice") -> SimpleNamespace:
+def _event(body: str, sender_name: str = "alice") -> InboundMessage:
"""A room message as the admin client sees it: body + sender + the
bridge-provided sender_name in content (used to tag the asker)."""
- return SimpleNamespace(
- body=body,
+ return InboundMessage(
+ room_id="!matrix:switch.local",
+ event_id="$evt",
sender=f"@{sender_name}:switch.local",
- source={"content": {"sender_name": sender_name}},
+ timestamp=1700000000000,
+ content={"sender_name": sender_name},
+ body=body,
+ sender_name=sender_name,
)
-def _room() -> SimpleNamespace:
- return SimpleNamespace(room_id="!matrix:switch.local")
+def _room() -> RoomRef:
+ return RoomRef(room_id="!matrix:switch.local")
def _admin_client(
diff --git a/core/tests/switch_core/clients/test_agent_client_attachment_groups.py b/core/tests/switch_core/clients/test_agent_client_attachment_groups.py
index 4ef41d558..4abea2ce2 100644
--- a/core/tests/switch_core/clients/test_agent_client_attachment_groups.py
+++ b/core/tests/switch_core/clients/test_agent_client_attachment_groups.py
@@ -5,11 +5,10 @@ from contextlib import asynccontextmanager
from types import SimpleNamespace
from typing import Any
-import nio
-
import switch_core.clients.agent_client as ac
from switch_core.clients.agent_client import AgentClient, _GateOutcome
from switch_core.clients.room_meta import RoomMeta
+from switch_core.transport import InboundMedia, RoomRef
def _media_event(
@@ -20,7 +19,7 @@ def _media_event(
msgtype: str = "m.image",
group: dict[str, Any] | None = None,
event_id: str = "$evt",
-) -> nio.RoomMessageMedia:
+) -> InboundMedia:
content: dict[str, Any] = {
"msgtype": msgtype,
"body": body,
@@ -32,15 +31,20 @@ def _media_event(
content["filename"] = filename
if group is not None:
content["com.switch.attachment_group"] = group
- cls = nio.RoomMessageImage if msgtype == "m.image" else nio.RoomMessageFile
- return cls.from_dict(
- {
- "type": "m.room.message",
- "event_id": event_id,
- "sender": "@alice:s",
- "origin_server_ts": 1700000000000,
- "content": content,
- }
+ return InboundMedia(
+ room_id="!room:s",
+ event_id=event_id,
+ sender="@alice:s",
+ timestamp=1700000000000,
+ content=content,
+ body=body,
+ sender_name="alice",
+ msgtype=msgtype,
+ uri="mxc://s/abc",
+ filename=filename,
+ mimetype=mimetype,
+ size=5,
+ group=group,
)
@@ -104,8 +108,8 @@ def _fake_client() -> SimpleNamespace:
return ns
-def _room() -> SimpleNamespace:
- return SimpleNamespace(room_id="!room:s")
+def _room() -> RoomRef:
+ return RoomRef(room_id="!room:s")
async def test_grouped_media_coalesces_into_one_event() -> None:
diff --git a/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py b/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py
index b8cee49ae..c51dfcb67 100644
--- a/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py
+++ b/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py
@@ -29,6 +29,8 @@ from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
+from switch_core.delivery.addressing import AddressingResolver
+from switch_core.transport import InboundMessage, RoomRef
MATRIX_ROOM_ID = "!r:test"
@@ -126,6 +128,14 @@ def _client(
client._agent_session_store = AgentSessionStore()
client._external_user_store = ExternalUserStore()
client._connections = ConnectionRegistry()
+ client._addressing = AddressingResolver(
+ room_store=client._room_store,
+ room_role_store=client._room_role_store,
+ client_store=client.client_store,
+ agent_store=client._agent_store,
+ external_user_store=client._external_user_store,
+ live_agent_ids=client._connections.live_agent_ids,
+ )
client._frontend_base_url = None
client._room_meta = {
MATRIX_ROOM_ID: RoomMeta(
@@ -150,19 +160,20 @@ def _client(
return client
-def _message(body: str, sender: str = "@switch-slack-louisa:test") -> Any:
- return SimpleNamespace(
- body=body,
- formatted_body=None,
- sender=sender,
+def _message(body: str, sender: str = "@switch-slack-louisa:test") -> InboundMessage:
+ return InboundMessage(
+ room_id=MATRIX_ROOM_ID,
event_id="$trigger",
- server_timestamp=0,
- source={"content": {"body": body, "sender_name": "louisa"}},
+ sender=sender,
+ timestamp=0,
+ content={"body": body, "sender_name": "louisa"},
+ body=body,
+ sender_name="louisa",
)
-def _room() -> Any:
- return SimpleNamespace(room_id=MATRIX_ROOM_ID)
+def _room() -> RoomRef:
+ return RoomRef(room_id=MATRIX_ROOM_ID)
class TestInboundMessageCheckouts:
diff --git a/core/tests/switch_core/clients/test_client_construction.py b/core/tests/switch_core/clients/test_client_construction.py
new file mode 100644
index 000000000..2f6cd5f46
--- /dev/null
+++ b/core/tests/switch_core/clients/test_client_construction.py
@@ -0,0 +1,180 @@
+"""Every client subclass must be constructible through the real signature.
+
+Three subclasses take `**kwargs: Any` and forward to `ClientBase`, which
+hides the constructor from the type checker: a keyword `ClientBase` no
+longer accepts type-checks clean and fails at runtime, when the client
+starts. That is how a `device_id` left behind by the transport port took
+down all four collaboration bridges while mypy stayed green.
+
+These tests call the constructors the way production does.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import pathlib
+from typing import Any
+
+import pytest
+
+from switch_core.clients.admin_client import AdminClient
+from switch_core.clients.bridge_client import BridgeClient, BridgeClientConfig
+from switch_core.clients.client_base import ClientBase, ClientConfig
+from switch_core.clients.client_factory import matrix_transport_for
+from switch_core.clients.user_client import UserClient
+from tests.switch_core.transport.fake import FakeMessageRecorder
+
+
+def _base_kwargs() -> dict[str, Any]:
+ return {
+ "client_id": "client-1",
+ "matrix_user_id": "@switch-agent-1:switch.local",
+ "display_name": "agent-one",
+ "password": "pw",
+ "server_url": "https://matrix.example",
+ "session_factory": object(),
+ "client_store": object(),
+ "transport_factory": matrix_transport_for,
+ "session_state": {"access_token": None, "device_id": None},
+ "next_batch_token": None,
+ "message_recorder": FakeMessageRecorder(),
+ }
+
+
+def test_client_base_takes_what_the_factory_passes() -> None:
+ client = ClientBase(config=ClientConfig(), **_base_kwargs())
+
+ assert client.client_id == "client-1"
+ # Credentials are held opaquely, not unpacked into named attributes.
+ assert client.session_state == {"access_token": None, "device_id": None}
+
+
+def test_bridge_client_construction_matches_its_lifecycle_call_site() -> None:
+ client = BridgeClient(
+ bridge_core=object(), # type: ignore[arg-type]
+ config=BridgeClientConfig(bridge_id="bridge-1"),
+ **_base_kwargs(),
+ )
+
+ assert client.config.bridge_id == "bridge-1"
+
+
[email protected]("cls", [UserClient, AdminClient])
+def test_every_registered_client_type_constructs(cls: type) -> None:
+ base = _base_kwargs()
+ # Collaborators the factory injects as extra kwargs differ per class, so
+ # stub whatever each one declares rather than naming them here.
+ collaborators: dict[str, Any] = {}
+ for name, param in inspect.signature(cls.__init__).parameters.items():
+ if (
+ param.kind is not inspect.Parameter.KEYWORD_ONLY
+ or param.default is not inspect.Parameter.empty
+ or name in base
+ or name == "config"
+ ):
+ continue
+ # A plain object() stands in for a collaborator, but a few are strings
+ # the constructor manipulates on the way in.
+ collaborators[name] = "" if "str" in str(param.annotation) else object()
+
+ client = cls(config=cls.config_class(), **base, **collaborators)
+
+ assert isinstance(client, ClientBase)
+
+
+def test_no_client_holds_matrix_credentials_directly() -> None:
+ """The transport owns them; a client that reads them is a Matrix client."""
+ client = ClientBase(config=ClientConfig(), **_base_kwargs())
+
+ assert not hasattr(client, "access_token")
+ assert not hasattr(client, "device_id")
+
+
+def test_no_call_site_passes_transport_credentials_to_a_client() -> None:
+ """Catch the caller, which the constructor tests above cannot.
+
+ `**kwargs: Any` means a call site passing `device_id=` type-checks and
+ then fails when the client starts. Constructing a client correctly in a
+ test proves nothing about the places that construct it wrongly, so scan
+ for the argument itself.
+ """
+ package = pathlib.Path(__file__).resolve().parents[3] / "switch_core"
+ retired = {"device_id", "access_token"}
+ offenders: list[str] = []
+
+ for path in package.rglob("*.py"):
+ tree = ast.parse(path.read_text(), filename=str(path))
+ for node in ast.walk(tree):
+ if not isinstance(node, ast.Call):
+ continue
+ func = node.func
+ name = getattr(func, "id", None) or getattr(func, "attr", "")
+ if not name.endswith("Client"):
+ continue
+ passed = {kw.arg for kw in node.keywords if kw.arg}
+ for arg in sorted(passed & retired):
+ offenders.append(f"{path.relative_to(package)}: {name}({arg}=...)")
+
+ assert offenders == [], (
+ "clients take an opaque `session_state`, not individual credentials; "
+ f"these call sites still pass them: {offenders}"
+ )
+
+
+def test_only_the_factory_names_a_transport_implementation() -> None:
+ """A client's bus is one decision, made in one place.
+
+ The collaboration bridges named `matrix_transport_for` directly, so the
+ transport setting reached every agent and no bridge: agents talked in rows,
+ bridges talked to the homeserver, and neither side saw the other or logged
+ anything. Nothing failed — messages simply stopped crossing.
+
+ That is invisible in review, so scan for the cause instead. Any module that
+ can reach an implementation can pick the wrong one.
+
+ Guarded per module rather than per symbol: an implementation's module is
+ private, so one added later is covered the day it lands instead of the day
+ someone remembers to extend a list of names, and putting a module in
+ `allowed` is a deliberate act a reviewer sees.
+ """
+ package = pathlib.Path(__file__).resolve().parents[3] / "switch_core"
+ private = {"switch_core.transport.matrix", "switch_core.transport.postgres"}
+ allowed = {
+ "clients/client_factory.py",
+ "transport/matrix.py",
+ "transport/postgres.py",
+ # The migration commands are the exception the rule is not about. They
+ # exist to read the homeserver — that is the whole job — and they must
+ # do it whatever transport the running server is on, which is how a
+ # backfill can still be run after the flip. A client picking its own
+ # bus is the bug; a one-off command naming the bus it is migrating
+ # away from is the point.
+ "cli/backfill.py",
+ "cli/reconcile.py",
+ }
+ offenders: list[str] = []
+
+ for path in package.rglob("*.py"):
+ relative = path.relative_to(package).as_posix()
+ if relative in allowed:
+ continue
+ tree = ast.parse(path.read_text(), filename=str(path))
+ for node in ast.walk(tree):
+ imported: list[str] = []
+ if isinstance(node, ast.Import):
+ imported = [alias.name for alias in node.names]
+ elif isinstance(node, ast.ImportFrom) and node.module and not node.level:
+ # `from switch_core.transport import postgres` reaches the same
+ # module by importing its name from the package.
+ imported = [node.module] + [
+ f"{node.module}.{alias.name}" for alias in node.names
+ ]
+ for name in imported:
+ if name in private:
+ offenders.append(f"{relative}: {name}")
+
+ assert offenders == [], (
+ "ask ClientFactory.transport_for for a transport rather than reaching "
+ f"for one; these modules choose for themselves: {offenders}"
+ )
diff --git a/core/tests/switch_core/clients/test_client_factory_transport_choice.py b/core/tests/switch_core/clients/test_client_factory_transport_choice.py
new file mode 100644
index 000000000..6fdf238f4
--- /dev/null
+++ b/core/tests/switch_core/clients/test_client_factory_transport_choice.py
@@ -0,0 +1,101 @@
+"""One setting picks the transport, and the recorder that goes with it.
+
+The pairing is the thing worth a test. A transport that stores what it carries
+paired with a recorder that also writes would double every row; the other way
+round would leave the log empty. Both are silent until someone reads the table,
+which is why the decision is made in one place and checked here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.clients.client_base import ClientBase
+from switch_core.clients.client_factory import ClientFactory
+from switch_core.config import SwitchConfig
+from switch_core.db.models import Client
+from switch_core.db.stores.client_store import ClientStore
+from switch_core.db.stores.media_store import MediaStore
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.db.stores.room_store import RoomStore
+from switch_core.messages import MessageRecorder
+from switch_core.messages.notify import MessageListener
+from switch_core.messages.recording import NoRecording
+from switch_core.transport.ephemeral import EphemeralBus
+from switch_core.transport.invites import InviteBus
+from switch_core.transport.matrix import MatrixTransport
+from switch_core.transport.postgres import PostgresTransport
+
+
+def _factory(
+ session_factory: async_sessionmaker[AsyncSession], transport: str
+) -> ClientFactory:
+ config = SwitchConfig(
+ db_host="db",
+ db_port="5432",
+ db_user="postgres",
+ db_password="pw",
+ db_name="switch",
+ matrix_server="http://nowhere",
+ matrix_server_name="switch.local",
+ matrix_admin_user="admin",
+ matrix_admin_password="pw",
+ matrix_registration_shared_secret="secret",
+ agent_registration_token="token",
+ jwt_secret_key="jwt",
+ gateway_admin_email="[email protected]",
+ gateway_admin_password="pw",
+ message_transport=transport, # type: ignore[arg-type]
+ )
+ recorder = MessageRecorder(
+ session_factory=session_factory,
+ room_store=RoomStore(),
+ message_store=MessageStore(),
+ )
+ factory = ClientFactory(
+ client_store=ClientStore(),
+ session_factory=session_factory,
+ config=config,
+ message_recorder=recorder,
+ room_store=RoomStore(),
+ message_store=MessageStore(),
+ media_store=MediaStore(),
+ listener=MessageListener(lambda: None), # type: ignore[arg-type,return-value]
+ invites=InviteBus(),
+ ephemeral=EphemeralBus(),
+ )
+ factory.register("user", ClientBase)
+ return factory
+
+
+def _record() -> Client:
+ return Client(
+ id="client-1",
+ matrix_user_id="@someone:test",
+ display_name="someone",
+ type="user",
+ password="x",
+ )
+
+
+ ("setting", "transport_class", "records_separately"),
+ [
+ ("matrix", MatrixTransport, True),
+ ("postgres", PostgresTransport, False),
+ ],
+)
+def test_the_setting_picks_both_halves(
+ session_factory: async_sessionmaker[AsyncSession],
+ setting: str,
+ transport_class: type,
+ records_separately: bool,
+) -> None:
+ client: Any = _factory(session_factory, setting).create(_record())
+
+ assert isinstance(client._transport_factory(client), transport_class)
+ assert isinstance(client.message_recorder, MessageRecorder) is records_separately
+ assert isinstance(client.message_recorder, NoRecording) is not records_separately
diff --git a/core/tests/switch_core/clients/test_mention_routing.py b/core/tests/switch_core/clients/test_mention_routing.py
index c30b36c61..2d13fa418 100644
--- a/core/tests/switch_core/clients/test_mention_routing.py
+++ b/core/tests/switch_core/clients/test_mention_routing.py
@@ -8,6 +8,10 @@ from switch_core.clients.agent_client import (
AgentClient,
_role_elsewhere_message,
)
+from switch_core.delivery.addressing import (
+ AddressingResolver,
+ IncomingMessage,
+)
@asynccontextmanager
@@ -32,21 +36,49 @@ def _no_connections() -> SimpleNamespace:
)
-def _event(body: str, formatted_body: str | None = None) -> SimpleNamespace:
- return SimpleNamespace(body=body, formatted_body=formatted_body)
+def _event(body: str, formatted_body: str | None = None) -> IncomingMessage:
+ return IncomingMessage(sender="@u:test", body=body, formatted_body=formatted_body)
+
+
+def _resolver(**attrs: object) -> SimpleNamespace:
+ """A resolver-shaped double with the named checks wired to the real ones.
+
+ Each check reads only the stores it needs, so a double carrying just those
+ is enough to run the real logic against.
+ """
+ resolver = SimpleNamespace(**attrs)
+ for name in ("mentions_name", "mentions_alias", "mentions_role"):
+ setattr(
+ resolver,
+ name,
+ (
+ lambda method: (
+ lambda *a, **kw: getattr(AddressingResolver, method)(
+ resolver, *a, **kw
+ )
+ )
+ )(name),
+ )
+ return resolver
def _client(name: str) -> SimpleNamespace:
- # Enough surface for the unbound _is_mentioned: an agent with a name and a
- # matrix_user_id for the formatted_body branch.
+ """An AgentClient-shaped double: an agent, an mxid, and a resolver."""
return SimpleNamespace(
agent=SimpleNamespace(name=name),
matrix_user_id=f"@switch-agent-{name}:switch.local",
+ _addressing=_resolver(),
+ _as_incoming=AgentClient._as_incoming,
)
def _is_mentioned(name: str, body: str) -> bool:
- return AgentClient._is_mentioned(_client(name), _event(body))
+ return AddressingResolver.mentions_name(
+ _resolver(),
+ agent=SimpleNamespace(name=name), # type: ignore[arg-type]
+ agent_matrix_id=f"@switch-agent-{name}:switch.local",
+ message=_event(body),
+ )
async def _command_addresses(name: str, args: str) -> bool:
@@ -127,12 +159,14 @@ class TestMediaEventWithoutFormattedBody:
def test_media_caption_mention_matches(self) -> None:
client = _client("cc-bug-fixing")
# A media event surfaces only `body` (the caption) — no formatted_body.
- media_event = SimpleNamespace(body="@cc-bug-fixing look at this")
+ media_event = SimpleNamespace(
+ body="@cc-bug-fixing look at this", content={}, sender="@u:test"
+ )
assert AgentClient._is_mentioned(client, media_event) is True
def test_media_without_mention_not_addressed(self) -> None:
client = _client("cc-bug-fixing")
- media_event = SimpleNamespace(body="cat.png")
+ media_event = SimpleNamespace(body="cat.png", content={}, sender="@u:test")
assert AgentClient._is_mentioned(client, media_event) is False
@@ -162,9 +196,10 @@ def _role_client(agent_name: str, held_role: str | None) -> SimpleNamespace:
return SimpleNamespace(
agent=SimpleNamespace(id="agent-1", name=agent_name),
- session_factory=_session_factory,
- _connections=_no_connections(),
- _room_role_store=SimpleNamespace(agent_room_role=_agent_room_role),
+ _addressing=_resolver(
+ _room_role_store=SimpleNamespace(agent_room_role=_agent_room_role),
+ _live_agent_ids=_no_connections().live_agent_ids,
+ ),
)
@@ -231,9 +266,9 @@ def _alias_client(agent_name: str, alias_by_room: dict[str, str]) -> SimpleNames
return SimpleNamespace(
agent=SimpleNamespace(id="agent-1", name=agent_name),
- session_factory=_session_factory,
- _connections=_no_connections(),
- _room_store=SimpleNamespace(get_alias=_get_alias),
+ _addressing=_resolver(
+ _room_store=SimpleNamespace(get_alias=_get_alias),
+ ),
)
diff --git a/core/tests/switch_core/clients/test_no_session_reply_threading.py b/core/tests/switch_core/clients/test_no_session_reply_threading.py
index 63abfc56b..e07f91a94 100644
--- a/core/tests/switch_core/clients/test_no_session_reply_threading.py
+++ b/core/tests/switch_core/clients/test_no_session_reply_threading.py
@@ -11,6 +11,7 @@ from switch_core.clients.agent_client import (
AgentClient,
_GateOutcome,
)
+from switch_core.transport import InboundMessage, RoomRef
@asynccontextmanager
@@ -92,25 +93,26 @@ def _fake_self(
return ns
-def _event(thread_id: str | None, *, is_auto_reply: bool = False) -> SimpleNamespace:
+def _event(thread_id: str | None, *, is_auto_reply: bool = False) -> InboundMessage:
content: dict[str, object] = {"sender_name": "louisa"}
- if thread_id is not None:
- content["m.relates_to"] = {"rel_type": "m.thread", "event_id": thread_id}
if is_auto_reply:
content[AUTO_REPLY_FLAG] = True
- return SimpleNamespace(
- body="@cc-bug-fixing can you help",
- sender="@switch-mattermost-louisa:switch.local",
+ return InboundMessage(
+ room_id="!matrix:server",
event_id="$trigger",
- server_timestamp=0,
- source={"content": content},
+ sender="@switch-mattermost-louisa:switch.local",
+ timestamp=0,
+ content=content,
+ body="@cc-bug-fixing can you help",
+ sender_name="louisa",
+ thread_root_id=thread_id,
)
@pytest.mark.asyncio
async def test_no_session_reply_threads_under_triggering_mention() -> None:
send_message = _Recorder()
- room = SimpleNamespace(room_id="!matrix:server")
+ room = RoomRef(room_id="!matrix:server")
await AgentClient.on_message(
_fake_self(send_message), room, _event(thread_id="$thread-root")
)
@@ -132,7 +134,7 @@ async def test_no_session_reply_not_triggered_by_another_auto_reply() -> None:
# must not ping-pong. A message already flagged as an auto-reply gets no
# reply, so the loop can never form.
send_message = _Recorder()
- room = SimpleNamespace(room_id="!matrix:server")
+ room = RoomRef(room_id="!matrix:server")
await AgentClient.on_message(
_fake_self(send_message),
room,
@@ -148,7 +150,7 @@ async def test_no_session_reply_does_not_double_tag_the_asker() -> None:
# configured operator). When that's the same person as the asker, we must
# tag them once, not "@louisa @louisa".
send_message = _Recorder()
- room = SimpleNamespace(room_id="!matrix:server")
+ room = RoomRef(room_id="!matrix:server")
await AgentClient.on_message(
_fake_self(
send_message, unavailable_reply="@louisa\n\nmy operator should run …"
@@ -168,7 +170,7 @@ async def test_no_session_reply_tags_distinct_asker_and_operator() -> None:
# When the reply's embedded mention is a DIFFERENT person (the operator),
# both the asker and that operator are tagged.
send_message = _Recorder()
- room = SimpleNamespace(room_id="!matrix:server")
+ room = RoomRef(room_id="!matrix:server")
await AgentClient.on_message(
_fake_self(
send_message, unavailable_reply="@operator\n\nmy operator should run …"
@@ -200,7 +202,7 @@ class TestStartingSessionNoticeGoesWhereItWasAsked:
@pytest.mark.asyncio
async def test_asked_at_the_root_it_answers_at_the_root(self) -> None:
send_message = _Recorder()
- room = SimpleNamespace(room_id="!matrix:server")
+ room = RoomRef(room_id="!matrix:server")
await AgentClient.on_message(
_fake_self(send_message, unavailable_reply=_STARTING_SESSION_MESSAGE),
@@ -217,7 +219,7 @@ class TestStartingSessionNoticeGoesWhereItWasAsked:
# The other half of the rule — replying at the root here would strand
# the notice away from the conversation it belongs to.
send_message = _Recorder()
- room = SimpleNamespace(room_id="!matrix:server")
+ room = RoomRef(room_id="!matrix:server")
await AgentClient.on_message(
_fake_self(send_message, unavailable_reply=_STARTING_SESSION_MESSAGE),
@@ -241,7 +243,7 @@ class TestTerminalReplyThreadsOffTheTrigger:
@pytest.mark.asyncio
async def test_asked_at_the_root_it_opens_a_thread_on_the_trigger(self) -> None:
send_message = _Recorder()
- room = SimpleNamespace(room_id="!matrix:server")
+ room = RoomRef(room_id="!matrix:server")
await AgentClient.on_message(
_fake_self(send_message), room, _event(thread_id=None)
@@ -255,7 +257,7 @@ class TestTerminalReplyThreadsOffTheTrigger:
# Already in a thread: the trigger's thread root IS that thread, so it
# lands there rather than starting a nested one.
send_message = _Recorder()
- room = SimpleNamespace(room_id="!matrix:server")
+ room = RoomRef(room_id="!matrix:server")
await AgentClient.on_message(
_fake_self(send_message), room, _event(thread_id="$thread-root")
diff --git a/core/tests/switch_core/clients/test_room_join_events.py b/core/tests/switch_core/clients/test_room_join_events.py
index 7585c8f73..a927dd61f 100644
--- a/core/tests/switch_core/clients/test_room_join_events.py
+++ b/core/tests/switch_core/clients/test_room_join_events.py
@@ -5,6 +5,7 @@ from types import SimpleNamespace
from switch_core.bridges.agent.protocol.types import AgentEvent, RoomJoinPayload
from switch_core.clients.agent_client import AgentClient, RoomMeta
+from switch_core.transport import InboundMembership, RoomRef
class _FakeQueue:
@@ -15,6 +16,19 @@ class _FakeQueue:
self.enqueued.append((agent_id, room_id, event))
+class _FakeClientStore:
+ """Resolves a matrix id to the Switch client that owns it, or nothing."""
+
+ def __init__(self, names: dict[str, str]) -> None:
+ self._names = names
+
+ async def get_by_matrix_user_id(
+ self, _session: object, matrix_user_id: str
+ ) -> object | None:
+ name = self._names.get(matrix_user_id)
+ return SimpleNamespace(display_name=name) if name else None
+
+
class _FakeRoomStore:
def __init__(self, receives: bool) -> None:
self._receives = receives
@@ -25,7 +39,12 @@ class _FakeRoomStore:
return self._receives
-def _client(meta: RoomMeta | None = None, *, receives: bool = True) -> SimpleNamespace:
+def _client(
+ meta: RoomMeta | None = None,
+ *,
+ receives: bool = True,
+ known: dict[str, str] | None = None,
+) -> SimpleNamespace:
"""A minimal fake `self` for the unbound AgentClient.on_member_event.
Stubs the event queue, agent identity, room-meta resolution, and the room
@@ -47,13 +66,21 @@ def _client(meta: RoomMeta | None = None, *, receives: bool = True) -> SimpleNam
async def _session_factory():
yield SimpleNamespace()
- return SimpleNamespace(
+ stub = SimpleNamespace(
_event_buffer=_FakeQueue(),
agent=SimpleNamespace(id="agent-1"),
_resolve_room_meta=_resolve_room_meta,
_room_store=_FakeRoomStore(receives),
+ client_store=_FakeClientStore(
+ {"@alice:switch.local": "Alice"} if known is None else known
+ ),
session_factory=_session_factory,
)
+ # Bound, so the handler resolves the name through the real implementation.
+ stub._member_name = lambda session, event: AgentClient._member_name(
+ stub, session, event
+ )
+ return stub
def _member_event(
@@ -62,23 +89,26 @@ def _member_event(
prev_membership: str | None = "leave",
state_key: str = "@alice:switch.local",
displayname: str | None = "Alice",
- server_timestamp: int = 123,
-) -> SimpleNamespace:
+ timestamp: int = 123,
+) -> InboundMembership:
content: dict[str, object] = {}
if displayname is not None:
content["displayname"] = displayname
- return SimpleNamespace(
+ return InboundMembership(
+ room_id="!matrix:switch.local",
+ event_id="$member",
+ sender=state_key,
+ timestamp=timestamp,
+ content=content,
+ state_key=state_key,
membership=membership,
prev_membership=prev_membership,
- state_key=state_key,
- content=content,
- server_timestamp=server_timestamp,
+ display_name=displayname,
)
-async def _run(client: SimpleNamespace, event: SimpleNamespace) -> None:
- room = SimpleNamespace(room_id="!matrix:switch.local")
- await AgentClient.on_member_event(client, room, event)
+async def _run(client: SimpleNamespace, event: InboundMembership) -> None:
+ await AgentClient.on_member_event(client, RoomRef("!matrix:switch.local"), event)
class TestRoomJoinEnqueue:
@@ -110,11 +140,22 @@ class TestRoomJoinEnqueue:
_, _, event = client._event_buffer.enqueued[0]
assert event.payload.listening is False
- async def test_missing_displayname_falls_back_to_localpart(self) -> None:
- client = _client()
+ async def test_the_member_is_named_the_way_switch_knows_them(self) -> None:
+ """A profile carries the source platform's spelling of a name; the log
+ records the Switch one. Delivering the profile name would make live
+ events and history disagree about the same person."""
+ client = _client(known={"@alice:switch.local": "alice"})
+ await _run(client, _member_event(displayname="Alice \U0001f495"))
+
+ _, _, event = client._event_buffer.enqueued[0]
+ assert event.payload.member_name == "alice"
+
+ async def test_a_member_no_switch_client_owns_falls_back_to_the_event(
+ self,
+ ) -> None:
+ client = _client(known={})
await _run(
- client,
- _member_event(displayname=None, state_key="@bob:switch.local"),
+ client, _member_event(displayname=None, state_key="@bob:switch.local")
)
assert len(client._event_buffer.enqueued) == 1
diff --git a/core/tests/switch_core/clients/test_self_join_dispatch.py b/core/tests/switch_core/clients/test_self_join_dispatch.py
index d09d923ca..cf308a12d 100644
--- a/core/tests/switch_core/clients/test_self_join_dispatch.py
+++ b/core/tests/switch_core/clients/test_self_join_dispatch.py
@@ -9,25 +9,41 @@ greeting unreachable on every room an agent is invited to, which is all of them.
from __future__ import annotations
-from types import SimpleNamespace
-
import pytest
from switch_core.clients.client_base import ClientBase
+from switch_core.transport import InboundMembership, RoomRef
MATRIX_ROOM_ID = "!matrix:switch.local"
SELF = "@switch-agent-1:switch.local"
+class _Recorder:
+ """Stands in for MessageRecorder, collecting the arrivals written."""
+
+ def __init__(self) -> None:
+ self.joins: list[str] = []
+ self.names: list[str] = []
+
+ async def record_join(
+ self, *, transport_room_id, event, client_id, member_name
+ ) -> None:
+ self.joins.append(event.event_id)
+ self.names.append(member_name)
+
+
class _Client(ClientBase):
def __init__(self) -> None:
self.matrix_user_id = SELF
+ self.client_id = "client-1"
+ self.display_name = "client one"
self.room_join_times = {}
self._room_joined_events = {}
self._self_join_dispatched = set()
self._startup_ts = 1000
self.self_joins: list[str] = []
self.member_events: list[str] = []
+ self.message_recorder = _Recorder()
async def on_self_join(self, room, event) -> None:
self.self_joins.append(room.room_id)
@@ -36,8 +52,8 @@ class _Client(ClientBase):
self.member_events.append(event.state_key)
-def _room() -> SimpleNamespace:
- return SimpleNamespace(room_id=MATRIX_ROOM_ID)
+def _room() -> RoomRef:
+ return RoomRef(room_id=MATRIX_ROOM_ID)
def _member_event(
@@ -45,15 +61,16 @@ def _member_event(
state_key: str = SELF,
membership: str = "join",
prev_membership: str | None = "invite",
- server_timestamp: int = 2000,
-) -> SimpleNamespace:
- return SimpleNamespace(
+ timestamp: int = 2000,
+) -> InboundMembership:
+ return InboundMembership(
+ room_id=MATRIX_ROOM_ID,
+ event_id="$member",
+ sender=state_key,
+ timestamp=timestamp,
state_key=state_key,
membership=membership,
prev_membership=prev_membership,
- server_timestamp=server_timestamp,
- sender=state_key,
- content={},
)
@@ -85,7 +102,7 @@ async def test_profile_update_is_not_an_arrival() -> None:
client = _Client()
await client._handle_member_event(
- _room(), _member_event(prev_membership="join", server_timestamp=3000)
+ _room(), _member_event(prev_membership="join", timestamp=3000)
)
assert client.self_joins == []
@@ -95,7 +112,7 @@ async def test_profile_update_is_not_an_arrival() -> None:
async def test_join_predating_this_process_is_not_announced() -> None:
client = _Client()
- await client._handle_member_event(_room(), _member_event(server_timestamp=500))
+ await client._handle_member_event(_room(), _member_event(timestamp=500))
assert client.self_joins == []
@@ -107,12 +124,10 @@ async def test_rejoining_after_leaving_is_a_fresh_arrival() -> None:
await client._handle_member_event(_room(), _member_event())
await client._handle_member_event(
_room(),
- _member_event(
- membership="leave", prev_membership="join", server_timestamp=3000
- ),
+ _member_event(membership="leave", prev_membership="join", timestamp=3000),
)
await client._handle_member_event(
- _room(), _member_event(prev_membership="leave", server_timestamp=4000)
+ _room(), _member_event(prev_membership="leave", timestamp=4000)
)
assert client.self_joins == [MATRIX_ROOM_ID, MATRIX_ROOM_ID]
@@ -127,3 +142,41 @@ async def test_another_member_joining_is_not_a_self_join() -> None:
assert client.self_joins == []
assert client.member_events == [other]
+
+
+async def test_an_arrival_is_logged_even_when_it_is_not_announced() -> None:
+ """Announcing and logging answer different questions.
+
+ A join older than this process is nobody's news, so it is not announced.
+ It is still how that participant got into the room, so it is still history.
+ """
+ client = _Client()
+
+ await client._handle_member_event(_room(), _member_event(timestamp=500))
+
+ assert client.self_joins == []
+ assert client.message_recorder.joins == ["$member"]
+
+
+async def test_a_profile_update_is_not_logged_as_an_arrival() -> None:
+ client = _Client()
+
+ await client._handle_member_event(
+ _room(), _member_event(prev_membership="join", timestamp=3000)
+ )
+
+ assert client.message_recorder.joins == []
+
+
+async def test_another_member_arriving_is_not_this_client_to_log() -> None:
+ """Each client logs its own arrival, which is what makes it one row."""
+ client = _Client()
+
+ await client._handle_member_event(
+ _room(), _member_event(state_key="@switch-agent-2:switch.local")
+ )
+
+ assert client.message_recorder.joins == []
diff --git a/core/tests/switch_core/clients/test_send_media.py b/core/tests/switch_core/clients/test_send_media.py
index dbb3a8122..5381be148 100644
--- a/core/tests/switch_core/clients/test_send_media.py
+++ b/core/tests/switch_core/clients/test_send_media.py
@@ -1,66 +1,51 @@
from __future__ import annotations
import pytest
-from nio import UploadError
from switch_core.clients.client_base import ClientBase
+from switch_core.transport import TransportError, UploadResult
+from tests.switch_core.transport.fake import FakeMessageRecorder, FakeTransport
-class _FakeSendResp:
- def __init__(self, event_id: str) -> None:
- self.event_id = event_id
+class _FailingUploadTransport(FakeTransport):
+ """Upload is the one media call that must not degrade to a None result."""
+ async def upload_media(
+ self, data: bytes, content_type: str, filename: str
+ ) -> UploadResult:
+ raise TransportError(f"Failed to upload media '{filename}'")
-class _FakeUploadResp:
- def __init__(self, content_uri: str) -> None:
- self.content_uri = content_uri
-
-class _FakeNio:
- def __init__(self, *, upload_result: object) -> None:
- self._upload_result = upload_result
- self.room_send_calls: list[tuple[str, str, dict]] = []
- self.upload_calls: list[dict] = []
-
- async def room_send(self, room_id: str, msgtype: str, content: dict):
- self.room_send_calls.append((room_id, msgtype, content))
- return _FakeSendResp("$evt")
-
- async def upload(self, **kwargs): # noqa: ANN003
- self.upload_calls.append(kwargs)
- return self._upload_result, None
-
-
-def _client(nio: _FakeNio) -> ClientBase:
+def _client(transport: FakeTransport) -> ClientBase:
client = object.__new__(ClientBase)
- client.nio_client = nio # type: ignore[attr-defined]
+ client.transport = transport # type: ignore[attr-defined]
client.display_name = "Alice" # type: ignore[attr-defined]
+ client.matrix_user_id = "@alice:switch.local" # type: ignore[attr-defined]
+ client.client_id = "client-1" # type: ignore[attr-defined]
+ client.message_recorder = FakeMessageRecorder() # type: ignore[assignment]
return client
async def test_upload_media_returns_content_uri() -> None:
- nio = _FakeNio(upload_result=_FakeUploadResp("mxc://s/abc"))
- client = _client(nio)
+ transport = FakeTransport(upload_uri="mxc://s/abc")
+ client = _client(transport)
mxc = await client.upload_media(b"bytes", "image/png", "cat.png")
assert mxc == "mxc://s/abc"
- assert nio.upload_calls[0]["content_type"] == "image/png"
- assert nio.upload_calls[0]["filename"] == "cat.png"
- assert nio.upload_calls[0]["filesize"] == 5
+ assert transport.uploads == [(b"bytes", "image/png", "cat.png")]
async def test_upload_media_raises_on_error() -> None:
- nio = _FakeNio(upload_result=UploadError("nope"))
- client = _client(nio)
+ client = _client(_FailingUploadTransport())
- with pytest.raises(RuntimeError, match="Failed to upload media"):
+ with pytest.raises(TransportError, match="Failed to upload media"):
await client.upload_media(b"bytes", "image/png", "cat.png")
-async def test_send_media_with_caption_sets_body_and_filename() -> None:
- nio = _FakeNio(upload_result=_FakeUploadResp("mxc://s/abc"))
- client = _client(nio)
+async def test_send_media_with_caption_passes_caption_and_filename_through() -> None:
+ transport = FakeTransport()
+ client = _client(transport)
event_id = await client.send_media(
"!room",
@@ -72,26 +57,38 @@ async def test_send_media_with_caption_sets_body_and_filename() -> None:
caption="look at this",
)
- assert event_id == "$evt"
- _, msgtype, content = nio.room_send_calls[0]
- assert msgtype == "m.room.message"
- assert content["msgtype"] == "m.image"
- # Caption convention: body is the caption, filename carried separately.
- assert content["body"] == "look at this"
- assert content["filename"] == "cat.png"
- assert content["url"] == "mxc://s/abc"
- assert content["info"] == {"mimetype": "image/png", "size": 1234}
- assert content["sender_name"] == "Alice"
+ assert event_id == "$fake1"
+ sent = transport.sent_media[0]
+ assert sent["room_id"] == "!room"
+ assert sent["msgtype"] == "m.image"
+ # Caption convention: the caption travels beside the real filename, so the
+ # transport can put one in `body` and carry the other separately.
+ assert sent["caption"] == "look at this"
+ assert sent["filename"] == "cat.png"
+ assert sent["uri"] == "mxc://s/abc"
+ assert sent["mimetype"] == "image/png"
+ assert sent["size"] == 1234
+ assert sent["sender_name"] == "Alice"
-async def test_send_media_without_caption_uses_filename_as_body() -> None:
- nio = _FakeNio(upload_result=_FakeUploadResp("mxc://s/abc"))
- client = _client(nio)
+async def test_send_media_without_caption_sends_no_caption() -> None:
+ transport = FakeTransport()
+ client = _client(transport)
await client.send_media(
"!room", "mxc://s/abc", "cat.png", "image/png", 1234, msgtype="m.image"
)
- _, _, content = nio.room_send_calls[0]
- assert content["body"] == "cat.png"
- assert "filename" not in content
+ sent = transport.sent_media[0]
+ assert sent["caption"] is None
+ assert sent["filename"] == "cat.png"
+
+
+async def test_send_media_returns_none_when_the_transport_rejects_it() -> None:
+ client = _client(FakeTransport(fail_send="nope"))
+
+ result = await client.send_media(
+ "!room", "mxc://s/abc", "cat.png", "image/png", 1234, msgtype="m.image"
+ )
+
+ assert result is None
diff --git a/core/tests/switch_core/clients/test_send_recording.py b/core/tests/switch_core/clients/test_send_recording.py
new file mode 100644
index 000000000..90ac04366
--- /dev/null
+++ b/core/tests/switch_core/clients/test_send_recording.py
@@ -0,0 +1,136 @@
+"""A client records every kind of send, and records nothing it did not send.
+
+The recorder is only as good as the set of sends that reach it. Messages,
+media and custom events each take a different route out of `ClientBase`, so
+each is checked here rather than trusting that instrumenting one instrumented
+the others.
+
+The negative cases carry as much weight. A row for a message the transport
+rejected would be a record of something that never happened, which is worse
+than no record at all.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from switch_core.clients.client_base import ClientBase, ClientConfig
+from switch_core.transport import TransportError
+from tests.switch_core.transport.fake import FakeMessageRecorder, FakeTransport
+
+
+def _client(
+ transport: FakeTransport,
+) -> tuple[ClientBase[ClientConfig], FakeMessageRecorder]:
+ recorder = FakeMessageRecorder()
+ client: ClientBase[ClientConfig] = object.__new__(ClientBase)
+ client.transport = transport
+ client.message_recorder = recorder
+ client.matrix_user_id = "@agent:test"
+ client.client_id = "client-1"
+ client.display_name = "agent one"
+ return client, recorder
+
+
+class TestEverySendIsRecorded:
+ async def test_a_message(self) -> None:
+ transport = FakeTransport()
+ client, recorder = _client(transport)
+
+ event_id = await client.send_message("!room:test", "hello")
+
+ assert len(recorder.recorded) == 1
+ recorded = recorder.recorded[0]
+ assert recorded["transport_room_id"] == "!room:test"
+ assert recorded["result"].event_id == event_id
+ assert recorded["result"].content["body"] == "hello"
+ assert recorded["sender_matrix_id"] == "@agent:test"
+ assert recorded["sender_client_id"] == "client-1"
+ assert recorded["sender_name"] == "agent one"
+
+ async def test_a_custom_event(self) -> None:
+ transport = FakeTransport()
+ client, recorder = _client(transport)
+
+ event_id = await client.send_event(
+ "!room:test", "com.switch.command", {"command": "reset"}
+ )
+
+ assert len(recorder.recorded) == 1
+ result = recorder.recorded[0]["result"]
+ assert result.event_id == event_id
+ assert result.event_type == "com.switch.command"
+ assert result.content == {"command": "reset"}
+
+ async def test_media(self) -> None:
+ transport = FakeTransport()
+ client, recorder = _client(transport)
+
+ event_id = await client.send_media(
+ "!room:test",
+ "mxc://test/abc",
+ "chart.png",
+ "image/png",
+ 4096,
+ msgtype="m.image",
+ )
+
+ assert len(recorder.recorded) == 1
+ result = recorder.recorded[0]["result"]
+ assert result.event_id == event_id
+ assert result.content["url"] == "mxc://test/abc"
+
+ async def test_what_is_recorded_is_what_the_transport_sent(self) -> None:
+ """The recorder is handed the transport's own content dict.
+
+ Reconstructing it at the client would drift from the transport the
+ first time the wire format changed, and nothing would notice.
+ """
+ transport = FakeTransport()
+ client, recorder = _client(transport)
+
+ await client.send_message(
+ "!room:test", "**bold**", format="markdown", thread_root_id="$root"
+ )
+
+ content = recorder.recorded[0]["result"].content
+ assert content["m.relates_to"] == {
+ "rel_type": "m.thread",
+ "event_id": "$root",
+ }
+
+
+class TestNothingIsRecordedForASendThatFailed:
+ async def test_a_failed_message(self) -> None:
+ transport = FakeTransport(fail_send="homeserver said no")
+ client, recorder = _client(transport)
+
+ assert await client.send_message("!room:test", "hello") is None
+ assert recorder.recorded == []
+
+ async def test_a_failed_media_send(self) -> None:
+ transport = FakeTransport(fail_send="homeserver said no")
+ client, recorder = _client(transport)
+
+ result = await client.send_media(
+ "!room:test",
+ "mxc://test/abc",
+ "chart.png",
+ "image/png",
+ 4096,
+ msgtype="m.image",
+ )
+
+ assert result is None
+ assert recorder.recorded == []
+
+ async def test_a_failed_custom_event_raises_and_records_nothing(self) -> None:
+ """Unlike a chat message, a custom event carries protocol state, so the
+ caller is told rather than left to assume it landed."""
+ transport = FakeTransport(fail_send="homeserver said no")
+ client, recorder = _client(transport)
+
+ with pytest.raises(TransportError):
+ await client.send_event("!room:test", "com.switch.command", {})
+
+ assert recorder.recorded == []
diff --git a/core/tests/switch_core/clients/test_sync_cursor_persistence.py b/core/tests/switch_core/clients/test_sync_cursor_persistence.py
index 4691e5ec5..0d4fe4743 100644
--- a/core/tests/switch_core/clients/test_sync_cursor_persistence.py
+++ b/core/tests/switch_core/clients/test_sync_cursor_persistence.py
@@ -8,6 +8,11 @@ pool on an otherwise idle instance.
Two properties fix that and are asserted here: an idle sync does not earn a
write at all, and the clients that do write are spread out rather than aligned.
+
+Whether a given batch counted as idle is the transport's judgement, not this
+one's — it is the only thing that can see what the batch held, and it says so
+as the `durable` flag these tests pass in. What that flag is derived from is
+covered in `tests/switch_core/transport/test_sync_durability.py`.
"""
from __future__ import annotations
@@ -15,15 +20,6 @@ from __future__ import annotations
import time
import pytest
-from nio import (
- DeviceList,
- DeviceOneTimeKeyCount,
- InviteInfo,
- RoomInfo,
- Rooms,
- SyncResponse,
- Timeline,
-)
from switch_core.clients.client_base import (
SYNC_STATE_INTERVAL,
@@ -31,6 +27,7 @@ from switch_core.clients.client_base import (
SYNC_STATE_MAX_STALENESS,
ClientBase,
)
+from tests.switch_core.transport.fake import FakeMessageRecorder
ROOM = "!room:switch.local"
@@ -57,8 +54,6 @@ class _Store:
session: object,
client_id: str,
*,
- access_token: str | None,
- device_id: str | None,
next_batch_token: str | None,
) -> None:
self.writes.append(next_batch_token)
@@ -81,6 +76,9 @@ class _Client(ClientBase):
session_factory=_Session, # type: ignore[arg-type]
client_store=_Store(), # type: ignore[arg-type]
config=ClientBase.config_class(),
+ transport_factory=lambda client: object(), # type: ignore[arg-type,return-value]
+ session_state={},
+ message_recorder=FakeMessageRecorder(),
next_batch_token="s0",
)
# Pin the jittered interval so the throttle assertions are deterministic.
@@ -92,39 +90,6 @@ class _Client(ClientBase):
return store.writes
-def _sync(
- next_batch: str,
- *,
- timeline: list[object] | None = None,
- state: list[object] | None = None,
- ephemeral: list[object] | None = None,
- invite: bool = False,
- to_device: list[object] | None = None,
-) -> SyncResponse:
- join = {
- ROOM: RoomInfo(
- timeline=Timeline(
- events=list(timeline or []), limited=False, prev_batch=None
- ),
- state=list(state or []),
- ephemeral=list(ephemeral or []),
- account_data=[],
- )
- }
- return SyncResponse(
- next_batch=next_batch,
- rooms=Rooms(
- invite={ROOM: InviteInfo(invite_state=[])} if invite else {},
- join=join,
- leave={},
- ),
- device_key_count=DeviceOneTimeKeyCount(curve25519=None, signed_curve25519=None),
- device_list=DeviceList(changed=[], left=[]),
- to_device_events=list(to_device or []),
- presence_events=[],
- )
-
-
@pytest.mark.asyncio
async def test_idle_sync_advances_the_cursor_without_writing() -> None:
"""The overnight case: nothing happened, so nothing is worth persisting.
@@ -136,7 +101,7 @@ async def test_idle_sync_advances_the_cursor_without_writing() -> None:
client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL
for i in range(1, 6):
- await client._handle_sync(_sync(f"s{i}"))
+ await client._handle_sync(f"s{i}", False)
assert client.writes == []
# The cursor still moved, so the next sync does not refetch.
@@ -145,34 +110,24 @@ async def test_idle_sync_advances_the_cursor_without_writing() -> None:
@pytest.mark.asyncio
-async def test_ephemeral_only_sync_does_not_earn_a_write() -> None:
+async def test_a_batch_the_transport_called_idle_does_not_earn_a_write() -> None:
"""Typing notices and read receipts advance the token and mean nothing."""
client = _Client()
client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL
- await client._handle_sync(_sync("s1", ephemeral=[object()]))
+ await client._handle_sync("s1", False)
assert client.writes == []
assert client.next_batch_token == "s1"
@pytest.mark.asyncio
- "kwargs",
- [
- {"timeline": [object()]},
- {"state": [object()]},
- {"invite": True},
- {"to_device": [object()]},
- ],
- ids=["timeline", "state", "invite", "to_device"],
-)
-async def test_durable_events_are_persisted(kwargs: dict[str, object]) -> None:
+async def test_durable_events_are_persisted() -> None:
"""Anything a restart would replay to a handler must move the cursor."""
client = _Client()
client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL
- await client._handle_sync(_sync("s1", **kwargs)) # type: ignore[arg-type]
+ await client._handle_sync("s1", True)
assert client.writes == ["s1"]
@@ -183,11 +138,11 @@ async def test_a_stale_cursor_is_flushed_even_while_idle() -> None:
client = _Client()
client._last_sync_persist = time.monotonic() - (SYNC_STATE_MAX_STALENESS - 1)
- await client._handle_sync(_sync("s1"))
+ await client._handle_sync("s1", False)
assert client.writes == []
client._last_sync_persist = time.monotonic() - (SYNC_STATE_MAX_STALENESS + 1)
- await client._handle_sync(_sync("s2"))
+ await client._handle_sync("s2", False)
assert client.writes == ["s2"]
assert client._sync_state_dirty is False
@@ -199,9 +154,9 @@ async def test_busy_clients_are_still_throttled() -> None:
client = _Client()
client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL
- await client._handle_sync(_sync("s1", timeline=[object()]))
- await client._handle_sync(_sync("s2", timeline=[object()]))
- await client._handle_sync(_sync("s3", timeline=[object()]))
+ await client._handle_sync("s1", True)
+ await client._handle_sync("s2", True)
+ await client._handle_sync("s3", True)
assert client.writes == ["s1"]
assert client.next_batch_token == "s3"
@@ -212,7 +167,7 @@ async def test_an_unchanged_cursor_is_ignored() -> None:
client = _Client()
client._last_sync_persist = time.monotonic() - 10 * SYNC_STATE_INTERVAL
- await client._handle_sync(_sync("s0", timeline=[object()]))
+ await client._handle_sync("s0", True)
assert client.writes == []
@@ -229,6 +184,9 @@ def _real_clients(count: int) -> list[ClientBase]:
session_factory=None, # type: ignore[arg-type]
client_store=None, # type: ignore[arg-type]
config=ClientBase.config_class(),
+ transport_factory=lambda client: object(), # type: ignore[arg-type,return-value]
+ session_state={},
+ message_recorder=FakeMessageRecorder(),
)
for i in range(count)
]
diff --git a/core/tests/switch_core/clients/test_system_message_never_addresses.py b/core/tests/switch_core/clients/test_system_message_never_addresses.py
index 6eec62196..ae02e66a5 100644
--- a/core/tests/switch_core/clients/test_system_message_never_addresses.py
+++ b/core/tests/switch_core/clients/test_system_message_never_addresses.py
@@ -23,17 +23,21 @@ import pytest
from switch_core.clients.admin_messages import ADMIN_MARKER, admin_extra_content
from switch_core.clients.agent_client import AgentClient
from switch_core.clients.room_meta import RoomMeta
+from switch_core.delivery.addressing import AddressingResolver
+from switch_core.transport import InboundMessage
-def _event(body: str, *, admin: bool = False) -> SimpleNamespace:
+def _event(body: str, *, admin: bool = False) -> InboundMessage:
content: dict = {"body": body}
if admin:
content.update(admin_extra_content(None))
- return SimpleNamespace(
- body=body,
- formatted_body=None,
+ return InboundMessage(
+ room_id="!room:server",
+ event_id="$evt",
sender="@switch-admin:switch.local",
- source={"content": content},
+ timestamp=1,
+ content=content,
+ body=body,
)
@@ -42,7 +46,12 @@ def _meta(channel_type: str) -> RoomMeta:
def _client(name: str = "flintai-sdk.ts") -> SimpleNamespace:
- client = SimpleNamespace(
+ """A resolver with the two store-backed checks stubbed out.
+
+ Only the name mention is left live: alias and role routing have their own
+ tests, and what these pin is that the marker beats all three.
+ """
+ resolver = SimpleNamespace(
agent=SimpleNamespace(name=name),
matrix_user_id=f"@switch-agent-{name}:switch.local",
)
@@ -50,17 +59,31 @@ def _client(name: str = "flintai-sdk.ts") -> SimpleNamespace:
async def _no(*_a: object, **_k: object) -> bool:
return False
- client._is_mentioned = lambda event: AgentClient._is_mentioned(client, event)
- client._addressed_without_lookup = lambda event, meta: (
- AgentClient._addressed_without_lookup(client, event, meta)
+ resolver.mentions_name = lambda **kw: AddressingResolver.mentions_name(
+ resolver, **kw
+ )
+ resolver.addressed_without_lookup = lambda **kw: (
+ AddressingResolver.addressed_without_lookup(resolver, **kw)
+ )
+ resolver.mentions_alias = _no
+ resolver.mentions_role = _no
+ return resolver
+
+
+async def _addressed(
+ resolver: SimpleNamespace, event: InboundMessage, meta: RoomMeta
+) -> bool:
+ # `object()` stands in for the session the caller owns: the marker and the
+ # name mention are answered before any store is consulted.
+ return await AddressingResolver.addresses(
+ resolver,
+ object(),
+ agent=resolver.agent,
+ agent_matrix_id=resolver.matrix_user_id,
+ room_id=meta.room_id,
+ channel_type=meta.channel_type,
+ message=AgentClient._as_incoming(event),
)
- client._is_mentioned_via_alias = _no
- client._is_mentioned_via_role = _no
- return client
-
-
-async def _addressed(client: SimpleNamespace, event: object, meta: RoomMeta) -> bool:
- return await AgentClient._compute_addressed(client, None, event, meta)
@pytest.mark.asyncio
@@ -103,7 +126,7 @@ async def test_the_marker_alone_is_enough_whatever_type_it_carries() -> None:
from switch_core.clients.admin_messages import AdminMessageType
event = _event("Added flintai-sdk.ts to this room.")
- event.source["content"].update(admin_extra_content(AdminMessageType.COMMAND_RESULT))
- assert ADMIN_MARKER in event.source["content"]
+ event.content.update(admin_extra_content(AdminMessageType.COMMAND_RESULT))
+ assert ADMIN_MARKER in event.content
assert await _addressed(_client(), event, _meta("direct")) is False
diff --git a/core/tests/switch_core/clients/test_wait_joined_existing_membership.py b/core/tests/switch_core/clients/test_wait_joined_existing_membership.py
index 0f970e225..6ff386e4b 100644
--- a/core/tests/switch_core/clients/test_wait_joined_existing_membership.py
+++ b/core/tests/switch_core/clients/test_wait_joined_existing_membership.py
@@ -1,32 +1,31 @@
from __future__ import annotations
import asyncio
-from types import SimpleNamespace
import pytest
-from nio import JoinedRoomsError
from switch_core.clients.client_base import ClientBase
+from tests.switch_core.transport.fake import FakeTransport
MATRIX_ROOM_ID = "!matrix:switch.local"
-class _FakeNioClient:
- def __init__(self, rooms: list[str] | None) -> None:
- self._rooms = rooms
+class _CountingTransport(FakeTransport):
+ """Counts membership lookups so the caching assertions stay meaningful."""
+
+ def __init__(self, joined: list[str]) -> None:
+ super().__init__(joined=joined)
self.calls = 0
- async def joined_rooms(self) -> object:
+ async def joined_rooms(self) -> list[str]:
self.calls += 1
- if self._rooms is None:
- return JoinedRoomsError(message="boom")
- return SimpleNamespace(rooms=list(self._rooms))
+ return await super().joined_rooms()
-def _client(nio_client: _FakeNioClient) -> ClientBase:
+def _client(transport: FakeTransport) -> ClientBase:
client = ClientBase.__new__(ClientBase)
client.matrix_user_id = "@ext_alice:switch.local"
- client.nio_client = nio_client
+ client.transport = transport
client.room_join_times = {}
client._room_joined_events = {}
client._startup_ts = 1000
@@ -37,23 +36,22 @@ async def test_wait_joined_accepts_membership_that_predates_this_process() -> No
"""A puppet joined in an earlier run replays no member event: the client
resumes from a stored next_batch token, and re-inviting an existing member
is a no-op. Waiting on sync alone times out and the message is dropped."""
- nio_client = _FakeNioClient([MATRIX_ROOM_ID])
- client = _client(nio_client)
+ transport = _CountingTransport([MATRIX_ROOM_ID])
+ client = _client(transport)
assert await client.wait_joined(MATRIX_ROOM_ID, 0.05) is True
- assert nio_client.calls == 1
+ assert transport.calls == 1
# The join predates startup, so it must not shift the ignore cutoff forward
# and suppress events already in flight.
assert client.room_join_times[MATRIX_ROOM_ID] == client._startup_ts
# Membership is cached — no second round trip.
assert await client.wait_joined(MATRIX_ROOM_ID, 0.05) is True
- assert nio_client.calls == 1
+ assert transport.calls == 1
async def test_wait_joined_still_waits_for_a_pending_join() -> None:
- nio_client = _FakeNioClient([])
- client = _client(nio_client)
+ client = _client(_CountingTransport([]))
async def join_late() -> None:
await asyncio.sleep(0.01)
@@ -65,16 +63,20 @@ async def test_wait_joined_still_waits_for_a_pending_join() -> None:
async def test_wait_joined_times_out_when_the_join_never_lands() -> None:
- client = _client(_FakeNioClient([]))
+ client = _client(_CountingTransport([]))
assert await client.wait_joined(MATRIX_ROOM_ID, 0.05) is False
-async def test_wait_joined_falls_back_to_waiting_when_the_lookup_fails() -> None:
- nio_client = _FakeNioClient(None)
- client = _client(nio_client)
+async def test_wait_joined_falls_back_to_waiting_when_the_lookup_reports_nothing() -> (
+ None
+):
+ """A failed membership lookup degrades to "no rooms" at the transport, so
+ the client must wait rather than record a join it never observed."""
+ transport = _CountingTransport([])
+ client = _client(transport)
assert await client.wait_joined(MATRIX_ROOM_ID, 0.05) is False
- assert nio_client.calls == 1
+ assert transport.calls == 1
assert MATRIX_ROOM_ID not in client.room_join_times
diff --git a/core/tests/switch_core/db/stores/test_delivery_cursor_store.py b/core/tests/switch_core/db/stores/test_delivery_cursor_store.py
new file mode 100644
index 000000000..9736f7352
--- /dev/null
+++ b/core/tests/switch_core/db/stores/test_delivery_cursor_store.py
@@ -0,0 +1,146 @@
+"""A delivery cursor moves forward and only forward."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import Agent, ApiKey, Client, Room, User
+from switch_core.db.stores.delivery_cursor_store import DeliveryCursorStore
+
+
+async def _agent(session: AsyncSession) -> Agent:
+ """Minimal User → ApiKey → Client → Agent chain."""
+ name = f"agent-{uuid.uuid4().hex[:8]}"
+ user = User(name=name, email=f"{name}@test", role="user", password_hash="x")
+ session.add(user)
+ await session.flush()
+ api_key = ApiKey(
+ user_id=user.id,
+ key_hash=f"hash-{name}",
+ encrypted_key="enc",
+ label=name,
+ type="agent",
+ )
+ client = Client(
+ matrix_user_id=f"@{name}:test", display_name=name, type="agent", password="x"
+ )
+ session.add_all([api_key, client])
+ await session.flush()
+ agent = Agent(
+ name=name,
+ description="",
+ agent_type="always_on",
+ connector_type="claude_code",
+ integration_profile={"connection_model": "always_on"},
+ client_id=client.id,
+ api_key_id=api_key.id,
+ )
+ session.add(agent)
+ await session.flush()
+ return agent
+
+
+async def _make_agent_and_room(session: AsyncSession) -> tuple[str, str]:
+ room = Room(
+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",
+ name="a room",
+ description="",
+ )
+ session.add(room)
+ agent = await _agent(session)
+ await session.flush()
+ return agent.id, room.id
+
+
+class TestPosition:
+ async def test_an_agent_that_was_never_delivered_is_at_zero(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Zero, not an error: `seq` starts at 1, so zero already says
+ "behind everything"."""
+ async with session_factory() as session:
+ agent_id, room_id = await _make_agent_and_room(session)
+ await session.commit()
+
+ store = DeliveryCursorStore()
+ assert await store.position(session, agent_id, room_id) == 0
+
+ async def test_a_cursor_reads_back_where_it_was_left(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ agent_id, room_id = await _make_agent_and_room(session)
+ store = DeliveryCursorStore()
+ await store.advance(session, agent_id, room_id, 7)
+ await session.commit()
+
+ assert await store.position(session, agent_id, room_id) == 7
+
+ async def test_positions_omit_agents_that_have_none(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Absent rather than zero, so a caller can tell an agent that has
+ never been delivered from one sitting at the start."""
+ async with session_factory() as session:
+ first, room_id = await _make_agent_and_room(session)
+ second = await _agent(session)
+ session.add(second)
+ await session.flush()
+
+ store = DeliveryCursorStore()
+ await store.advance(session, first, room_id, 3)
+ await session.commit()
+
+ positions = await store.positions_in(session, room_id, [first, second.id])
+
+ assert positions == {first: 3}
+
+
+class TestAdvancing:
+ async def test_advancing_twice_keeps_the_further_position(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ agent_id, room_id = await _make_agent_and_room(session)
+ store = DeliveryCursorStore()
+ await store.advance(session, agent_id, room_id, 4)
+ await store.advance(session, agent_id, room_id, 9)
+ await session.commit()
+
+ assert await store.position(session, agent_id, room_id) == 9
+
+ async def test_a_late_write_cannot_rewind_the_cursor(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Two deliveries can finish out of order. The later write must not
+ undo the further one, because rewinding redelivers and a redelivered
+ message is indistinguishable from a new one."""
+ async with session_factory() as session:
+ agent_id, room_id = await _make_agent_and_room(session)
+ store = DeliveryCursorStore()
+ await store.advance(session, agent_id, room_id, 9)
+ await store.advance(session, agent_id, room_id, 4)
+ await session.commit()
+
+ assert await store.position(session, agent_id, room_id) == 9
+
+ async def test_cursors_in_different_rooms_are_independent(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ agent_id, first_room = await _make_agent_and_room(session)
+ second_room = Room(
+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",
+ name="another room",
+ description="",
+ )
+ session.add(second_room)
+ await session.flush()
+
+ store = DeliveryCursorStore()
+ await store.advance(session, agent_id, first_room, 5)
+ await session.commit()
+
+ assert await store.position(session, agent_id, second_room.id) == 0
diff --git a/core/tests/switch_core/db/stores/test_message_store.py b/core/tests/switch_core/db/stores/test_message_store.py
new file mode 100644
index 000000000..3e1507b35
--- /dev/null
+++ b/core/tests/switch_core/db/stores/test_message_store.py
@@ -0,0 +1,458 @@
+"""`MessageStore` against real Postgres.
+
+Catches the mistakes a mock or SQLite cannot: an attachment order that only
+holds by accident of insertion, a `seq` that is not a gap-free total order to
+page on, a `transport_event_id` that admits a duplicate, and FK actions
+(`ON DELETE CASCADE` / `SET NULL`) that are declared but not enforced.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+
+import pytest
+from sqlalchemy import delete
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import Client, Message, MessageAttachment, Room
+from switch_core.db.stores.message_store import MessageStore
+
+
+async def _make_room(session: AsyncSession, name: str) -> Room:
+ room = Room(
+ matrix_room_id=f"!{name}-{uuid.uuid4().hex[:8]}:test",
+ name=name,
+ description=f"{name} desc",
+ )
+ session.add(room)
+ await session.flush()
+ return room
+
+
+async def _make_client(session: AsyncSession, name: str) -> Client:
+ client = Client(
+ matrix_user_id=f"@{name}-{uuid.uuid4().hex[:8]}:test",
+ display_name=name,
+ type="agent",
+ password="x",
+ )
+ session.add(client)
+ await session.flush()
+ return client
+
+
+def _message(room_id: str, event_id: str, **overrides: object) -> Message:
+ fields: dict[str, object] = {
+ "room_id": room_id,
+ "transport_event_id": event_id,
+ "sender_matrix_id": "@sender:test",
+ "event_type": "m.room.message",
+ "msgtype": "m.text",
+ "body": f"body of {event_id}",
+ "content": {"msgtype": "m.text", "body": f"body of {event_id}"},
+ }
+ fields.update(overrides)
+ return Message(**fields)
+
+
+class TestCreate:
+ async def test_create_and_read_back_by_transport_event_id(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ await store.create(session, _message(room.id, "$evt1"), [])
+ await session.commit()
+
+ found = await store.get_by_transport_event_id(session, "$evt1")
+
+ assert found is not None
+ assert found.room_id == room.id
+ assert found.body == "body of $evt1"
+ assert found.content == {"msgtype": "m.text", "body": "body of $evt1"}
+ assert found.sent_at is not None
+
+ async def test_miss_returns_none(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ assert await store.get_by_transport_event_id(session, "$nope") is None
+
+ async def test_duplicate_transport_event_id_rejected(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The same send recorded twice must not produce two rows."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ await store.create(session, _message(room.id, "$dup"), [])
+ await session.commit()
+
+ with pytest.raises(IntegrityError):
+ await store.create(session, _message(room.id, "$dup"), [])
+
+
+class TestAttachments:
+ async def test_attachments_numbered_and_returned_in_send_order(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ message = await store.create(
+ session,
+ _message(room.id, "$files"),
+ [
+ MessageAttachment(uri="mxc://a", filename="a.txt"),
+ MessageAttachment(uri="mxc://b", filename="b.txt"),
+ MessageAttachment(uri="mxc://c", filename="c.txt"),
+ ],
+ )
+ await session.commit()
+
+ attachments = await store.get_attachments(session, message.id)
+
+ assert [a.position for a in attachments] == [0, 1, 2]
+ assert [a.filename for a in attachments] == ["a.txt", "b.txt", "c.txt"]
+
+ async def test_get_attachments_orders_by_position_not_insertion(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Rows written out of order still read back in send order."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ message = await store.create(session, _message(room.id, "$files"), [])
+ await session.commit()
+
+ for position, name in ((2, "c.txt"), (0, "a.txt"), (1, "b.txt")):
+ session.add(
+ MessageAttachment(
+ message_id=message.id,
+ position=position,
+ uri=f"mxc://{name}",
+ filename=name,
+ )
+ )
+ await session.commit()
+
+ attachments = await store.get_attachments(session, message.id)
+
+ assert [a.filename for a in attachments] == ["a.txt", "b.txt", "c.txt"]
+
+ async def test_attachments_scoped_to_their_message(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ first = await store.create(
+ session,
+ _message(room.id, "$one"),
+ [MessageAttachment(uri="mxc://a", filename="a.txt")],
+ )
+ second = await store.create(
+ session,
+ _message(room.id, "$two"),
+ [MessageAttachment(uri="mxc://b", filename="b.txt")],
+ )
+ await session.commit()
+
+ assert [
+ a.filename for a in await store.get_attachments(session, first.id)
+ ] == ["a.txt"]
+ assert [
+ a.filename for a in await store.get_attachments(session, second.id)
+ ] == ["b.txt"]
+
+
+class TestSeq:
+ async def test_seq_is_database_assigned_and_strictly_increasing(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ messages = [
+ await store.create(session, _message(room.id, f"$evt{i}"), [])
+ for i in range(5)
+ ]
+ await session.commit()
+ seqs = [m.seq for m in messages]
+
+ assert all(seq is not None for seq in seqs)
+ assert seqs == sorted(seqs)
+ assert len(set(seqs)) == len(seqs)
+
+ async def test_the_store_owns_seq_not_the_caller(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A caller that picked its own number could hand a reader a value it
+ has already paged past."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ created = await store.create(
+ session, _message(room.id, "$forced", seq=999), []
+ )
+ await session.commit()
+
+ assert created.seq == 1
+
+ async def test_seq_starts_at_one_in_every_room(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Numbering is per room, so one busy room does not push another
+ room's first message to a large number."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room_a = await _make_room(session, "alpha")
+ room_b = await _make_room(session, "beta")
+ a1 = await store.create(session, _message(room_a.id, "$a1"), [])
+ a2 = await store.create(session, _message(room_a.id, "$a2"), [])
+ b1 = await store.create(session, _message(room_b.id, "$b1"), [])
+ await session.commit()
+
+ assert (a1.seq, a2.seq, b1.seq) == (1, 2, 1)
+
+ async def test_two_rooms_may_hold_the_same_seq(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The uniqueness that matters is per room. A global constraint would
+ reject this, and it is not a conflict."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room_a = await _make_room(session, "alpha")
+ room_b = await _make_room(session, "beta")
+ await store.create(session, _message(room_a.id, "$a1"), [])
+ await store.create(session, _message(room_b.id, "$b1"), [])
+ await session.commit()
+
+ async def test_a_room_cannot_hold_the_same_seq_twice(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The constraint is what makes the cursor trustworthy, so prove it is
+ really on the table rather than only in the store's arithmetic."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ await store.create(session, _message(room.id, "$a1"), [])
+ await session.commit()
+ room_id = room.id
+
+ async with session_factory() as session:
+ duplicate = _message(room_id, "$a2", seq=1)
+ session.add(duplicate)
+ with pytest.raises(IntegrityError):
+ await session.commit()
+
+
+class TestSeqUnderConcurrency:
+ """The reason `seq` is not an identity column.
+
+ A sequence allocates when the INSERT runs, so two concurrent writers take
+ their numbers immediately and may commit in the other order — leaving a
+ row visible only *behind* a cursor that has already moved past it. These
+ tests hold one transaction open and watch what the other one does, which
+ is the only way to tell the two designs apart.
+ """
+
+ async def test_a_second_writer_to_the_same_room_waits(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ await session.commit()
+ room_id = room.id
+
+ async with session_factory() as holder:
+ first = await store.create(holder, _message(room_id, "$first"), [])
+ assert first.seq == 1
+
+ async with session_factory() as waiter:
+ blocked = asyncio.ensure_future(
+ store.create(waiter, _message(room_id, "$second"), [])
+ )
+ with pytest.raises(TimeoutError):
+ await asyncio.wait_for(asyncio.shield(blocked), timeout=0.5)
+
+ # Releasing the lock is what lets the second writer number
+ # itself, and it can only do so after the first is committed.
+ await holder.commit()
+ second = await blocked
+ await waiter.commit()
+
+ assert second.seq == 2
+
+ async def test_writers_to_different_rooms_do_not_wait(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Serialising every room against every other one would make this a
+ global write lock, which is not the trade being made."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room_a = await _make_room(session, "alpha")
+ room_b = await _make_room(session, "beta")
+ await session.commit()
+ room_a_id, room_b_id = room_a.id, room_b.id
+
+ async with session_factory() as holder, session_factory() as other:
+ await store.create(holder, _message(room_a_id, "$a1"), [])
+ created = await asyncio.wait_for(
+ store.create(other, _message(room_b_id, "$b1"), []), timeout=5
+ )
+ await other.commit()
+ await holder.commit()
+
+ assert created.seq == 1
+
+
+class TestListForRoom:
+ async def test_pages_on_after_seq_without_gap_or_repeat(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ for i in range(10):
+ await store.create(session, _message(room.id, f"$evt{i}"), [])
+ await session.commit()
+
+ first_page = await store.list_for_room(
+ session, room.id, after_seq=0, limit=4
+ )
+ second_page = await store.list_for_room(
+ session, room.id, after_seq=first_page[-1].seq, limit=4
+ )
+ third_page = await store.list_for_room(
+ session, room.id, after_seq=second_page[-1].seq, limit=4
+ )
+ past_the_end = await store.list_for_room(
+ session, room.id, after_seq=third_page[-1].seq, limit=4
+ )
+
+ assert [m.transport_event_id for m in first_page] == [
+ f"$evt{i}" for i in range(4)
+ ]
+ assert [m.transport_event_id for m in second_page] == [
+ f"$evt{i}" for i in range(4, 8)
+ ]
+ assert [m.transport_event_id for m in third_page] == ["$evt8", "$evt9"]
+ assert past_the_end == []
+
+ seen = [m.seq for m in first_page + second_page + third_page]
+ assert seen == sorted(seen)
+ assert len(set(seen)) == 10
+
+ async def test_scoped_to_one_room(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room_a = await _make_room(session, "alpha")
+ room_b = await _make_room(session, "beta")
+ for i in range(3):
+ await store.create(session, _message(room_a.id, f"$a{i}"), [])
+ await store.create(session, _message(room_b.id, f"$b{i}"), [])
+ await session.commit()
+
+ in_a = await store.list_for_room(session, room_a.id, after_seq=0, limit=50)
+ in_b = await store.list_for_room(session, room_b.id, after_seq=0, limit=50)
+
+ assert [m.transport_event_id for m in in_a] == ["$a0", "$a1", "$a2"]
+ assert [m.transport_event_id for m in in_b] == ["$b0", "$b1", "$b2"]
+
+ async def test_after_seq_from_another_room_does_not_skip_rows(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """`seq` is global, so a cursor is only meaningful within its own room;
+ rows interleaved from another room must not consume the page."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room_a = await _make_room(session, "alpha")
+ room_b = await _make_room(session, "beta")
+ await store.create(session, _message(room_a.id, "$a0"), [])
+ for i in range(5):
+ await store.create(session, _message(room_b.id, f"$b{i}"), [])
+ await store.create(session, _message(room_a.id, "$a1"), [])
+ await session.commit()
+
+ page = await store.list_for_room(session, room_a.id, after_seq=0, limit=1)
+ following = await store.list_for_room(
+ session, room_a.id, after_seq=page[-1].seq, limit=10
+ )
+
+ assert [m.transport_event_id for m in page] == ["$a0"]
+ assert [m.transport_event_id for m in following] == ["$a1"]
+
+
+class TestForeignKeyBehaviour:
+ async def test_deleting_the_room_cascades_its_messages(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ keeper = await _make_room(session, "beta")
+ await store.create(session, _message(room.id, "$gone"), [])
+ await store.create(session, _message(keeper.id, "$kept"), [])
+ await session.commit()
+
+ await session.execute(delete(Room).where(Room.id == room.id))
+ await session.commit()
+
+ assert await store.get_by_transport_event_id(session, "$gone") is None
+ assert await store.get_by_transport_event_id(session, "$kept") is not None
+
+ async def test_deleting_the_message_cascades_its_attachments(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ message = await store.create(
+ session,
+ _message(room.id, "$files"),
+ [
+ MessageAttachment(uri="mxc://a", filename="a.txt"),
+ MessageAttachment(uri="mxc://b", filename="b.txt"),
+ ],
+ )
+ await session.commit()
+ message_id = message.id
+
+ await session.execute(delete(Message).where(Message.id == message_id))
+ await session.commit()
+
+ assert await store.get_attachments(session, message_id) == []
+
+ async def test_deleting_the_sender_client_nulls_the_reference(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """History outlives the client that wrote it: the row stays, the link
+ goes."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session, "alpha")
+ client = await _make_client(session, "writer")
+ await store.create(
+ session,
+ _message(room.id, "$byclient", sender_client_id=client.id),
+ [],
+ )
+ await session.commit()
+
+ await session.execute(delete(Client).where(Client.id == client.id))
+ await session.commit()
+ session.expire_all()
+
+ found = await store.get_by_transport_event_id(session, "$byclient")
+
+ assert found is not None
+ assert found.sender_client_id is None
+ assert found.sender_matrix_id == "@sender:test"
diff --git a/core/tests/switch_core/db/stores/test_room_membership_write.py b/core/tests/switch_core/db/stores/test_room_membership_write.py
new file mode 100644
index 000000000..669edf94e
--- /dev/null
+++ b/core/tests/switch_core/db/stores/test_room_membership_write.py
@@ -0,0 +1,81 @@
+"""Recording a membership twice is success, not a failed transaction.
+
+Over Matrix an invitation was accepted later, over sync, so `room_service` was
+effectively the only writer of `client_rooms`. On the Postgres transport the
+invitation *is* the join: the client writes the row synchronously, and the
+inviting caller then writes it again in a transaction that also creates the
+room's agents. A plain insert turned that into an IntegrityError, rolled the
+whole thing back, and left an agent a client member of a room but not one of
+its agents — receiving messages while `!list-agents` reported nobody.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import Client, Room
+from switch_core.db.stores.room_store import RoomStore
+
+
+async def _client_and_room(session: AsyncSession) -> tuple[str, str]:
+ client = Client(
+ matrix_user_id=f"@someone-{uuid.uuid4().hex[:8]}:test",
+ display_name="someone",
+ type="agent",
+ password="x",
+ )
+ room = Room(
+ matrix_room_id=f"!{uuid.uuid4().hex[:8]}:test",
+ name="a room",
+ description="",
+ )
+ session.add_all([client, room])
+ await session.flush()
+ return client.id, room.id
+
+
+class TestAddClient:
+ async def test_recording_the_same_membership_twice_succeeds(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ client_id, room_id = await _client_and_room(session)
+ await session.commit()
+
+ async with session_factory() as session:
+ await RoomStore().add_client(session, client_id, room_id)
+ await session.commit()
+
+ async with session_factory() as session:
+ await RoomStore().add_client(session, client_id, room_id)
+ # Whatever else the caller is doing in this transaction has to
+ # survive: the second write is the case that broke /invite-agent.
+ await session.commit()
+
+ async with session_factory() as session:
+ assert await RoomStore().get_client_ids(session, room_id) == [client_id]
+
+ async def test_a_second_write_does_not_poison_the_caller_s_transaction(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The failure that mattered was not the duplicate — it was the work
+ alongside it being rolled back."""
+ async with session_factory() as session:
+ client_id, room_id = await _client_and_room(session)
+ await RoomStore().add_client(session, client_id, room_id)
+ await session.commit()
+
+ async with session_factory() as session:
+ await RoomStore().add_client(session, client_id, room_id)
+ await RoomStore().add_agents(session, room_id, [])
+ room = await RoomStore().get(session, room_id)
+ assert room is not None
+ room.description = "written alongside the duplicate"
+ await session.commit()
+
+ async with session_factory() as session:
+ room = await RoomStore().get(session, room_id)
+ assert room is not None
+ assert room.description == "written alongside the duplicate"
diff --git a/core/tests/switch_core/gateway/test_room_resource_read_authz.py b/core/tests/switch_core/gateway/test_room_resource_read_authz.py
index 3614f7273..fd9dbce9b 100644
--- a/core/tests/switch_core/gateway/test_room_resource_read_authz.py
+++ b/core/tests/switch_core/gateway/test_room_resource_read_authz.py
@@ -19,6 +19,7 @@ from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.document_store import DocumentStore
from switch_core.db.stores.package_store import PackageStore
from switch_core.db.stores.reference_store import ReferenceStore
+from switch_core.db.stores.reference_type_store import ReferenceTypeStore
from switch_core.db.stores.room_link_store import RoomLinkStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.user_store import UserStore
@@ -38,6 +39,7 @@ _AGENT_STORE = AgentStore()
def _svc(session_factory: async_sessionmaker[AsyncSession]) -> ResourceService:
return ResourceService(
reference_store=ReferenceStore(),
+ reference_type_store=ReferenceTypeStore(),
document_store=DocumentStore(),
package_store=PackageStore(),
room_link_store=RoomLinkStore(),
diff --git a/core/tests/switch_core/messages/__init__.py b/core/tests/switch_core/messages/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/core/tests/switch_core/messages/test_backfill.py b/core/tests/switch_core/messages/test_backfill.py
new file mode 100644
index 000000000..9da30a4d8
--- /dev/null
+++ b/core/tests/switch_core/messages/test_backfill.py
@@ -0,0 +1,455 @@
+"""Reconstructed history lands in the right order, below the live log.
+
+The two properties that matter most are the ones a careless implementation
+gets wrong in ways nobody notices for weeks: the numbering must run the same
+way time does, and running the walk twice must not double the room.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.cli.backfill import _ReadOnlyStore
+from switch_core.db.models import Message, Room
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.messages import backfill_room
+from switch_core.transport import (
+ HistoryPage,
+ InboundCustomEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+)
+
+BASE = datetime(2026, 1, 1, 12, 0, tzinfo=UTC)
+
+
+class PagingTransport:
+ """Replays fixed pages of backwards history, newest first."""
+
+ def __init__(self, pages: list[HistoryPage]) -> None:
+ self._pages = pages
+ self.reads = 0
+
+ async def read_history(
+ self, room_id: str, *, start: str | None, limit: int
+ ) -> HistoryPage:
+ page = self._pages[min(self.reads, len(self._pages) - 1)]
+ self.reads += 1
+ return page
+
+
+def _at(seconds: int) -> datetime:
+ return BASE + timedelta(seconds=seconds)
+
+
+def _ms(seconds: int) -> int:
+ return int(_at(seconds).timestamp() * 1000)
+
+
+def _event(event_id: str, at: int, body: str = "hello", **overrides: object): # type: ignore[no-untyped-def]
+ fields: dict[str, object] = {
+ "room_id": "!room:test",
+ "event_id": event_id,
+ "sender": "@a:test",
+ "timestamp": _ms(at),
+ "content": {"body": body, "sender_name": "Alice"},
+ "body": body,
+ "msgtype": "m.text",
+ }
+ fields.update(overrides)
+ return InboundMessage(**fields) # type: ignore[arg-type]
+
+
+async def _make_room(session: AsyncSession) -> Room:
+ room = Room(
+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",
+ name="a room",
+ description="",
+ )
+ session.add(room)
+ await session.commit()
+ return room
+
+
+async def _rows(
+ session_factory: async_sessionmaker[AsyncSession], room_id: str
+) -> list[Message]:
+ async with session_factory() as session:
+ result = await session.execute(
+ select(Message).where(Message.room_id == room_id).order_by(Message.seq)
+ )
+ return list(result.scalars().all())
+
+
+class TestNumbering:
+ async def test_history_is_numbered_below_the_live_log(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A message from before recording must not outrank one from after it.
+
+ Ordering is by `seq`, so a positive number on reconstructed history
+ would put last month at the top of every read.
+ """
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+ live = Message(
+ room_id=room.id,
+ transport_event_id="$live",
+ sender_matrix_id="@a:test",
+ event_type="m.room.message",
+ msgtype="m.text",
+ body="today",
+ content={},
+ sent_at=_at(100),
+ )
+ await store.create(session, live, [])
+ await session.commit()
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$old", 10, "yesterday")], next_token=None)]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ await backfill_room(transport, session_factory, room, store=store)
+
+ rows = await _rows(session_factory, room.id)
+ assert [(r.seq, r.body) for r in rows] == [(-1, "yesterday"), (1, "today")]
+
+ async def test_the_oldest_message_gets_the_lowest_number(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Numbering has to run the same way time does, across pages as well as
+ within them — a walk that numbered per page would interleave."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[_event("$d", 40, "d"), _event("$c", 30, "c")],
+ next_token="t1",
+ ),
+ HistoryPage(
+ events=[_event("$b", 20, "b"), _event("$a", 10, "a")],
+ next_token=None,
+ ),
+ ]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ await backfill_room(transport, session_factory, room, store=store)
+
+ rows = await _rows(session_factory, room.id)
+ assert [r.body for r in rows] == ["a", "b", "c", "d"]
+ assert [r.seq for r in rows] == [-4, -3, -2, -1]
+
+ async def test_the_timestamp_is_when_it_was_sent_not_when_it_was_written(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The read path filters on `sent_at`. Stamping the backfill's own
+ clock would pile a year of history onto tonight."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$a", 10)], next_token=None)]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ await backfill_room(transport, session_factory, room, store=store)
+
+ rows = await _rows(session_factory, room.id)
+ assert rows[0].sent_at == _at(10)
+
+
+class TestCompletionMark:
+ """A room is marked done only by a walk that really wrote it.
+
+ The mark is what stops a re-run re-reading every page of every room. It is
+ also what a dry run must not leave behind: the documented first step is a
+ dry run, and if that marked every room, the real run afterwards would find
+ nothing to do and say so as though the work were finished.
+ """
+
+ async def test_a_completed_walk_marks_the_room(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$a", 10, "a")], next_token=None)]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ await backfill_room(transport, session_factory, room, store=MessageStore())
+
+ async with session_factory() as session:
+ written = await session.get(Room, room.id)
+ assert written is not None
+ assert written.history_backfilled_at is not None
+
+ async def test_a_dry_run_marks_nothing(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Otherwise the dry run disables the real one, silently."""
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$a", 10, "a")], next_token=None)]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ report = await backfill_room(
+ transport, session_factory, room, store=_ReadOnlyStore()
+ )
+
+ assert report.written == 1
+ async with session_factory() as session:
+ untouched = await session.get(Room, room.id)
+ assert untouched is not None
+ assert untouched.history_backfilled_at is None
+ assert await _rows(session_factory, room.id) == []
+
+
+class TestIdempotence:
+ async def test_running_it_twice_writes_nothing_the_second_time(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A long walk that fails halfway should be safe to just run again."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ def _transport() -> PagingTransport:
+ return PagingTransport(
+ [
+ HistoryPage(
+ events=[_event("$b", 20, "b"), _event("$a", 10, "a")],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ first = await backfill_room(
+ _transport(), session_factory, room, store=store
+ )
+ second = await backfill_room(
+ _transport(), session_factory, room, store=store
+ )
+
+ assert (first.written, first.already_present) == (2, 0)
+ assert (second.written, second.already_present) == (0, 2)
+ assert len(await _rows(session_factory, room.id)) == 2
+
+ async def test_a_message_already_recorded_live_is_left_alone(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The walk overlaps the recorded window by design — it starts at the
+ newest message on the bus, not at the oldest row."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+ live = Message(
+ room_id=room.id,
+ transport_event_id="$b",
+ sender_matrix_id="@a:test",
+ event_type="m.room.message",
+ msgtype="m.text",
+ body="b",
+ content={},
+ sent_at=_at(20),
+ )
+ await store.create(session, live, [])
+ await session.commit()
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[_event("$b", 20, "b"), _event("$a", 10, "a")],
+ next_token=None,
+ )
+ ]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ report = await backfill_room(transport, session_factory, room, store=store)
+
+ assert (report.written, report.already_present) == (1, 1)
+ rows = await _rows(session_factory, room.id)
+ assert [(r.seq, r.body) for r in rows] == [(-1, "a"), (1, "b")]
+
+
+class TestWhatBelongsInTheLog:
+ async def test_bus_traffic_the_log_does_not_keep_is_skipped(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The same scoping as the live recorder, or the backfill would put
+ back exactly what scoping the log took out."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _event("$msg", 20),
+ InboundCustomEvent(
+ room_id="!room:test",
+ event_id="$state",
+ sender="@a:test",
+ timestamp=_ms(10),
+ content={"state": "busy"},
+ event_type="com.switch.agent.runtime_state",
+ ),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ report = await backfill_room(transport, session_factory, room, store=store)
+
+ assert report.written == 1
+ assert report.skipped_by_type == {"com.switch.agent.runtime_state": 1}
+
+ async def test_an_arrival_is_reconstructed_with_no_body(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The timeline reads wrong without arrivals, and the sentence stays
+ the reader's to phrase — same as the live path."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ InboundMembership(
+ room_id="!room:test",
+ event_id="$join",
+ sender="@bob:test",
+ timestamp=_ms(10),
+ state_key="@bob:test",
+ membership="join",
+ display_name="Bob",
+ )
+ ],
+ next_token=None,
+ )
+ ]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ await backfill_room(transport, session_factory, room, store=store)
+
+ rows = await _rows(session_factory, room.id)
+ assert rows[0].event_type == "m.room.member"
+ assert rows[0].body is None
+ assert rows[0].sender_name == "Bob"
+
+ async def test_a_departure_is_not_history_worth_keeping(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ InboundMembership(
+ room_id="!room:test",
+ event_id="$leave",
+ sender="@bob:test",
+ timestamp=_ms(10),
+ state_key="@bob:test",
+ membership="leave",
+ )
+ ],
+ next_token=None,
+ )
+ ]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ report = await backfill_room(transport, session_factory, room, store=store)
+
+ assert report.written == 0
+ assert await _rows(session_factory, room.id) == []
+
+ async def test_a_file_comes_back_with_its_attachment_row(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ InboundMedia(
+ room_id="!room:test",
+ event_id="$img",
+ sender="@a:test",
+ timestamp=_ms(10),
+ content={
+ "info": {"mimetype": "image/png", "size": 42},
+ "body": "chart.png",
+ },
+ body="chart.png",
+ msgtype="m.image",
+ uri="mxc://s/abc",
+ )
+ ],
+ next_token=None,
+ )
+ ]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ await backfill_room(transport, session_factory, room, store=store)
+
+ rows = await _rows(session_factory, room.id)
+ async with session_factory() as session:
+ attachments = await store.attachments_for(session, [rows[0].id])
+ [attachment] = attachments[rows[0].id]
+ assert (attachment.uri, attachment.filename) == ("mxc://s/abc", "chart.png")
+ assert (attachment.mimetype, attachment.size) == ("image/png", 42)
+
+
+class TestStopping:
+ async def test_a_cursor_that_does_not_advance_stops_the_walk(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A homeserver that keeps returning the token it was given would
+ otherwise walk forever."""
+ store = MessageStore()
+ async with session_factory() as session:
+ room = await _make_room(session)
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$a", 10)], next_token="stuck")]
+ )
+ async with session_factory() as session:
+ room = await session.get(Room, room.id) # type: ignore[assignment]
+ report = await backfill_room(transport, session_factory, room, store=store)
+
+ assert transport.reads == 2
+ assert report.written == 1
diff --git a/core/tests/switch_core/messages/test_message_recorder.py b/core/tests/switch_core/messages/test_message_recorder.py
new file mode 100644
index 000000000..82027dd5d
--- /dev/null
+++ b/core/tests/switch_core/messages/test_message_recorder.py
@@ -0,0 +1,623 @@
+"""What the recorder writes for a send, and what it does when it cannot.
+
+The recorder reads the content dict the transport reports back rather than
+being told separately what was sent, so these tests feed it the shapes the
+Matrix transport really produces — a plain message, a markdown one, a threaded
+reply, a media event, a custom `com.switch.*` event — and check what lands.
+
+The failure tests matter as much as the success ones. Recording runs after
+delivery and must never turn a delivered message into a raised exception at
+the caller.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import Client, Room
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.db.stores.room_store import RoomStore
+from switch_core.messages import MessageRecorder
+from switch_core.transport import InboundMembership, SendResult
+
+
+async def _make_room(session: AsyncSession) -> tuple[str, str, str]:
+ """Insert the Room and Client a recorded message depends on.
+
+ Returns (room uuid, matrix room id, client id).
+ """
+ suffix = uuid.uuid4().hex[:8]
+ client = Client(
+ matrix_user_id=f"@agent-{suffix}:test",
+ display_name="agent one",
+ type="agent",
+ password="x",
+ )
+ session.add(client)
+ await session.flush()
+ room = Room(
+ matrix_room_id=f"!room-{suffix}:test",
+ name="a room",
+ description="",
+ )
+ session.add(room)
+ await session.flush()
+ return room.id, room.matrix_room_id, client.id
+
+
+def _recorder(session_factory: async_sessionmaker[AsyncSession]) -> MessageRecorder:
+ return MessageRecorder(
+ session_factory=session_factory,
+ room_store=RoomStore(),
+ message_store=MessageStore(),
+ )
+
+
+async def _record(
+ session_factory: async_sessionmaker[AsyncSession],
+ matrix_room_id: str,
+ client_id: str,
+ result: SendResult,
+) -> None:
+ await _recorder(session_factory).record(
+ transport_room_id=matrix_room_id,
+ result=result,
+ sender_matrix_id="@agent:test",
+ sender_client_id=client_id,
+ sender_name="agent one",
+ )
+
+
+class TestRecordsWhatWasSent:
+ async def test_a_plain_message(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _record(
+ session_factory,
+ matrix_room_id,
+ client_id,
+ SendResult(
+ event_id="$evt1",
+ event_type="m.room.message",
+ content={
+ "msgtype": "m.text",
+ "body": "hello",
+ "sender_name": "agent one",
+ },
+ ),
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(session, "$evt1")
+
+ assert message is not None
+ assert message.room_id == room_id
+ assert message.body == "hello"
+ assert message.msgtype == "m.text"
+ assert message.event_type == "m.room.message"
+ assert message.sender_client_id == client_id
+ assert message.sender_matrix_id == "@agent:test"
+ assert message.thread_root_event_id is None
+ # The whole event body is kept, not just the columns beside it.
+ assert message.content["sender_name"] == "agent one"
+
+ async def test_a_markdown_message_keeps_the_rendered_html(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _record(
+ session_factory,
+ matrix_room_id,
+ client_id,
+ SendResult(
+ event_id="$evt2",
+ event_type="m.room.message",
+ content={
+ "msgtype": "m.text",
+ "body": "**bold**",
+ "format": "org.matrix.custom.html",
+ "formatted_body": "<p><strong>bold</strong></p>",
+ },
+ ),
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(session, "$evt2")
+
+ assert message is not None
+ assert message.formatted_body == "<p><strong>bold</strong></p>"
+
+ async def test_a_threaded_reply_records_its_root(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _record(
+ session_factory,
+ matrix_room_id,
+ client_id,
+ SendResult(
+ event_id="$evt3",
+ event_type="m.room.message",
+ content={
+ "msgtype": "m.text",
+ "body": "in thread",
+ "m.relates_to": {
+ "rel_type": "m.thread",
+ "event_id": "$root",
+ },
+ },
+ ),
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(session, "$evt3")
+
+ assert message is not None
+ assert message.thread_root_event_id == "$root"
+
+ async def test_a_non_thread_relation_is_not_read_as_a_thread(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """An edit or a reaction relates to an event without being in a thread."""
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _record(
+ session_factory,
+ matrix_room_id,
+ client_id,
+ SendResult(
+ event_id="$evt4",
+ event_type="m.room.message",
+ content={
+ "msgtype": "m.text",
+ "body": "an edit",
+ "m.relates_to": {
+ "rel_type": "m.replace",
+ "event_id": "$original",
+ },
+ },
+ ),
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(session, "$evt4")
+
+ assert message is not None
+ assert message.thread_root_event_id is None
+
+ async def test_a_media_event_records_its_file(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _record(
+ session_factory,
+ matrix_room_id,
+ client_id,
+ SendResult(
+ event_id="$evt5",
+ event_type="m.room.message",
+ content={
+ "msgtype": "m.image",
+ "body": "a caption",
+ "filename": "chart.png",
+ "url": "mxc://test/abc",
+ "info": {"mimetype": "image/png", "size": 4096},
+ },
+ ),
+ )
+
+ async with session_factory() as session:
+ store = MessageStore()
+ message = await store.get_by_transport_event_id(session, "$evt5")
+ assert message is not None
+ attachments = await store.get_attachments(session, message.id)
+
+ assert len(attachments) == 1
+ assert attachments[0].uri == "mxc://test/abc"
+ # The caption is the body; the real filename is carried separately.
+ assert attachments[0].filename == "chart.png"
+ assert attachments[0].mimetype == "image/png"
+ assert attachments[0].size == 4096
+
+ async def test_an_uncaptioned_file_falls_back_to_the_body_for_its_name(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Without a caption the transport puts the filename in `body` and
+ sends no `filename` field at all."""
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _record(
+ session_factory,
+ matrix_room_id,
+ client_id,
+ SendResult(
+ event_id="$evt6",
+ event_type="m.room.message",
+ content={
+ "msgtype": "m.file",
+ "body": "report.csv",
+ "url": "mxc://test/def",
+ "info": {"mimetype": "text/csv", "size": 12},
+ },
+ ),
+ )
+
+ async with session_factory() as session:
+ store = MessageStore()
+ message = await store.get_by_transport_event_id(session, "$evt6")
+ assert message is not None
+ attachments = await store.get_attachments(session, message.id)
+
+ assert [a.filename for a in attachments] == ["report.csv"]
+
+ async def test_a_custom_event_records_its_whole_content(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A `com.switch.*` event has no body or msgtype — the payload is all
+ there is, so losing it would lose the event."""
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _record(
+ session_factory,
+ matrix_room_id,
+ client_id,
+ SendResult(
+ event_id="$evt7",
+ event_type="com.switch.command",
+ content={"command": "reset", "args": ["--hard"], "request_id": "r1"},
+ ),
+ )
+
+ async with session_factory() as session:
+ store = MessageStore()
+ message = await store.get_by_transport_event_id(session, "$evt7")
+ assert message is not None
+ attachments = await store.get_attachments(session, message.id)
+
+ assert message.event_type == "com.switch.command"
+ assert message.body is None
+ assert message.msgtype is None
+ assert message.content == {
+ "command": "reset",
+ "args": ["--hard"],
+ "request_id": "r1",
+ }
+ assert attachments == []
+
+ async def test_bus_traffic_is_not_recorded_at_all(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The log is the conversation. A runtime-state ping is not part of it,
+ and it is the highest-volume thing on the bus."""
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _record(
+ session_factory,
+ matrix_room_id,
+ client_id,
+ SendResult(
+ event_id="$evt8",
+ event_type="com.switch.agent.runtime_state",
+ content={"state": "busy"},
+ ),
+ )
+
+ async with session_factory() as session:
+ found = await MessageStore().get_by_transport_event_id(session, "$evt8")
+
+ assert found is None
+
+
+class TestFailingToRecordNeverReachesTheCaller:
+ async def test_an_unknown_room_is_warned_about_not_raised(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ caplog: pytest.LogCaptureFixture,
+ ) -> None:
+ """Not every room a client sends to is a Switch room."""
+ with caplog.at_level(logging.WARNING):
+ await _record(
+ session_factory,
+ "!nobody-knows-this:test",
+ None, # type: ignore[arg-type]
+ SendResult(
+ event_id="$evt8",
+ event_type="m.room.message",
+ content={"body": "hi"},
+ ),
+ )
+
+ assert "not a Switch room" in caplog.text
+
+ async with session_factory() as session:
+ assert (
+ await MessageStore().get_by_transport_event_id(session, "$evt8") is None
+ )
+
+ async def test_a_database_failure_is_logged_at_error_and_swallowed(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ caplog: pytest.LogCaptureFixture,
+ ) -> None:
+ """The message was delivered. Raising here would tell the caller a
+ successful send failed, which is worse than a missing row."""
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ recorder = _recorder(session_factory)
+ result = SendResult(
+ event_id="$evt9",
+ event_type="m.room.message",
+ content={"msgtype": "m.text", "body": "once"},
+ )
+ await recorder.record(
+ transport_room_id=matrix_room_id,
+ result=result,
+ sender_matrix_id="@agent:test",
+ sender_client_id=client_id,
+ sender_name="agent one",
+ )
+
+ # The same event id a second time violates the unique constraint, which
+ # is a stand-in for any database failure after a successful send.
+ with caplog.at_level(logging.ERROR):
+ await recorder.record(
+ transport_room_id=matrix_room_id,
+ result=result,
+ sender_matrix_id="@agent:test",
+ sender_client_id=client_id,
+ sender_name="agent one",
+ )
+
+ assert "failed to record" in caplog.text
+ assert "$evt9" in caplog.text
+
+
+class TestRoomResolution:
+ async def test_the_room_lookup_is_cached_across_sends(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A send is on the hot path, so the room id is resolved once."""
+ async with session_factory() as session:
+ room_id, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ lookups = 0
+ real_lookup = RoomStore.get_by_matrix_room_id
+
+ async def counting_lookup(
+ self: RoomStore, session: AsyncSession, matrix_room_id: str
+ ) -> Room | None:
+ nonlocal lookups
+ lookups += 1
+ return await real_lookup(self, session, matrix_room_id)
+
+ room_store = RoomStore()
+ room_store.get_by_matrix_room_id = counting_lookup.__get__(room_store) # type: ignore[method-assign]
+ recorder = MessageRecorder(
+ session_factory=session_factory,
+ room_store=room_store,
+ message_store=MessageStore(),
+ )
+
+ for n in range(3):
+ await recorder.record(
+ transport_room_id=matrix_room_id,
+ result=SendResult(
+ event_id=f"$cached{n}",
+ event_type="m.room.message",
+ content={"body": "x"},
+ ),
+ sender_matrix_id="@agent:test",
+ sender_client_id=client_id,
+ sender_name="agent one",
+ )
+
+ assert lookups == 1
+
+ async with session_factory() as session:
+ for n in range(3):
+ message = await MessageStore().get_by_transport_event_id(
+ session, f"$cached{n}"
+ )
+ assert message is not None
+ assert message.room_id == room_id
+
+
+class TestRecordsArrivals:
+ """A join is not a send, so it comes in by its own door.
+
+ It is recorded by the client that arrived, about itself. Exactly one Switch
+ client owns each participant, so that gives one row per arrival for the
+ same reason recording sends does.
+ """
+
+ async def test_an_arrival_is_recorded(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _recorder(session_factory).record_join(
+ transport_room_id=matrix_room_id,
+ event=InboundMembership(
+ room_id=matrix_room_id,
+ event_id="$join1",
+ sender="@agent:test",
+ timestamp=1000,
+ content={"membership": "join", "displayname": "agent one"},
+ state_key="@agent:test",
+ membership="join",
+ prev_membership="invite",
+ display_name="agent one",
+ ),
+ client_id=client_id,
+ member_name="agent one",
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(session, "$join1")
+ assert message is not None
+ assert message.room_id == room_id
+ assert message.event_type == "m.room.member"
+ assert message.sender_matrix_id == "@agent:test"
+ assert message.sender_name == "agent one"
+ assert message.content["membership"] == "join"
+
+ async def test_the_arrival_is_named_the_way_the_member_speaks(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The membership event's display name comes from the profile, which is
+ set from whatever the source platform calls the member. Recording it
+ would make one participant read two ways in the same history."""
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _recorder(session_factory).record_join(
+ transport_room_id=matrix_room_id,
+ event=InboundMembership(
+ room_id=matrix_room_id,
+ event_id="$join5",
+ sender="@agent:test",
+ timestamp=1000,
+ state_key="@agent:test",
+ membership="join",
+ display_name="agent one on the platform",
+ ),
+ client_id=client_id,
+ member_name="agent one",
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(session, "$join5")
+ assert message is not None
+ assert message.sender_name == "agent one"
+
+ async def test_the_row_carries_no_rendered_sentence(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """How an arrival reads is the reader's to phrase. Writing "x joined
+ the room" into the log would freeze today's wording into every row."""
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ await _recorder(session_factory).record_join(
+ transport_room_id=matrix_room_id,
+ event=InboundMembership(
+ room_id=matrix_room_id,
+ event_id="$join2",
+ sender="@agent:test",
+ timestamp=1000,
+ state_key="@agent:test",
+ membership="join",
+ display_name="agent one",
+ ),
+ client_id=client_id,
+ member_name="agent one",
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(session, "$join2")
+ assert message is not None
+ assert message.body is None
+ assert message.msgtype is None
+
+ async def test_seeing_the_same_join_twice_records_it_once(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A redelivered sync is not a second arrival."""
+ async with session_factory() as session:
+ room_id, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ event = InboundMembership(
+ room_id=matrix_room_id,
+ event_id="$join3",
+ sender="@agent:test",
+ timestamp=1000,
+ state_key="@agent:test",
+ membership="join",
+ display_name="agent one",
+ )
+ recorder = _recorder(session_factory)
+ await recorder.record_join(
+ transport_room_id=matrix_room_id,
+ event=event,
+ client_id=client_id,
+ member_name="agent one",
+ )
+ await recorder.record_join(
+ transport_room_id=matrix_room_id,
+ event=event,
+ client_id=client_id,
+ member_name="agent one",
+ )
+
+ async with session_factory() as session:
+ rows = await MessageStore().list_for_room(
+ session, room_id, after_seq=0, limit=10
+ )
+ assert [row.transport_event_id for row in rows] == ["$join3"]
+
+ async def test_a_failure_to_record_does_not_escape(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ caplog: pytest.LogCaptureFixture,
+ ) -> None:
+ """Nothing about being in a room depends on the row having landed."""
+ async with session_factory() as session:
+ _, matrix_room_id, client_id = await _make_room(session)
+ await session.commit()
+
+ recorder = _recorder(session_factory)
+
+ async def boom(*args: object, **kwargs: object) -> None:
+ raise RuntimeError("database is unhappy")
+
+ recorder._message_store.create = boom # type: ignore[method-assign]
+
+ with caplog.at_level(logging.ERROR):
+ await recorder.record_join(
+ transport_room_id=matrix_room_id,
+ event=InboundMembership(
+ room_id=matrix_room_id,
+ event_id="$join4",
+ sender="@agent:test",
+ timestamp=1000,
+ state_key="@agent:test",
+ membership="join",
+ ),
+ client_id=client_id,
+ member_name="agent one",
+ )
+
+ assert "failed to record the arrival" in caplog.text
diff --git a/core/tests/switch_core/messages/test_notify.py b/core/tests/switch_core/messages/test_notify.py
new file mode 100644
index 000000000..4f3fde479
--- /dev/null
+++ b/core/tests/switch_core/messages/test_notify.py
@@ -0,0 +1,222 @@
+"""New rows announce themselves, and the listener wakes whoever asked.
+
+These run against real PostgreSQL because the thing under test is a trigger and
+a `LISTEN`. Neither has a meaningful stand-in: a fake would prove the fan-out
+works and say nothing about whether the database ever speaks.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import TYPE_CHECKING
+
+import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.pool import NullPool
+
+from switch_core.db.models import Message, Room
+from switch_core.messages.notify import Announcement, MessageListener
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator
+
+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+# Long enough that a slow container does not fail the test, short enough that a
+# genuine hang does not hold the suite up.
+DELIVERY_TIMEOUT = 10.0
+
+
+class Woken:
+ """Records which rooms were woken, and lets a test wait for one."""
+
+ def __init__(self) -> None:
+ self.rooms: list[str] = []
+ self._anything = asyncio.Event()
+
+ async def __call__(self, room_id: str) -> None:
+ self.rooms.append(room_id)
+ self._anything.set()
+
+ async def wait(self) -> None:
+ await asyncio.wait_for(self._anything.wait(), DELIVERY_TIMEOUT)
+ self._anything.clear()
+
+
+async def listener(postgres_url: str) -> AsyncIterator[MessageListener]:
+ listener = MessageListener(
+ lambda: create_async_engine(postgres_url, poolclass=NullPool)
+ )
+ await listener.start()
+ try:
+ await asyncio.wait_for(listener.connected.wait(), DELIVERY_TIMEOUT)
+ yield listener
+ finally:
+ await listener.stop()
+
+
+async def _make_room(session: AsyncSession) -> str:
+ room = Room(
+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",
+ name="a room",
+ description="",
+ )
+ session.add(room)
+ await session.flush()
+ return room.id
+
+
+async def _write(session: AsyncSession, room_id: str, seq: int) -> None:
+ session.add(
+ Message(
+ seq=seq,
+ room_id=room_id,
+ transport_event_id=f"$e{uuid.uuid4().hex[:8]}",
+ sender_matrix_id="@a:test",
+ event_type="m.room.message",
+ msgtype="m.text",
+ body="hello",
+ content={"body": "hello"},
+ )
+ )
+ await session.commit()
+
+
+class TestParsingAnnouncements:
+ def test_a_payload_becomes_an_announcement(self) -> None:
+ announcement = Announcement.parse('{"room_id": "r1", "seq": 4, "id": "m1"}')
+ assert announcement == Announcement(room_id="r1", seq=4, message_id="m1")
+
+ @pytest.mark.parametrize(
+ "payload", ["not json", "{}", '{"room_id": "r1", "seq": "no"}', "[]"]
+ )
+ def test_an_unreadable_payload_is_dropped_not_raised(self, payload: str) -> None:
+ """This runs inside the connection's read loop. Raising there would
+ take delivery down for every room over one bad message."""
+ assert Announcement.parse(payload) is None
+
+
+class TestDelivery:
+ async def test_writing_a_message_wakes_a_subscriber(
+ self,
+ listener: MessageListener,
+ session_factory: async_sessionmaker[AsyncSession],
+ ) -> None:
+ async with session_factory() as session:
+ room_id = await _make_room(session)
+ await session.commit()
+
+ woken = Woken()
+ listener.subscribe(room_id, woken)
+ await woken.wait() # subscribing wakes once by design
+ woken.rooms.clear()
+
+ async with session_factory() as session:
+ await _write(session, room_id, 1)
+
+ await woken.wait()
+ assert woken.rooms == [room_id]
+
+ async def test_a_room_nobody_subscribed_to_wakes_nobody(
+ self,
+ listener: MessageListener,
+ session_factory: async_sessionmaker[AsyncSession],
+ ) -> None:
+ async with session_factory() as session:
+ mine = await _make_room(session)
+ theirs = await _make_room(session)
+ await session.commit()
+
+ woken = Woken()
+ listener.subscribe(mine, woken)
+ await woken.wait()
+ woken.rooms.clear()
+
+ async with session_factory() as session:
+ await _write(session, theirs, 1)
+ await _write(session, mine, 1)
+
+ await woken.wait()
+ assert woken.rooms == [mine]
+
+ async def test_a_burst_coalesces_into_one_wake_up(
+ self,
+ listener: MessageListener,
+ session_factory: async_sessionmaker[AsyncSession],
+ ) -> None:
+ """The wake-up says a room moved, not what was said, so several rows
+ arriving together are one thing to react to. The subscriber reads from
+ its own cursor and sees all of them either way."""
+ async with session_factory() as session:
+ room_id = await _make_room(session)
+ await session.commit()
+
+ blocked = asyncio.Event()
+ released = asyncio.Event()
+ calls = 0
+
+ async def slow(_room_id: str) -> None:
+ nonlocal calls
+ calls += 1
+ blocked.set()
+ await released.wait()
+
+ listener.subscribe(room_id, slow)
+ await asyncio.wait_for(blocked.wait(), DELIVERY_TIMEOUT)
+
+ async with session_factory() as session:
+ for seq in range(1, 6):
+ await _write(session, room_id, seq)
+
+ # Let the announcements land while the subscriber is still held.
+ await asyncio.sleep(0.5)
+ released.set()
+ await asyncio.sleep(0.5)
+
+ assert calls == 2, "the subscribe wake-up, then one for the whole burst"
+
+ async def test_reconstructed_history_is_not_announced(
+ self,
+ listener: MessageListener,
+ session_factory: async_sessionmaker[AsyncSession],
+ ) -> None:
+ """A backfill writes thousands of rows numbered below zero. Nobody is
+ waiting for them — every cursor is above those positions by
+ construction — so waking the room to read nothing is pure noise."""
+ async with session_factory() as session:
+ room_id = await _make_room(session)
+ await session.commit()
+
+ woken = Woken()
+ listener.subscribe(room_id, woken)
+ await woken.wait()
+ woken.rooms.clear()
+
+ async with session_factory() as session:
+ await _write(session, room_id, -1)
+
+ await asyncio.sleep(0.5)
+ assert woken.rooms == []
+
+ async def test_unsubscribing_stops_the_wake_ups(
+ self,
+ listener: MessageListener,
+ session_factory: async_sessionmaker[AsyncSession],
+ ) -> None:
+ async with session_factory() as session:
+ room_id = await _make_room(session)
+ await session.commit()
+
+ woken = Woken()
+ listener.subscribe(room_id, woken)
+ await woken.wait()
+ listener.unsubscribe(room_id, woken)
+ woken.rooms.clear()
+
+ async with session_factory() as session:
+ await _write(session, room_id, 1)
+
+ await asyncio.sleep(0.5)
+ assert woken.rooms == []
diff --git a/core/tests/switch_core/messages/test_reconcile.py b/core/tests/switch_core/messages/test_reconcile.py
new file mode 100644
index 000000000..a93a8c46b
--- /dev/null
+++ b/core/tests/switch_core/messages/test_reconcile.py
@@ -0,0 +1,792 @@
+"""Reconciliation reports the differences it is supposed to, and no others.
+
+The whole value of this check is that its verdict can be trusted. So the tests
+that matter most are the ones proving it does not cry drift over things that
+are legitimately different — history predating the recorder, membership
+changes that were never arrivals, arrivals predating the path that records
+them — and the one proving it does not report a room it could not fully read
+as clean.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+from itertools import count
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import Message, Room
+from switch_core.messages import reconcile_room
+from switch_core.transport import (
+ HistoryPage,
+ InboundCustomEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+)
+
+
+class PagingTransport:
+ """Replays fixed pages of backwards history, newest first."""
+
+ def __init__(self, pages: list[HistoryPage]) -> None:
+ self._pages = pages
+ self.reads = 0
+
+ async def read_history(
+ self, room_id: str, *, start: str | None, limit: int
+ ) -> HistoryPage:
+ page = self._pages[self.reads]
+ self.reads += 1
+ return page
+
+
+def _ms(moment: datetime) -> int:
+ return int(moment.timestamp() * 1000)
+
+
+async def _make_room(session: AsyncSession) -> Room:
+ room = Room(
+ matrix_room_id=f"!room-{uuid.uuid4().hex[:8]}:test",
+ name="a room",
+ description="",
+ )
+ session.add(room)
+ await session.flush()
+ return room
+
+
+_seq = count(1)
+
+
+def _row(
+ room_id: str, event_id: str, sent_at: datetime, **overrides: object
+) -> Message:
+ """`seq` is assigned by MessageStore.create; these rows bypass it, so the
+ helper numbers them. Reconciliation matches on event id and never reads
+ `seq`, so only distinctness matters here."""
+ fields: dict[str, object] = {
+ "seq": next(_seq),
+ "room_id": room_id,
+ "transport_event_id": event_id,
+ "sender_matrix_id": "@agent:test",
+ "sender_name": "agent one",
+ "event_type": "m.room.message",
+ "msgtype": "m.text",
+ "body": "hello",
+ "content": {"msgtype": "m.text", "body": "hello"},
+ "sent_at": sent_at,
+ }
+ fields.update(overrides)
+ return Message(**fields)
+
+
+def _join_row(room_id: str, event_id: str, sent_at: datetime) -> Message:
+ return _row(
+ room_id,
+ event_id,
+ sent_at,
+ event_type="m.room.member",
+ msgtype=None,
+ body=None,
+ content={"membership": "join"},
+ )
+
+
+def _join_event(event_id: str, at: datetime, **overrides: object) -> InboundMembership:
+ fields: dict[str, object] = {
+ "room_id": "!room:test",
+ "event_id": event_id,
+ "sender": "@agent:test",
+ "timestamp": _ms(at),
+ "content": {"membership": "join"},
+ "state_key": "@agent:test",
+ "membership": "join",
+ "prev_membership": "invite",
+ }
+ fields.update(overrides)
+ return InboundMembership(**fields) # type: ignore[arg-type]
+
+
+def _event(event_id: str, at: datetime, **overrides: object) -> InboundMessage:
+ fields: dict[str, object] = {
+ "room_id": "!room:test",
+ "event_id": event_id,
+ "sender": "@agent:test",
+ "timestamp": _ms(at),
+ "content": {},
+ "body": "hello",
+ "msgtype": "m.text",
+ }
+ fields.update(overrides)
+ return InboundMessage(**fields) # type: ignore[arg-type]
+
+
+class TestAgreement:
+ async def test_a_room_whose_records_match_is_clean(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ session.add(_row(room.id, "$b", now + timedelta(seconds=1)))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _event("$b", now + timedelta(seconds=1)),
+ _event("$a", now),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.compared == 2
+ assert report.agreed == 2
+
+ async def test_history_older_than_the_recorder_is_not_reported_missing(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The room existed before recording started. Reporting its whole
+ back-catalogue as drift would bury the row that really went astray."""
+ now = datetime.now(UTC)
+ recording_began = now - timedelta(minutes=5)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$new", recording_began))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _event("$new", recording_began),
+ _event("$ancient", now - timedelta(days=30)),
+ _event("$older-still", now - timedelta(days=60)),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.compared == 1
+ assert report.missing_rows == []
+
+ async def test_events_that_were_never_sends_are_counted_not_flagged(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ InboundMembership(
+ room_id="!room:test",
+ event_id="$join",
+ sender="@someone:test",
+ timestamp=_ms(now + timedelta(seconds=1)),
+ state_key="@someone:test",
+ membership="join",
+ ),
+ _event("$a", now),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.ignored_by_type == {
+ "m.room.member (before arrivals were recorded)": 1
+ }
+
+ async def test_a_room_with_nothing_recorded_reports_that_plainly(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Not the same as agreeing, and not the same as total drift."""
+ async with session_factory() as session:
+ room = await _make_room(session)
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport([])
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.compared_nothing
+ assert transport.reads == 0
+ assert "nothing to compare" in report.summary()
+
+
+class TestTheWindowBoundary:
+ """The oldest recorded message is the one most likely to be misjudged.
+
+ Its row is written after its send is accepted, so the row's `sent_at` is
+ always a little later than the event's own timestamp. A window that began
+ at the row would exclude the event that produced it, and every room would
+ report its first message as drift for as long as it existed.
+ """
+
+ async def test_the_first_recorded_message_is_not_reported_as_drift(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ sent = datetime.now(UTC)
+ recorded_at = sent + timedelta(milliseconds=40)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$first", recorded_at))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$first", sent)], next_token=None)]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.agreed == 1
+ assert report.anchored
+
+ async def test_history_before_the_anchor_is_still_left_alone(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Admitting the anchor from before the window must not admit its
+ neighbours: the walk stops at it, it does not step over it."""
+ sent = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$first", sent + timedelta(milliseconds=40)))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _event("$first", sent),
+ _event("$older", sent - timedelta(seconds=1)),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.missing_rows == []
+
+ async def test_an_anchor_the_bus_has_lost_is_declared_not_hidden(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$gone", now))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$other", now)], next_token=None)]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert not report.anchored
+ assert "WINDOW UNANCHORED" in report.summary()
+
+
+class TestArrivalsAndRowsWithNothingToCompareAgainst:
+ """Arrivals are compared from the point the log holds one; the categories
+ the bus walk still discards have no counterpart by construction, and
+ calling those "recorded but never sent" would report the same rows as
+ drift on every run."""
+
+ async def test_an_arrival_the_bus_agrees_with_is_checked_not_skipped(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Recording arrivals is the newest write path there is, so leaving it
+ out of the check made the least proven part the unchecked part."""
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ session.add(_join_row(room.id, "$join", now + timedelta(seconds=2)))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _join_event("$join", now + timedelta(seconds=1)),
+ _event("$a", now),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.compared == 2
+ assert report.agreed == 2
+ assert report.unverifiable_by_type == {}
+
+ async def test_an_arrival_the_log_missed_is_drift(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ session.add(_join_row(room.id, "$join", now + timedelta(seconds=2)))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _join_event("$later", now + timedelta(seconds=3)),
+ _join_event("$join", now + timedelta(seconds=1)),
+ _event("$a", now),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.missing_rows == ["$later"]
+
+ async def test_an_arrival_older_than_the_log_is_counted_not_reported(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Every room was joined long before arrivals were recorded, so a join
+ from before the log's first one cannot have a row."""
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ session.add(_join_row(room.id, "$join", now + timedelta(seconds=3)))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _join_event("$join", now + timedelta(seconds=2)),
+ _join_event("$ancient", now + timedelta(seconds=1)),
+ _event("$a", now),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.ignored_by_type == {
+ "m.room.member (before arrivals were recorded)": 1
+ }
+
+ async def test_a_leave_is_never_compared(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ session.add(_join_row(room.id, "$join", now + timedelta(seconds=2)))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _join_event(
+ "$leave",
+ now + timedelta(seconds=3),
+ membership="leave",
+ prev_membership="join",
+ ),
+ _join_event("$join", now + timedelta(seconds=1)),
+ _event("$a", now),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.ignored_by_type == {"m.room.member": 1}
+
+ async def test_a_row_written_before_its_type_was_denied_is_not_drift(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """These exist on real deployments: the recorder kept every type before
+ the log was scoped, and those rows outlive the change."""
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ session.add(
+ _row(
+ room.id,
+ "$legacy",
+ now + timedelta(seconds=1),
+ event_type="com.switch.agent.runtime_state",
+ msgtype=None,
+ body=None,
+ content={"state": "busy"},
+ )
+ )
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$a", now)], next_token=None)]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.unverifiable_by_type == {"com.switch.agent.runtime_state": 1}
+
+
+class TestDrift:
+ async def test_a_delivered_message_with_no_row_is_reported(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The failure mode recording was designed to tolerate: the send
+ succeeded and the write after it did not."""
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ _event("$lost", now + timedelta(seconds=1)),
+ _event("$a", now),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert not report.clean
+ assert report.missing_rows == ["$lost"]
+ assert "DRIFT" in report.summary()
+
+ async def test_a_row_the_bus_does_not_have_is_reported(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now))
+ session.add(_row(room.id, "$phantom", now))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [HistoryPage(events=[_event("$a", now)], next_token=None)]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.unsent_rows == ["$phantom"]
+
+ async def test_a_field_that_disagrees_is_named(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$a", now, body="what was recorded"))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[_event("$a", now, body="what the bus holds")],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert [m.field_name for m in report.mismatches] == ["body"]
+ assert "what the bus holds" in report.mismatches[0].describe()
+ assert report.agreed == 0
+
+ async def test_a_custom_event_is_compared_on_its_type(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(
+ _row(
+ room.id,
+ "$cmd",
+ now,
+ event_type="com.switch.command",
+ msgtype=None,
+ body=None,
+ content={"command": "reset"},
+ )
+ )
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ InboundCustomEvent(
+ room_id="!room:test",
+ event_id="$cmd",
+ sender="@agent:test",
+ timestamp=_ms(now),
+ content={"command": "reset"},
+ event_type="com.switch.command",
+ )
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.agreed == 1
+
+ async def test_a_media_event_is_compared_on_its_uri(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(
+ _row(
+ room.id,
+ "$img",
+ now,
+ msgtype="m.image",
+ body="chart.png",
+ content={
+ "msgtype": "m.image",
+ "body": "chart.png",
+ "url": "mxc://a",
+ },
+ )
+ )
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ InboundMedia(
+ room_id="!room:test",
+ event_id="$img",
+ sender="@agent:test",
+ timestamp=_ms(now),
+ content={},
+ body="chart.png",
+ msgtype="m.image",
+ uri="mxc://somewhere-else",
+ )
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert [m.field_name for m in report.mismatches] == ["uri"]
+
+ async def test_an_event_the_recorder_does_not_keep_is_counted_not_reported(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Bus traffic is absent by design. Reporting it as a missing row would
+ drown the one row that really went astray."""
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$msg", now))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(
+ events=[
+ InboundCustomEvent(
+ room_id="!room:test",
+ event_id="$state",
+ sender="@agent:test",
+ timestamp=_ms(now + timedelta(seconds=1)),
+ content={"state": "busy"},
+ event_type="com.switch.agent.runtime_state",
+ ),
+ _event("$msg", now),
+ ],
+ next_token=None,
+ )
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert report.clean
+ assert report.compared == 1
+ assert report.ignored_by_type == {"com.switch.agent.runtime_state": 1}
+
+
+class TestPaging:
+ async def test_it_keeps_paging_until_the_window_is_covered(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The read path gives up after a page budget. This must not: an event
+ it never looked at would otherwise be reported as agreeing."""
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ # Oldest first, so `seq` runs the same way the recorder assigns it:
+ # the anchor is the room's first message, not its last.
+ for n in (2, 1, 0):
+ session.add(_row(room.id, f"$p{n}", now - timedelta(minutes=n)))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(events=[_event("$p0", now)], next_token="t1"),
+ HistoryPage(
+ events=[_event("$p1", now - timedelta(minutes=1))],
+ next_token="t2",
+ ),
+ HistoryPage(
+ events=[_event("$p2", now - timedelta(minutes=2))],
+ next_token=None,
+ ),
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert transport.reads == 3
+ assert report.compared == 3
+ assert report.clean
+
+ async def test_it_stops_at_a_token_that_does_not_advance(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A server that returns the cursor it was given would otherwise loop
+ forever.
+
+ The anchor is deliberately absent from the bus, since a walk that finds
+ it stops there and never reaches a second page.
+ """
+ now = datetime.now(UTC)
+ async with session_factory() as session:
+ room = await _make_room(session)
+ session.add(_row(room.id, "$vanished", now))
+ await session.commit()
+ room_id = room.id
+
+ transport = PagingTransport(
+ [
+ HistoryPage(events=[], next_token="stuck"),
+ HistoryPage(events=[], next_token="stuck"),
+ ]
+ )
+
+ async with session_factory() as session:
+ room = await session.get(Room, room_id) # type: ignore[assignment]
+ report = await reconcile_room(transport, session, room) # type: ignore[arg-type]
+
+ assert transport.reads == 2
+ assert not report.anchored
diff --git a/core/tests/switch_core/messages/test_recorded_types.py b/core/tests/switch_core/messages/test_recorded_types.py
new file mode 100644
index 000000000..a4de15364
--- /dev/null
+++ b/core/tests/switch_core/messages/test_recorded_types.py
@@ -0,0 +1,75 @@
+"""The classification has to keep up with the dispatch table.
+
+A custom event type added to `ClientBase._EVENT_DISPATCH` without a decision
+here is recorded by default, which is the safe direction but not a decision.
+These tests make the omission visible instead of letting it ride.
+"""
+
+from switch_core.clients.client_base import ClientBase
+from switch_core.messages.recorded_types import (
+ EPHEMERAL,
+ NOT_RECORDED,
+ PERSISTED_ELSEWHERE,
+ RETIRED,
+ TELEMETRY,
+ should_record,
+)
+
+# The one custom type that is part of the conversation: a person typing
+# `!invite-agent` into a room.
+RECORDED_CUSTOM_TYPES = frozenset({"com.switch.command"})
+
+
+def test_every_dispatched_type_is_classified():
+ dispatched = set(ClientBase._EVENT_DISPATCH)
+ unclassified = dispatched - NOT_RECORDED - RECORDED_CUSTOM_TYPES
+ assert not unclassified, (
+ "These custom event types are neither recorded nor denied. Decide "
+ "which they are in switch_core/messages/recorded_types.py: "
+ f"{sorted(unclassified)}"
+ )
+
+
+def test_classification_names_no_type_that_is_never_dispatched():
+ dispatched = set(ClientBase._EVENT_DISPATCH)
+ stale = (NOT_RECORDED | RECORDED_CUSTOM_TYPES) - dispatched - RETIRED
+ assert not stale, f"Classified but no longer dispatched: {sorted(stale)}"
+
+
+def test_retired_types_are_the_ones_nothing_dispatches():
+ """The set exists for types the code no longer has. A name that is back in
+ the dispatch table is a live type and belongs in a live bucket."""
+ revived = RETIRED & set(ClientBase._EVENT_DISPATCH)
+ assert not revived, f"Retired but dispatched again: {sorted(revived)}"
+
+
+def test_a_retired_type_is_still_classified():
+ """History outlives the code that wrote it: an event of a deleted type is
+ still on the bus, and a walk over that history has to know what it was."""
+ assert not should_record("com.switch.mediation.tool_result")
+
+
+def test_the_buckets_do_not_overlap():
+ buckets = [EPHEMERAL, PERSISTED_ELSEWHERE, TELEMETRY, RETIRED]
+ total = sum(len(bucket) for bucket in buckets)
+ assert total == len(NOT_RECORDED)
+
+
+def test_conversation_is_recorded():
+ assert should_record("m.room.message")
+ assert should_record("com.switch.command")
+
+
+def test_bus_traffic_is_not_recorded():
+ assert not should_record("com.switch.agent.runtime_state")
+ assert not should_record("com.switch.task.delegate")
+ assert not should_record("com.switch.report.llm_call")
+
+
+def test_the_unimplemented_observe_prefix_is_not_recorded():
+ assert not should_record("com.switch.observe.anything")
+
+
+def test_an_unknown_type_is_recorded_rather_than_dropped():
+ """The denylist fails towards keeping too much, never towards silence."""
+ assert should_record("com.switch.something.nobody.has.written.yet")
diff --git a/core/tests/switch_core/provisioning/__init__.py b/core/tests/switch_core/provisioning/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/core/tests/switch_core/provisioning/test_postgres_provisioning.py b/core/tests/switch_core/provisioning/test_postgres_provisioning.py
new file mode 100644
index 000000000..99eb40ff6
--- /dev/null
+++ b/core/tests/switch_core/provisioning/test_postgres_provisioning.py
@@ -0,0 +1,261 @@
+"""Provisioning against the database, where every operation is a row.
+
+Against a real PostgreSQL, because what is being tested is what the tables end
+up holding — a membership, an arrival, and the absence of either.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import Client, ClientRoom, Room
+from switch_core.db.stores.client_store import ClientStore
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.db.stores.room_store import RoomStore
+from switch_core.provisioning.postgres import (
+ MEMBERSHIP_EVENT_TYPE,
+ PostgresProvisioning,
+ ProvisioningError,
+ new_room_id,
+)
+from switch_core.transport.invites import InviteBus
+
+
+async def _client(session: AsyncSession, name: str = "someone") -> Client:
+ client = Client(
+ matrix_user_id=f"@{name}-{uuid.uuid4().hex[:8]}:test",
+ display_name=name,
+ type="agent",
+ password=str(uuid.uuid4()),
+ )
+ session.add(client)
+ await session.flush()
+ return client
+
+
+async def _room(session: AsyncSession) -> Room:
+ room = Room(matrix_room_id=new_room_id(), name="a room", description="")
+ session.add(room)
+ await session.flush()
+ return room
+
+
+def _provisioning(
+ session_factory: async_sessionmaker[AsyncSession],
+ invites: InviteBus | None = None,
+) -> PostgresProvisioning:
+ return PostgresProvisioning(
+ session_factory=session_factory,
+ room_store=RoomStore(),
+ client_store=ClientStore(),
+ message_store=MessageStore(),
+ invites=invites or InviteBus(),
+ )
+
+
+class TestAccounts:
+ async def test_registering_writes_nothing(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The caller's `clients` row is the account; there is no second
+ system to create one in."""
+ await _provisioning(session_factory).register_user("@a:test", "secret")
+
+ async with session_factory() as session:
+ assert await ClientStore().get_by_matrix_user_id(session, "@a:test") is None
+
+ async def test_a_password_is_checked_against_the_client_row(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ client = await _client(session)
+ await session.commit()
+ user_id, password = client.matrix_user_id, client.password
+
+ provisioning = _provisioning(session_factory)
+ assert await provisioning.verify_login(user_id, password) is True
+ assert await provisioning.verify_login(user_id, "wrong") is False
+ assert await provisioning.verify_login("@nobody:test", password) is False
+
+
+class TestRooms:
+ async def test_creating_a_room_mints_an_id_and_writes_no_row(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The room is the caller's to create. A second record of it here
+ would be a second thing to keep in step."""
+ provisioning = _provisioning(session_factory)
+
+ first = await provisioning.create_room("a", "b")
+ second = await provisioning.create_room("a", "b")
+
+ assert first != second
+ async with session_factory() as session:
+ assert await RoomStore().get_by_matrix_room_id(session, first) is None
+
+
+class TestMembership:
+ async def test_a_member_who_is_not_running_is_written_in_directly(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session)
+ client = await _client(session, "nova")
+ await session.commit()
+ room_id, transport_room_id = room.id, room.matrix_room_id
+ client_id, user_id = client.id, client.matrix_user_id
+
+ await _provisioning(session_factory).invite_to_room(transport_room_id, user_id)
+
+ async with session_factory() as session:
+ membership = await session.get(
+ ClientRoom, {"client_id": client_id, "room_id": room_id}
+ )
+ rows = await MessageStore().list_for_room(
+ session, room_id, after_seq=0, limit=10
+ )
+
+ assert membership is not None
+ # The arrival explains the membership, and carries no rendered
+ # sentence: how it reads is the reader's to phrase.
+ assert [row.event_type for row in rows] == [MEMBERSHIP_EVENT_TYPE]
+ assert rows[0].sender_matrix_id == user_id
+ assert rows[0].sender_name == "nova"
+ assert rows[0].body is None
+
+ async def test_a_running_member_is_woken_and_joins_itself(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Waking the client is what leaves its transport watching the room.
+ Writing the membership underneath it would put it in a room it never
+ reads."""
+ async with session_factory() as session:
+ room = await _room(session)
+ client = await _client(session)
+ await session.commit()
+ room_id, transport_room_id = room.id, room.matrix_room_id
+ client_id, user_id = client.id, client.matrix_user_id
+
+ woken: list[str] = []
+
+ async def _handler(invited_to: str) -> None:
+ woken.append(invited_to)
+
+ invites = InviteBus()
+ invites.register(user_id, _handler)
+ await _provisioning(session_factory, invites).invite_to_room(
+ transport_room_id, user_id
+ )
+
+ assert woken == [transport_room_id]
+ async with session_factory() as session:
+ membership = await session.get(
+ ClientRoom, {"client_id": client_id, "room_id": room_id}
+ )
+ # Left to the client, which joins itself in response.
+ assert membership is None
+
+ async def test_inviting_a_member_who_is_already_in_does_nothing(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session)
+ client = await _client(session)
+ await session.commit()
+ transport_room_id, user_id = room.matrix_room_id, client.matrix_user_id
+ room_id, client_id = room.id, client.id
+
+ provisioning = _provisioning(session_factory)
+ await provisioning.invite_to_room(transport_room_id, user_id)
+ await provisioning.invite_to_room(transport_room_id, user_id)
+
+ async with session_factory() as session:
+ rows = await MessageStore().list_for_room(
+ session, room_id, after_seq=0, limit=10
+ )
+ membership = await session.get(
+ ClientRoom, {"client_id": client_id, "room_id": room_id}
+ )
+
+ assert membership is not None
+ assert len(rows) == 1
+
+ async def test_removing_a_member_takes_the_membership_away(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session)
+ client = await _client(session)
+ await session.commit()
+ transport_room_id, user_id = room.matrix_room_id, client.matrix_user_id
+ room_id, client_id = room.id, client.id
+
+ provisioning = _provisioning(session_factory)
+ await provisioning.invite_to_room(transport_room_id, user_id)
+ await provisioning.kick_user(transport_room_id, user_id)
+
+ async with session_factory() as session:
+ membership = await session.get(
+ ClientRoom, {"client_id": client_id, "room_id": room_id}
+ )
+ assert membership is None
+
+ async def test_removing_a_member_who_is_already_out_is_success(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session)
+ client = await _client(session)
+ await session.commit()
+ transport_room_id, user_id = room.matrix_room_id, client.matrix_user_id
+
+ await _provisioning(session_factory).kick_user(transport_room_id, user_id)
+
+ async def test_a_room_or_member_switch_does_not_know_is_an_error(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room = await _room(session)
+ await session.commit()
+ transport_room_id = room.matrix_room_id
+
+ provisioning = _provisioning(session_factory)
+ with pytest.raises(ProvisioningError):
+ await provisioning.invite_to_room("sw_room_nowhere", "@a:test")
+ with pytest.raises(ProvisioningError):
+ await provisioning.invite_to_room(transport_room_id, "@nobody:test")
+
+ async def test_a_recorded_member_is_still_woken(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A row is not proof that a running client is watching the room.
+
+ Something else may have written it, and there is a window at startup
+ where a client is running but not yet on the bus. Returning early on
+ the row would make a deaf membership permanent: every later
+ invitation would find the same row and stop.
+ """
+ async with session_factory() as session:
+ room = await _room(session)
+ client = await _client(session)
+ await session.commit()
+ transport_room_id, user_id = room.matrix_room_id, client.matrix_user_id
+
+ woken: list[str] = []
+
+ async def _handler(invited_to: str) -> None:
+ woken.append(invited_to)
+
+ provisioning = _provisioning(session_factory)
+ await provisioning.invite_to_room(transport_room_id, user_id)
+
+ invites = InviteBus()
+ invites.register(user_id, _handler)
+ await _provisioning(session_factory, invites).invite_to_room(
+ transport_room_id, user_id
+ )
+
+ assert woken == [transport_room_id]
diff --git a/core/tests/switch_core/test_migration_parity.py b/core/tests/switch_core/test_migration_parity.py
new file mode 100644
index 000000000..8f7579777
--- /dev/null
+++ b/core/tests/switch_core/test_migration_parity.py
@@ -0,0 +1,106 @@
+"""The migrations build the schema the models describe.
+
+Every other test provisions its schema with `Base.metadata.create_all`, so a
+model can gain a column, an index or a constraint that no migration ever
+applies and the whole suite still passes — the drift only shows up on a real
+deployment, where the table is the one Alembic built. This test replays the
+chain into an empty database and asks Alembic's autogenerate comparison
+whether anything is still missing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+from alembic.autogenerate import compare_metadata
+from alembic.config import Config
+from alembic.migration import MigrationContext
+from alembic.runtime.environment import EnvironmentContext
+from alembic.script import ScriptDirectory
+from sqlalchemy import Connection, text
+from sqlalchemy.ext.asyncio import create_async_engine
+
+import switch_core.db.models # noqa: F401 — registers every table on Base.metadata
+from switch_core.db.base import Base
+
+_CORE = Path(__file__).resolve().parents[2]
+_PARITY_DB = "migration_parity"
+
+
+def _script_directory(config: Config) -> ScriptDirectory:
+ config.set_main_option("script_location", str(_CORE / "switch_core" / "migrations"))
+ return ScriptDirectory.from_config(config)
+
+
+def _upgrade_to_head(connection: Connection) -> None:
+ """Replay the chain on an explicit connection.
+
+ Driven through `EnvironmentContext` rather than `alembic.command.upgrade`
+ so the repo's `env.py` — which builds its own engine from `SwitchConfig`
+ and would point at the deployment database — is never loaded.
+ """
+ config = Config(str(_CORE / "alembic.ini"))
+ script = _script_directory(config)
+
+ def do_upgrade(revision: str, context: Any) -> Any:
+ return script._upgrade_revs("head", revision)
+
+ with EnvironmentContext(config, script, fn=do_upgrade) as environment:
+ environment.configure(connection=connection, target_metadata=Base.metadata)
+ with environment.begin_transaction():
+ environment.run_migrations()
+
+
+def _diff(connection: Connection) -> list[Any]:
+ context = MigrationContext.configure(connection)
+ return list(compare_metadata(context, Base.metadata))
+
+
+def _is_real_drift(entry: Any) -> bool:
+ """Filter the one comparison Alembic cannot make faithfully.
+
+ A server default is compared as rendered SQL text, and Postgres echoes
+ `func.now()` back as `now()` while the model still holds the SQLAlchemy
+ construct, so every `server_default` column reports as modified whether or
+ not the migration matches. Nothing else is filtered: a missing table,
+ column, index, constraint or nullability change is real drift.
+ """
+ return not (isinstance(entry, tuple) and entry[0] == "modify_default")
+
+
+async def migrated_url(postgres_url: str) -> Any:
+ """An empty database, separate from the create_all one the store tests use."""
+ admin = create_async_engine(postgres_url, isolation_level="AUTOCOMMIT")
+ async with admin.connect() as connection:
+ await connection.execute(text(f'DROP DATABASE IF EXISTS "{_PARITY_DB}"'))
+ await connection.execute(text(f'CREATE DATABASE "{_PARITY_DB}"'))
+ await admin.dispose()
+
+ base, _, _ = postgres_url.rpartition("/")
+ try:
+ yield f"{base}/{_PARITY_DB}"
+ finally:
+ admin = create_async_engine(postgres_url, isolation_level="AUTOCOMMIT")
+ async with admin.connect() as connection:
+ await connection.execute(text(f'DROP DATABASE IF EXISTS "{_PARITY_DB}"'))
+ await admin.dispose()
+
+
+async def test_migrations_match_the_models(migrated_url: str) -> None:
+ engine = create_async_engine(migrated_url)
+ try:
+ async with engine.begin() as connection:
+ await connection.run_sync(_upgrade_to_head)
+ async with engine.connect() as connection:
+ diff = await connection.run_sync(_diff)
+ finally:
+ await engine.dispose()
+
+ drift = [entry for entry in diff if _is_real_drift(entry)]
+ assert not drift, (
+ "the migrations and the models disagree; autogenerate would emit:\n"
+ + "\n".join(f" {entry}" for entry in drift)
+ )
diff --git a/core/tests/switch_core/test_provisioning_port.py b/core/tests/switch_core/test_provisioning_port.py
new file mode 100644
index 000000000..f223eb8e6
--- /dev/null
+++ b/core/tests/switch_core/test_provisioning_port.py
@@ -0,0 +1,58 @@
+"""Every provisioning implementation must satisfy the port.
+
+Structural conformance is not checked anywhere else: neither implementation
+names the Protocol, and every caller annotates the port, so a signature
+drifting apart from the contract would type-check on both sides and only fail
+at the call. This is the same guard `test_no_nio_outside_transport.py` gives the
+transport port, in the shape a Protocol allows.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+import pytest
+
+from switch_core.matrix_admin import MatrixAdmin
+from switch_core.provisioning import Provisioning
+from switch_core.provisioning.postgres import PostgresProvisioning
+
+
[email protected]("implementation", [MatrixAdmin, PostgresProvisioning])
+def test_it_is_a_provisioning_implementation(implementation: type) -> None:
+ assert isinstance(implementation.__new__(implementation), Provisioning), (
+ f"{implementation.__name__} no longer satisfies Provisioning"
+ )
+
+
+def test_every_port_operation_has_a_matching_signature() -> None:
+ """`isinstance` on a Protocol checks names only, not what they take.
+
+ A parameter renamed or dropped on one side is exactly the drift this port
+ exists to prevent, and it is invisible to the check above.
+ """
+ for name in (
+ "register_user",
+ "verify_login",
+ "create_room",
+ "invite_to_room",
+ "kick_user",
+ "delete_room",
+ "close",
+ ):
+ expected = _rendered(getattr(Provisioning, name))
+ for implementation in (MatrixAdmin, PostgresProvisioning):
+ actual = _rendered(getattr(implementation, name))
+ assert actual == expected, (
+ f"{implementation.__name__}.{name} does not match the port"
+ )
+
+
+def _rendered(func: object) -> str:
+ """A signature as text, with the quotes deferred annotations add removed.
+
+ The port defers its annotations and `matrix_admin` does not, so the two
+ render the same types differently — `'str'` against `str` — while meaning
+ the same thing. Comparing the text without quotes compares the contract.
+ """
+ return str(inspect.signature(func)).replace("'", "")
diff --git a/core/tests/switch_core/transport/fake.py b/core/tests/switch_core/transport/fake.py
new file mode 100644
index 000000000..760699a70
--- /dev/null
+++ b/core/tests/switch_core/transport/fake.py
@@ -0,0 +1,245 @@
+"""A `MessageTransport` double for tests that need a client without a server.
+
+Every test that used to attach a fake nio client attaches one of these
+instead, so the thing under test talks to the port rather than to Matrix.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from switch_core.attachments import ATTACHMENT_GROUP_KEY
+from switch_core.transport import (
+ DownloadResult,
+ HistoryPage,
+ InboundEvent,
+ MessageFormat,
+ SendResult,
+ TransportError,
+ TransportHandlers,
+ UploadResult,
+)
+
+
+class FakeMessageRecorder:
+ """A `MessageRecorder` double for tests that send without a database."""
+
+ def __init__(self) -> None:
+ self.recorded: list[dict[str, Any]] = []
+
+ async def record(
+ self,
+ *,
+ transport_room_id: str,
+ result: SendResult,
+ sender_matrix_id: str,
+ sender_client_id: str,
+ sender_name: str,
+ ) -> None:
+ self.recorded.append(
+ {
+ "transport_room_id": transport_room_id,
+ "result": result,
+ "sender_matrix_id": sender_matrix_id,
+ "sender_client_id": sender_client_id,
+ "sender_name": sender_name,
+ }
+ )
+
+
+class FakeTransport:
+ """Records what was sent and replays what it was primed with."""
+
+ def __init__(
+ self,
+ *,
+ joined: list[str] | None = None,
+ upload_uri: str = "mxc://fake/abc",
+ history: HistoryPage | None = None,
+ download: DownloadResult | None = None,
+ fail_send: str | None = None,
+ ) -> None:
+ self._joined = joined if joined is not None else []
+ self._upload_uri = upload_uri
+ self._history = history or HistoryPage(events=[], next_token=None)
+ self._download = download or DownloadResult(body=b"", content_type="text/plain")
+ self._fail_send = fail_send
+
+ self.sent_messages: list[dict[str, Any]] = []
+ self.sent_events: list[tuple[str, str, dict[str, object]]] = []
+ self.sent_media: list[dict[str, Any]] = []
+ self.uploads: list[tuple[bytes, str, str]] = []
+ self.typing: list[tuple[str, bool]] = []
+ self.joins: list[str] = []
+ self.display_names: list[str] = []
+ self.handlers = TransportHandlers()
+ self.connected = False
+ self.closed = False
+ self.events_by_id: dict[str, InboundEvent] = {}
+ self.next_event_id = 0
+
+ # ── Session ───────────────────────────────────────────────────────────────
+
+ @property
+ def session_state(self) -> dict[str, str | None]:
+ return {"access_token": "fake-token", "device_id": "FAKEDEVICE"}
+
+ async def connect(self) -> None:
+ self.connected = True
+
+ async def close(self) -> None:
+ self.closed = True
+
+ async def relogin(self) -> None:
+ self.connected = True
+
+ def register_handlers(self, handlers: TransportHandlers) -> None:
+ self.handlers = handlers
+
+ async def receive_forever(self, *, since: str | None) -> None:
+ return None
+
+ # ── Outbound ──────────────────────────────────────────────────────────────
+
+ def _next_id(self) -> str:
+ self.next_event_id += 1
+ return f"$fake{self.next_event_id}"
+
+ async def send_message(
+ self,
+ room_id: str,
+ body: str,
+ *,
+ sender_name: str,
+ format: MessageFormat = "text",
+ mentions: list[str] | None = None,
+ thread_root_id: str | None = None,
+ extra_content: dict[str, object] | None = None,
+ ) -> SendResult:
+ if self._fail_send:
+ raise TransportError(self._fail_send)
+ self.sent_messages.append(
+ {
+ "room_id": room_id,
+ "body": body,
+ "sender_name": sender_name,
+ "format": format,
+ "mentions": mentions,
+ "thread_root_id": thread_root_id,
+ "extra_content": extra_content,
+ }
+ )
+ content: dict[str, object] = {
+ "msgtype": "m.text",
+ "body": body,
+ "sender_name": sender_name,
+ }
+ if extra_content:
+ content.update(extra_content)
+ if thread_root_id is not None:
+ content["m.relates_to"] = {
+ "rel_type": "m.thread",
+ "event_id": thread_root_id,
+ }
+ return SendResult(
+ event_id=self._next_id(),
+ event_type="m.room.message",
+ content=content,
+ )
+
+ async def send_event(
+ self, room_id: str, event_type: str, content: dict[str, object]
+ ) -> SendResult:
+ if self._fail_send:
+ raise TransportError(self._fail_send)
+ self.sent_events.append((room_id, event_type, content))
+ return SendResult(
+ event_id=self._next_id(), event_type=event_type, content=content
+ )
+
+ async def send_media(
+ self,
+ room_id: str,
+ uri: str,
+ filename: str,
+ mimetype: str,
+ size: int,
+ *,
+ sender_name: str,
+ msgtype: str,
+ caption: str | None = None,
+ thread_root_id: str | None = None,
+ group: dict[str, object] | None = None,
+ ) -> SendResult:
+ if self._fail_send:
+ raise TransportError(self._fail_send)
+ self.sent_media.append(
+ {
+ "room_id": room_id,
+ "uri": uri,
+ "filename": filename,
+ "mimetype": mimetype,
+ "size": size,
+ "sender_name": sender_name,
+ "msgtype": msgtype,
+ "caption": caption,
+ "thread_root_id": thread_root_id,
+ "group": group,
+ }
+ )
+ content: dict[str, object] = {
+ "msgtype": msgtype,
+ "body": caption if caption else filename,
+ "url": uri,
+ "info": {"mimetype": mimetype, "size": size},
+ "sender_name": sender_name,
+ }
+ if caption:
+ content["filename"] = filename
+ if group is not None:
+ content[ATTACHMENT_GROUP_KEY] = group
+ if thread_root_id is not None:
+ content["m.relates_to"] = {
+ "rel_type": "m.thread",
+ "event_id": thread_root_id,
+ }
+ return SendResult(
+ event_id=self._next_id(),
+ event_type="m.room.message",
+ content=content,
+ )
+
+ async def upload_media(
+ self, data: bytes, content_type: str, filename: str
+ ) -> UploadResult:
+ self.uploads.append((data, content_type, filename))
+ return UploadResult(uri=self._upload_uri)
+
+ async def download_media(self, uri: str) -> DownloadResult:
+ return self._download
+
+ async def set_typing(self, room_id: str, is_typing: bool) -> None:
+ self.typing.append((room_id, is_typing))
+
+ # ── History ───────────────────────────────────────────────────────────────
+
+ async def get_event(self, room_id: str, event_id: str) -> InboundEvent | None:
+ return self.events_by_id.get(event_id)
+
+ async def read_history(
+ self, room_id: str, *, start: str | None, limit: int
+ ) -> HistoryPage:
+ return self._history
+
+ # ── Rooms ─────────────────────────────────────────────────────────────────
+
+ async def join_room(self, room_id: str) -> bool:
+ self.joins.append(room_id)
+ self._joined.append(room_id)
+ return True
+
+ async def joined_rooms(self) -> list[str]:
+ return list(self._joined)
+
+ async def set_display_name(self, display_name: str) -> None:
+ self.display_names.append(display_name)
diff --git a/core/tests/switch_core/transport/test_matrix_transport.py b/core/tests/switch_core/transport/test_matrix_transport.py
new file mode 100644
index 000000000..01e0bb6e2
--- /dev/null
+++ b/core/tests/switch_core/transport/test_matrix_transport.py
@@ -0,0 +1,224 @@
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+from nio import RoomMessagesError, RoomSendError
+
+from switch_core.attachments import ATTACHMENT_GROUP_KEY
+from switch_core.transport import (
+ MessageTransport,
+ TransportError,
+ TransportHandlers,
+)
+from switch_core.transport.matrix import MatrixTransport
+
+
+class _FakeNio:
+ def __init__(self, *, send_result: Any = None, upload_result: Any = None) -> None:
+ self._send_result = send_result or SimpleNamespace(event_id="$evt")
+ self._upload_result = upload_result
+ self.room_send_calls: list[tuple[str, str, dict]] = []
+ self.typing_calls: list[tuple[str, bool]] = []
+ self.callbacks: list[tuple[Any, Any]] = []
+ self.response_callbacks: list[tuple[Any, Any]] = []
+ self.access_token = "tok"
+
+ async def room_send(self, room_id: str, event_type: str, content: dict) -> Any:
+ self.room_send_calls.append((room_id, event_type, content))
+ return self._send_result
+
+ async def upload(self, **kwargs: Any) -> tuple[Any, None]:
+ return self._upload_result, None
+
+ async def room_typing(self, room_id: str, is_typing: bool) -> Any:
+ self.typing_calls.append((room_id, is_typing))
+ return SimpleNamespace()
+
+ async def joined_rooms(self) -> Any:
+ return SimpleNamespace(rooms=["!a:s"])
+
+ async def join(self, room_id: str) -> Any:
+ return SimpleNamespace(room_id=room_id)
+
+ async def room_messages(self, room_id: str, start: str | None, limit: int) -> Any:
+ return SimpleNamespace(chunk=["e1", "e2"], end="tok-2")
+
+ def add_event_callback(self, cb: Any, kind: Any) -> None:
+ self.callbacks.append((cb, kind))
+
+ def add_response_callback(self, cb: Any, kind: Any) -> None:
+ self.response_callbacks.append((cb, kind))
+
+
+def _transport(nio: _FakeNio) -> MatrixTransport:
+ return MatrixTransport(
+ server_url="https://s",
+ user_id="@a:s",
+ password="pw",
+ client=nio,
+ )
+
+
+def test_matrix_transport_satisfies_the_port() -> None:
+ assert isinstance(_transport(_FakeNio()), MessageTransport)
+
+
+async def test_send_message_returns_a_neutral_result() -> None:
+ nio = _FakeNio()
+
+ result = await _transport(nio).send_message("!r:s", "hi", sender_name="Alice")
+
+ assert result.event_id == "$evt"
+ room_id, event_type, content = nio.room_send_calls[0]
+ assert (room_id, event_type) == ("!r:s", "m.room.message")
+ assert content["body"] == "hi"
+ assert content["sender_name"] == "Alice"
+
+
+async def test_send_message_threads_via_a_pure_thread_relation() -> None:
+ nio = _FakeNio()
+
+ await _transport(nio).send_message(
+ "!r:s", "hi", sender_name="Alice", thread_root_id="$root"
+ )
+
+ _, _, content = nio.room_send_calls[0]
+ assert content["m.relates_to"] == {"rel_type": "m.thread", "event_id": "$root"}
+
+
+async def test_send_message_raises_rather_than_returning_an_error() -> None:
+ nio = _FakeNio(send_result=object.__new__(RoomSendError))
+ nio._send_result.message = "nope" # type: ignore[attr-defined]
+
+ with pytest.raises(TransportError, match="nope"):
+ await _transport(nio).send_message("!r:s", "hi", sender_name="Alice")
+
+
+async def test_send_media_with_a_caption_keeps_the_filename_separate() -> None:
+ # The rich-media-caption convention: body carries the caption, and the real
+ # filename rides alongside so it is not lost.
+ nio = _FakeNio()
+
+ await _transport(nio).send_media(
+ "!r:s",
+ "mxc://s/abc",
+ "cat.png",
+ "image/png",
+ 5,
+ sender_name="Alice",
+ msgtype="m.image",
+ caption="look at this",
+ )
+
+ _, _, content = nio.room_send_calls[0]
+ assert content["body"] == "look at this"
+ assert content["filename"] == "cat.png"
+ assert content["url"] == "mxc://s/abc"
+ assert content["info"] == {"mimetype": "image/png", "size": 5}
+
+
+async def test_send_media_without_a_caption_uses_the_filename_as_body() -> None:
+ nio = _FakeNio()
+
+ await _transport(nio).send_media(
+ "!r:s",
+ "mxc://s/abc",
+ "cat.png",
+ "image/png",
+ 5,
+ sender_name="Alice",
+ msgtype="m.image",
+ )
+
+ _, _, content = nio.room_send_calls[0]
+ assert content["body"] == "cat.png"
+ # No caption means nothing to disambiguate, so no separate filename key.
+ assert "filename" not in content
+
+
+async def test_send_media_marks_a_multi_file_group() -> None:
+ # Matrix has no multi-attachment event, so N files share a group id that
+ # receivers coalesce back into one message.
+ nio = _FakeNio()
+ group = {"id": "g1", "index": 0, "total": 2}
+
+ await _transport(nio).send_media(
+ "!r:s",
+ "mxc://s/abc",
+ "cat.png",
+ "image/png",
+ 5,
+ sender_name="Alice",
+ msgtype="m.image",
+ group=group,
+ )
+
+ _, _, content = nio.room_send_calls[0]
+ assert content[ATTACHMENT_GROUP_KEY] == group
+
+
+async def test_send_event_carries_the_type_through() -> None:
+ nio = _FakeNio()
+
+ await _transport(nio).send_event("!r:s", "com.switch.task.accept", {"task_id": "t"})
+
+ assert nio.room_send_calls[0][1] == "com.switch.task.accept"
+
+
+async def test_read_history_returns_neutral_events_and_its_cursor() -> None:
+ nio = _FakeNio()
+
+ async def _chunk(*args: Any, **kwargs: Any) -> Any:
+ return SimpleNamespace(
+ chunk=[
+ SimpleNamespace(
+ event_id="$1",
+ sender="@a:s",
+ server_timestamp=7,
+ body="hello",
+ source={"content": {"body": "hello"}},
+ )
+ ],
+ end="tok-2",
+ )
+
+ nio.room_messages = _chunk # type: ignore[assignment]
+
+ page = await _transport(nio).read_history("!r:s", start=None, limit=10)
+
+ assert page.next_token == "tok-2"
+ assert [e.event_id for e in page.events] == ["$1"]
+ # History arrives already converted, so callers never see a nio type.
+ assert page.events[0].room_id == "!r:s"
+ assert page.events[0].timestamp == 7
+
+
+async def test_read_history_raises_on_failure() -> None:
+ nio = _FakeNio()
+ err = object.__new__(RoomMessagesError)
+ err.message = "boom" # type: ignore[attr-defined]
+
+ async def _fail(*args: Any, **kwargs: Any) -> Any:
+ return err
+
+ nio.room_messages = _fail # type: ignore[assignment]
+
+ with pytest.raises(TransportError, match="boom"):
+ await _transport(nio).read_history("!r:s", start=None, limit=10)
+
+
+def test_register_handlers_binds_only_what_was_supplied() -> None:
+ nio = _FakeNio()
+
+ _transport(nio).register_handlers(TransportHandlers(on_message=lambda r, e: None)) # type: ignore[arg-type]
+
+ assert len(nio.callbacks) == 1
+ assert nio.response_callbacks == []
+
+
+async def test_typing_is_best_effort() -> None:
+ nio = _FakeNio()
+
+ await _transport(nio).set_typing("!r:s", True)
+
+ assert nio.typing_calls == [("!r:s", True)]
diff --git a/core/tests/switch_core/transport/test_no_nio_outside_transport.py b/core/tests/switch_core/transport/test_no_nio_outside_transport.py
new file mode 100644
index 000000000..efc10f439
--- /dev/null
+++ b/core/tests/switch_core/transport/test_no_nio_outside_transport.py
@@ -0,0 +1,57 @@
+"""The seam only holds if something enforces it.
+
+Matrix may be imported in exactly one place. Without this check the port
+erodes the first time someone reaches for a nio type in a hurry, and the
+erosion is invisible until the homeserver is being replaced.
+"""
+
+import ast
+import pathlib
+
+PACKAGE = pathlib.Path(__file__).resolve().parents[3] / "switch_core"
+ALLOWED = {PACKAGE / "transport" / "matrix.py"}
+
+
+def _imports_nio(path: pathlib.Path) -> bool:
+ tree = ast.parse(path.read_text(), filename=str(path))
+ for node in ast.walk(tree):
+ if isinstance(node, ast.Import):
+ if any(a.name == "nio" or a.name.startswith("nio.") for a in node.names):
+ return True
+ elif isinstance(node, ast.ImportFrom):
+ module = node.module or ""
+ if module == "nio" or module.startswith("nio."):
+ return True
+ return False
+
+
+def test_only_the_matrix_transport_imports_nio() -> None:
+ offenders = sorted(
+ str(path.relative_to(PACKAGE))
+ for path in PACKAGE.rglob("*.py")
+ if path not in ALLOWED and _imports_nio(path)
+ )
+
+ assert offenders == [], (
+ "matrix-nio may only be imported by switch_core/transport/matrix.py; "
+ f"these modules import it directly: {offenders}. "
+ "Add what you need to MessageTransport instead."
+ )
+
+
+def test_the_guard_can_actually_see_an_import(tmp_path: pathlib.Path) -> None:
+ offender = tmp_path / "offender.py"
+ offender.write_text("from nio import AsyncClient\n")
+
+ assert _imports_nio(offender)
+
+
+def test_no_module_reaches_for_a_raw_client() -> None:
+ """`nio_client` was the escape hatch during the port. It is gone."""
+ offenders = sorted(
+ str(path.relative_to(PACKAGE))
+ for path in PACKAGE.rglob("*.py")
+ if "nio_client" in path.read_text()
+ )
+
+ assert offenders == []
diff --git a/core/tests/switch_core/transport/test_postgres_transport.py b/core/tests/switch_core/transport/test_postgres_transport.py
new file mode 100644
index 000000000..f05de0c16
--- /dev/null
+++ b/core/tests/switch_core/transport/test_postgres_transport.py
@@ -0,0 +1,862 @@
+"""Sending and receiving over Postgres.
+
+These run against a real database because the whole point of the transport is
+what the table ends up holding — the seq allocation, the denormalised columns
+and the attachment row are the behaviour, not an implementation detail behind
+it.
+
+What is deliberately not implemented is tested too: a transport that quietly
+returns nothing would look like a working deployment with a silent room, which
+is the one failure this codebase refuses to ship.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Iterator
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import Client, Room
+from switch_core.db.stores.media_store import MediaStore
+from switch_core.db.stores.message_store import MessageStore
+from switch_core.db.stores.room_store import RoomStore
+from switch_core.transport import (
+ InboundCustomEvent,
+ InboundMedia,
+ InboundMembership,
+ InboundMessage,
+ MessageTransport,
+ TransportError,
+ TransportHandlers,
+)
+from switch_core.transport.ephemeral import EphemeralBus
+from switch_core.transport.invites import InviteBus
+from switch_core.transport.postgres import PostgresTransport
+
+
+async def _make_room(session: AsyncSession) -> tuple[str, str, str, str]:
+ """Insert the Room and Client a send depends on.
+
+ Returns (room uuid, transport room id, client id, client mxid).
+ """
+ suffix = uuid.uuid4().hex[:8]
+ client = Client(
+ matrix_user_id=f"@agent-{suffix}:test",
+ display_name="agent one",
+ type="agent",
+ password="x",
+ )
+ session.add(client)
+ await session.flush()
+ room = Room(matrix_room_id=f"!room-{suffix}:test", name="a room", description="")
+ session.add(room)
+ await session.flush()
+ return room.id, room.matrix_room_id, client.id, client.matrix_user_id
+
+
+async def _watched_room(transport: PostgresTransport) -> str:
+ """Wait until the transport is watching a room, and name it.
+
+ `receive_forever` resolves memberships against the database before it
+ subscribes, so a test that sends immediately after starting it would race
+ the subscription rather than test anything.
+ """
+ for _ in range(200):
+ if transport._watching:
+ return next(iter(transport._watching))
+ await asyncio.sleep(0.01)
+ raise AssertionError("the transport never started watching a room")
+
+
+async def _settled(transport: PostgresTransport) -> None:
+ """Wait until a transport has nothing left to read."""
+ for _ in range(500):
+ if not transport._pending and not transport._delivering:
+ return
+ await asyncio.sleep(0.005)
+ raise AssertionError("the transport never finished delivering")
+
+
+class _FakeListener:
+ """Stands in for the notify listener, so a test can say "the room moved".
+
+ The real listener is a trigger and a LISTEN, covered by its own tests
+ against a live database. What matters here is what the transport does when
+ it is woken, which is a question about cursors and conversion.
+ """
+
+ def __init__(self) -> None:
+ self.wakers: dict[str, set] = {}
+
+ def subscribe(self, room_id: str, waker) -> None:
+ self.wakers.setdefault(room_id, set()).add(waker)
+
+ def unsubscribe(self, room_id: str, waker) -> None:
+ self.wakers.get(room_id, set()).discard(waker)
+
+ async def announce(self, room_id: str) -> None:
+ """Say the room moved, and wait for the reading it provokes.
+
+ A waker only notes the room now — each transport reads on its own
+ loop, so that a client whose handler is slow cannot hold up anyone
+ else's delivery. Waiting for those loops to go idle is what makes a
+ test assert on what was delivered rather than on the timing.
+ """
+ woken = []
+ for waker in list(self.wakers.get(room_id, ())):
+ await waker(room_id)
+ woken.append(waker.__self__)
+ for transport in woken:
+ await _settled(transport)
+
+
+class _Received:
+ """Collects what the transport handed to each handler."""
+
+ def __init__(self) -> None:
+ self.events: list[object] = []
+
+ def handlers(self) -> TransportHandlers:
+ return TransportHandlers(
+ on_message=self._take,
+ on_media=self._take,
+ on_member_event=self._take,
+ on_custom_event=self._take,
+ )
+
+ async def _take(self, _room, event) -> None:
+ self.events.append(event)
+
+
+def _transport(
+ session_factory: async_sessionmaker[AsyncSession],
+ *,
+ client_id: str,
+ user_id: str,
+ listener: _FakeListener | None = None,
+ ephemeral: EphemeralBus | None = None,
+) -> PostgresTransport:
+ return PostgresTransport(
+ user_id=user_id,
+ client_id=client_id,
+ display_name="agent one",
+ session_factory=session_factory,
+ room_store=RoomStore(),
+ message_store=MessageStore(),
+ media_store=MediaStore(),
+ listener=listener or _FakeListener(),
+ invites=InviteBus(),
+ ephemeral=ephemeral or EphemeralBus(),
+ )
+
+
+class TestConformsToThePort:
+ def test_it_is_a_message_transport(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ transport = _transport(session_factory, client_id="c", user_id="@a:test")
+ assert isinstance(transport, MessageTransport)
+
+
+class TestSending:
+ async def test_a_message_becomes_a_row(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ room_id, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ result = await transport.send_message(
+ transport_room_id, "hello", sender_name="agent one"
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(
+ session, result.event_id
+ )
+
+ assert message is not None
+ assert message.room_id == room_id
+ assert message.body == "hello"
+ assert message.msgtype == "m.text"
+ assert message.event_type == "m.room.message"
+ assert message.sender_client_id == client_id
+ assert message.sender_matrix_id == user_id
+ # The id the caller got back is the row's, so a caller that quotes it
+ # in a reply or a thread is naming something that exists.
+ assert message.transport_event_id == result.event_id
+ assert result.content["body"] == "hello"
+
+ async def test_the_room_orders_its_sends(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ first = await transport.send_message(
+ transport_room_id, "one", sender_name="agent one"
+ )
+ second = await transport.send_message(
+ transport_room_id, "two", sender_name="agent one"
+ )
+
+ async with session_factory() as session:
+ store = MessageStore()
+ a = await store.get_by_transport_event_id(session, first.event_id)
+ b = await store.get_by_transport_event_id(session, second.event_id)
+
+ assert a is not None and b is not None
+ assert b.seq > a.seq
+
+ async def test_a_threaded_reply_records_its_root(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ result = await transport.send_message(
+ transport_room_id,
+ "in the thread",
+ sender_name="agent one",
+ thread_root_id="root-1",
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(
+ session, result.event_id
+ )
+
+ assert message is not None
+ assert message.thread_root_event_id == "root-1"
+
+ async def test_media_records_the_file_beside_the_message(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ result = await transport.send_media(
+ transport_room_id,
+ "blob://1",
+ "report.pdf",
+ "application/pdf",
+ 2048,
+ sender_name="agent one",
+ msgtype="m.file",
+ caption="the report",
+ )
+
+ async with session_factory() as session:
+ store = MessageStore()
+ message = await store.get_by_transport_event_id(session, result.event_id)
+ assert message is not None
+ attachments = await store.get_attachments(session, message.id)
+
+ # The caption is the body, per the rich-media-caption convention, and
+ # the real filename travels on the attachment.
+ assert message.body == "the report"
+ assert len(attachments) == 1
+ assert attachments[0].uri == "blob://1"
+ assert attachments[0].filename == "report.pdf"
+ assert attachments[0].mimetype == "application/pdf"
+ assert attachments[0].size == 2048
+
+ async def test_a_custom_event_is_stored_whole(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A task event is not conversation, but it still has to reach its
+ handler, and here the row is the only way it can."""
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ result = await transport.send_event(
+ transport_room_id, "com.switch.task.accept", {"task_id": "t-1"}
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(
+ session, result.event_id
+ )
+
+ assert message is not None
+ assert message.event_type == "com.switch.task.accept"
+ assert message.content == {"task_id": "t-1"}
+ assert message.body is None
+
+ async def test_ephemeral_state_is_announced_and_not_stored(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Presence has no history worth keeping: the next value replaces it,
+ and a row would put it in the room's order for nobody to read."""
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ result = await transport.send_event(
+ transport_room_id, "com.switch.agent.runtime_state", {"state": "working"}
+ )
+
+ async with session_factory() as session:
+ message = await MessageStore().get_by_transport_event_id(
+ session, result.event_id
+ )
+
+ assert message is None
+ assert result.event_id
+
+ async def test_sending_to_a_room_switch_does_not_know_fails(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ transport = _transport(session_factory, client_id="c", user_id="@a:test")
+ with pytest.raises(TransportError):
+ await transport.send_message(
+ "!nowhere:test", "hello", sender_name="agent one"
+ )
+
+
+class TestRooms:
+ async def test_joining_is_a_membership_row_and_is_idempotent(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ assert await transport.join_room(transport_room_id) is True
+ assert await transport.join_room(transport_room_id) is True
+ assert await transport.joined_rooms() == [transport_room_id]
+
+ async def test_a_client_in_no_rooms_is_in_no_rooms(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, _, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ assert await transport.joined_rooms() == []
+
+
+class TestMedia:
+ async def test_bytes_go_in_and_come_back(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ transport = _transport(session_factory, client_id="c", user_id="@a:test")
+
+ uploaded = await transport.upload_media(b"file contents", "text/plain", "a.txt")
+ downloaded = await transport.download_media(uploaded.uri)
+
+ assert downloaded.body == b"file contents"
+ assert downloaded.content_type == "text/plain"
+ assert downloaded.filename == "a.txt"
+
+ async def test_two_uploads_of_the_same_bytes_are_two_handles(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Deduplicating would make one sender's delete another's data loss."""
+ transport = _transport(session_factory, client_id="c", user_id="@a:test")
+
+ first = await transport.upload_media(b"same", "text/plain", "a.txt")
+ second = await transport.upload_media(b"same", "text/plain", "a.txt")
+
+ assert first.uri != second.uri
+
+ async def test_a_handle_with_nothing_behind_it_raises(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """An empty file is a worse answer than an error: the reader cannot
+ tell it apart from a file that was genuinely empty."""
+ transport = _transport(session_factory, client_id="c", user_id="@a:test")
+
+ with pytest.raises(TransportError):
+ await transport.download_media("switch-media://nothing")
+
+
+class TestWhatIsNotBuiltYet:
+ async def test_history_refuses_rather_than_answering_from_the_wrong_place(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The read path queries these rows directly; the only callers of this
+ method are the walkers that compare a bus against them."""
+ transport = _transport(session_factory, client_id="c", user_id="@a:test")
+ with pytest.raises(NotImplementedError):
+ await transport.read_history("!r:test", start=None, limit=10)
+
+
+class TestReceiving:
+ """What a woken transport hands to its handlers.
+
+ Delivery is driven by the announcement the database makes on every insert;
+ a fake listener stands in for it so these tests are about the cursor and
+ the conversion rather than about the trigger, which has its own.
+ """
+
+ async def _receiving(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ ) -> tuple[PostgresTransport, _FakeListener, _Received, str, str]:
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ listener = _FakeListener()
+ received = _Received()
+ transport = _transport(
+ session_factory, client_id=client_id, user_id=user_id, listener=listener
+ )
+ transport.register_handlers(received.handlers())
+ await transport.join_room(transport_room_id)
+ task = asyncio.create_task(transport.receive_forever(since=None))
+ self._tasks.append((task, transport))
+ await _watched_room(transport)
+ return transport, listener, received, transport_room_id, user_id
+
+ @pytest.fixture(autouse=True)
+ def _cleanup(self) -> Iterator[None]:
+ self._tasks: list[tuple[asyncio.Task, PostgresTransport]] = []
+ yield
+ for task, _ in self._tasks:
+ task.cancel()
+
+ async def test_a_message_arrives_as_a_message(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ transport, listener, received, room, _ = await self._receiving(session_factory)
+
+ sent = await transport.send_message(room, "hello", sender_name="agent one")
+ await listener.announce(await _watched_room(transport))
+
+ assert len(received.events) == 1
+ event = received.events[0]
+ assert isinstance(event, InboundMessage)
+ assert event.event_id == sent.event_id
+ assert event.body == "hello"
+ # The room a handler is given is the transport-side id it knows, not
+ # the internal one the listener announces.
+ assert event.room_id == room
+
+ async def test_the_cursor_starts_at_the_head_and_does_not_repeat(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """A restart is not a replay.
+
+ Everything before this transport started receiving is already someone
+ else's problem — a delivery cursor's — and redelivering it would be
+ indistinguishable to a reader from it being said again.
+ """
+ async with session_factory() as session:
+ _, room, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ listener = _FakeListener()
+ writer = _transport(session_factory, client_id=client_id, user_id=user_id)
+ await writer.send_message(room, "said before anyone listened", sender_name="a")
+
+ received = _Received()
+ reader = _transport(
+ session_factory, client_id=client_id, user_id=user_id, listener=listener
+ )
+ reader.register_handlers(received.handlers())
+ await reader.join_room(room)
+ task = asyncio.create_task(reader.receive_forever(since=None))
+ self._tasks.append((task, reader))
+ switch_room_id = await _watched_room(reader)
+ await listener.announce(switch_room_id)
+ assert received.events == []
+
+ await writer.send_message(room, "said after", sender_name="a")
+ await listener.announce(switch_room_id)
+ await listener.announce(switch_room_id)
+
+ bodies = [event.body for event in received.events]
+ assert bodies == ["said after"]
+
+ async def test_a_file_arrives_as_media(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ transport, listener, received, room, _ = await self._receiving(session_factory)
+
+ await transport.send_media(
+ room,
+ "blob://7",
+ "notes.txt",
+ "text/plain",
+ 12,
+ sender_name="agent one",
+ msgtype="m.file",
+ )
+ await listener.announce(await _watched_room(transport))
+
+ event = received.events[0]
+ assert isinstance(event, InboundMedia)
+ assert event.uri == "blob://7"
+ assert event.filename == "notes.txt"
+ assert event.mimetype == "text/plain"
+ assert event.size == 12
+
+ async def test_a_custom_event_arrives_as_one(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ transport, listener, received, room, _ = await self._receiving(session_factory)
+
+ await transport.send_event(room, "com.switch.command", {"command": "roles"})
+ await listener.announce(await _watched_room(transport))
+
+ event = received.events[0]
+ assert isinstance(event, InboundCustomEvent)
+ assert event.event_type == "com.switch.command"
+ assert event.content == {"command": "roles"}
+
+ async def test_an_arrival_is_delivered_to_the_members_watching(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Joining writes the arrival, so the room learns about it the same way
+ it learns about anything else: a row it has not read yet."""
+ transport, listener, received, room, _ = await self._receiving(session_factory)
+
+ async with session_factory() as session:
+ newcomer = Client(
+ matrix_user_id=f"@later-{uuid.uuid4().hex[:8]}:test",
+ display_name="the newcomer",
+ type="agent",
+ password="x",
+ )
+ session.add(newcomer)
+ await session.commit()
+ newcomer_id, newcomer_mxid = newcomer.id, newcomer.matrix_user_id
+
+ joiner = _transport(
+ session_factory, client_id=newcomer_id, user_id=newcomer_mxid
+ )
+ joiner.display_name = "the newcomer"
+ await joiner.join_room(room)
+ await listener.announce(await _watched_room(transport))
+
+ event = received.events[0]
+ assert isinstance(event, InboundMembership)
+ assert event.state_key == newcomer_mxid
+ assert event.membership == "join"
+ assert event.display_name == "the newcomer"
+
+
+class TestPresence:
+ """Events that are announced and never stored still have to arrive.
+
+ Dropping the row dropped the delivery with it: runtime state was recorded
+ in its own table and reached nobody, so an agent going busy stopped showing
+ up on a bridged channel. The value travels on the announcement, because
+ there is no row for a reader to go and fetch.
+ """
+
+ @pytest.fixture(autouse=True)
+ def _cleanup(self) -> Iterator[None]:
+ self._tasks: list[asyncio.Task] = []
+ yield
+ for task in self._tasks:
+ task.cancel()
+
+ async def test_presence_reaches_the_other_clients_watching_the_room(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, room, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ ephemeral = EphemeralBus()
+ received = _Received()
+ watcher = _transport(
+ session_factory, client_id=client_id, user_id=user_id, ephemeral=ephemeral
+ )
+ watcher.register_handlers(received.handlers())
+ await watcher.join_room(room)
+ self._tasks.append(asyncio.create_task(watcher.receive_forever(since=None)))
+ await _watched_room(watcher)
+
+ sender = _transport(
+ session_factory, client_id=client_id, user_id=user_id, ephemeral=ephemeral
+ )
+ await sender.send_event(
+ room, "com.switch.agent.runtime_state", {"state": "working"}
+ )
+
+ assert len(received.events) == 1
+ event = received.events[0]
+ assert isinstance(event, InboundCustomEvent)
+ assert event.event_type == "com.switch.agent.runtime_state"
+ assert event.content == {"state": "working"}
+ # The room a handler is given is the transport-side id, as for a row.
+ assert event.room_id == room
+
+ async def test_presence_in_another_room_is_not_delivered(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, room, client_id, user_id = await _make_room(session)
+ _, elsewhere, other_client_id, other_user_id = await _make_room(session)
+ await session.commit()
+
+ ephemeral = EphemeralBus()
+ received = _Received()
+ watcher = _transport(
+ session_factory, client_id=client_id, user_id=user_id, ephemeral=ephemeral
+ )
+ watcher.register_handlers(received.handlers())
+ await watcher.join_room(room)
+ self._tasks.append(asyncio.create_task(watcher.receive_forever(since=None)))
+ await _watched_room(watcher)
+
+ sender = _transport(
+ session_factory,
+ client_id=other_client_id,
+ user_id=other_user_id,
+ ephemeral=ephemeral,
+ )
+ await sender.send_event(
+ elsewhere, "com.switch.agent.runtime_state", {"state": "idle"}
+ )
+
+ assert received.events == []
+
+ async def test_a_client_that_stopped_receiving_is_no_longer_told(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Presence is delivered live, so a closed client must leave the bus —
+ otherwise it holds a handler for a room nobody is reading."""
+ async with session_factory() as session:
+ _, room, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ ephemeral = EphemeralBus()
+ received = _Received()
+ watcher = _transport(
+ session_factory, client_id=client_id, user_id=user_id, ephemeral=ephemeral
+ )
+ watcher.register_handlers(received.handlers())
+ await watcher.join_room(room)
+ task = asyncio.create_task(watcher.receive_forever(since=None))
+ self._tasks.append(task)
+ await _watched_room(watcher)
+ await watcher.close()
+ await task
+
+ await watcher.send_event(
+ room, "com.switch.agent.runtime_state", {"state": "idle"}
+ )
+
+ assert received.events == []
+
+
+class TestOneClientCannotStallAnother:
+ """The listener fans out to every subscriber from a single task.
+
+ So whatever a waker awaits, every other client in the process waits for
+ too — and a handler can be a bridge posting to Slack, which is a network
+ call that sits in a rate limit for seconds. Under Matrix each client had
+ its own sync loop and got this isolation for free; here it is built.
+ """
+
+ @pytest.fixture(autouse=True)
+ def _cleanup(self) -> Iterator[None]:
+ self._tasks: list[asyncio.Task] = []
+ yield
+ for task in self._tasks:
+ task.cancel()
+
+ async def test_being_woken_does_not_deliver_on_the_caller_s_time(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, room, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ listener = _FakeListener()
+ received = _Received()
+ transport = _transport(
+ session_factory, client_id=client_id, user_id=user_id, listener=listener
+ )
+ transport.register_handlers(received.handlers())
+ await transport.join_room(room)
+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))
+ switch_room_id = await _watched_room(transport)
+
+ await transport.send_message(room, "hello", sender_name="agent one")
+ # The waker itself, rather than the fake's announce, which waits for
+ # the reading it provokes.
+ await transport._on_room_advanced(switch_room_id)
+
+ assert received.events == []
+ assert transport._pending == {switch_room_id}
+
+ await _settled(transport)
+ assert [event.body for event in received.events] == ["hello"]
+
+ async def test_rooms_that_moved_while_it_was_busy_are_read_once(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """Coalescing is what keeps the loop serial without falling behind:
+ a room announced three times is still one read, and running those
+ concurrently would deliver the same rows three times."""
+ async with session_factory() as session:
+ _, room, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ listener = _FakeListener()
+ received = _Received()
+ transport = _transport(
+ session_factory, client_id=client_id, user_id=user_id, listener=listener
+ )
+ transport.register_handlers(received.handlers())
+ await transport.join_room(room)
+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))
+ switch_room_id = await _watched_room(transport)
+
+ await transport.send_message(room, "hello", sender_name="agent one")
+ await transport._on_room_advanced(switch_room_id)
+ await transport._on_room_advanced(switch_room_id)
+ await transport._on_room_advanced(switch_room_id)
+ await _settled(transport)
+
+ assert [event.body for event in received.events] == ["hello"]
+
+
+class TestJoiningARoomAlreadyRecorded:
+ """Membership and subscription are two facts now.
+
+ The homeserver's join *was* what a sync loop delivered, so one implied the
+ other. A `client_rooms` row can be written by something other than this
+ client, and a join that returned early on finding one would leave a
+ running client a member of a room it never reads.
+ """
+
+ @pytest.fixture(autouse=True)
+ def _cleanup(self) -> Iterator[None]:
+ self._tasks: list[asyncio.Task] = []
+ yield
+ for task in self._tasks:
+ task.cancel()
+
+ async def test_it_starts_watching_and_writes_no_second_arrival(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ switch_room_id, room, client_id, user_id = await _make_room(session)
+ elsewhere_id, elsewhere, _, _ = await _make_room(session)
+ await session.commit()
+
+ listener = _FakeListener()
+ received = _Received()
+ transport = _transport(
+ session_factory, client_id=client_id, user_id=user_id, listener=listener
+ )
+ transport.register_handlers(received.handlers())
+ await transport.join_room(room)
+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))
+ await _watched_room(transport)
+
+ # Somebody else records the membership — what a moderation invite does
+ # when nothing is listening for this client.
+ async with session_factory() as session:
+ await RoomStore().add_client(session, client_id, elsewhere_id)
+ await session.commit()
+
+ assert await transport.join_room(elsewhere) is True
+ # Joining again must not announce a second arrival to the room.
+ assert await transport.join_room(elsewhere) is True
+
+ assert elsewhere_id in transport._watching
+ async with session_factory() as session:
+ rows = await MessageStore().list_for_room(
+ session, elsewhere_id, after_seq=0, limit=10
+ )
+ assert rows == []
+
+
+class TestHearingYourOwnArrival:
+ """A client learns it joined by being told, as it always did.
+
+ The homeserver turned a join into an event and delivered it to everyone —
+ including the client it was about, down its own connection — and code
+ downstream (the greeting an agent posts on entering a room) fired on
+ receiving it. Writing the row and then watching from the head steps over
+ it: the room hears the arrival and the arriving client does not.
+ """
+
+ @pytest.fixture(autouse=True)
+ def _cleanup(self) -> Iterator[None]:
+ self._tasks: list[asyncio.Task] = []
+ yield
+ for task in self._tasks:
+ task.cancel()
+
+ async def test_joining_while_receiving_delivers_the_join_to_itself(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, room, client_id, user_id = await _make_room(session)
+ _, later, _, _ = await _make_room(session)
+ await session.commit()
+
+ listener = _FakeListener()
+ received = _Received()
+ transport = _transport(
+ session_factory, client_id=client_id, user_id=user_id, listener=listener
+ )
+ transport.register_handlers(received.handlers())
+ await transport.join_room(room)
+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))
+ await _watched_room(transport)
+
+ await transport.join_room(later)
+ await _settled(transport)
+
+ assert len(received.events) == 1
+ event = received.events[0]
+ assert isinstance(event, InboundMembership)
+ assert event.state_key == user_id
+ assert event.membership == "join"
+ assert event.room_id == later
+
+ async def test_it_hears_the_join_once(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ """The cursor starts just below the arrival, not at the room's start:
+ a client joining a room with history must not be handed all of it."""
+ async with session_factory() as session:
+ _, room, client_id, user_id = await _make_room(session)
+ _, later, other_id, other_user = await _make_room(session)
+ await session.commit()
+
+ talker = _transport(session_factory, client_id=other_id, user_id=other_user)
+ await talker.join_room(later)
+ await talker.send_message(later, "said before anyone joined", sender_name="a")
+
+ listener = _FakeListener()
+ received = _Received()
+ transport = _transport(
+ session_factory, client_id=client_id, user_id=user_id, listener=listener
+ )
+ transport.register_handlers(received.handlers())
+ await transport.join_room(room)
+ self._tasks.append(asyncio.create_task(transport.receive_forever(since=None)))
+ await _watched_room(transport)
+
+ await transport.join_room(later)
+ await _settled(transport)
+ await _settled(transport)
+
+ kinds = [type(event) for event in received.events]
+ assert kinds == [InboundMembership]
diff --git a/core/tests/switch_core/transport/test_sync_durability.py b/core/tests/switch_core/transport/test_sync_durability.py
new file mode 100644
index 000000000..bb19bc519
--- /dev/null
+++ b/core/tests/switch_core/transport/test_sync_durability.py
@@ -0,0 +1,85 @@
+"""What counts as a batch worth persisting the cursor for.
+
+The judgement has to live here rather than in the client: only the transport
+sees what a sync response held, and the port hands the client a bool so a nio
+response class never reaches it. The client's side of the bargain — the
+throttle, the staleness flush, the per-client jitter — is covered in
+`tests/switch_core/clients/test_sync_cursor_persistence.py`.
+
+Timeline events, room state and invites are dispatched to handlers, so a
+restart must not skip them. Presence, typing and receipts are not: resuming
+from the older cursor replays the same nothing.
+"""
+
+from __future__ import annotations
+
+import pytest
+from nio import (
+ DeviceList,
+ DeviceOneTimeKeyCount,
+ InviteInfo,
+ RoomInfo,
+ Rooms,
+ SyncResponse,
+ Timeline,
+)
+
+from switch_core.transport.matrix import _carries_durable_events
+
+ROOM = "!room:switch.local"
+
+
+def _sync(
+ next_batch: str = "s1",
+ *,
+ timeline: list[object] | None = None,
+ state: list[object] | None = None,
+ ephemeral: list[object] | None = None,
+ invite: bool = False,
+ to_device: list[object] | None = None,
+) -> SyncResponse:
+ join = {
+ ROOM: RoomInfo(
+ timeline=Timeline(
+ events=list(timeline or []), limited=False, prev_batch=None
+ ),
+ state=list(state or []),
+ ephemeral=list(ephemeral or []),
+ account_data=[],
+ )
+ }
+ return SyncResponse(
+ next_batch=next_batch,
+ rooms=Rooms(
+ invite={ROOM: InviteInfo(invite_state=[])} if invite else {},
+ join=join,
+ leave={},
+ ),
+ device_key_count=DeviceOneTimeKeyCount(curve25519=None, signed_curve25519=None),
+ device_list=DeviceList(changed=[], left=[]),
+ to_device_events=list(to_device or []),
+ presence_events=[],
+ )
+
+
+ "kwargs",
+ [
+ {"timeline": [object()]},
+ {"state": [object()]},
+ {"invite": True},
+ {"to_device": [object()]},
+ ],
+ ids=["timeline", "state", "invite", "to_device"],
+)
+def test_anything_a_restart_would_replay_is_durable(kwargs: dict[str, object]) -> None:
+ assert _carries_durable_events(_sync(**kwargs)) is True # type: ignore[arg-type]
+
+
+def test_an_empty_batch_is_not() -> None:
+ assert _carries_durable_events(_sync()) is False
+
+
+def test_ephemeral_only_is_not() -> None:
+ """Typing notices and read receipts move the token and mean nothing."""
+ assert _carries_durable_events(_sync(ephemeral=[object()])) is False
diff --git a/deploy/local/standalone-docker-compose.yml b/deploy/local/standalone-docker-compose.yml
index 43f1ca0a3..bf1ec8243 100644
--- a/deploy/local/standalone-docker-compose.yml
+++ b/deploy/local/standalone-docker-compose.yml
@@ -10,7 +10,7 @@
# docker compose -f standalone-docker-compose.yml -f standalone-docker-compose.build.yml up
#
# Profiles keep optional services opt-in:
-# (core, no profile) postgres, tuwunel, switch — always started
+# (core, no profile) postgres, tuwunel, backfill, switch — always started
# collab init-db, mattermost, setup — Mattermost bridge + seeder
# gateway gateway — operator dashboard
# Select them with `--profile collab --profile gateway` or COMPOSE_PROFILES.
@@ -142,6 +142,54 @@ services:
init-db:
condition: service_completed_successfully
+ # One-shot: reconstructs each room's history from the homeserver into the
+ # message log, then exits. switch waits for it to finish, so the copy is
+ # never racing the server that will serve it.
+ #
+ # It always exits 0, so a backfill that fails delays the stack rather than
+ # keeping it down. The trade is deliberate and it is a real one: a failure
+ # here is only visible in this service's log, and the stack above it will
+ # look healthy while missing history. Backfill is idempotent, so re-running
+ # it after fixing the cause costs nothing.
+ #
+ # It runs alembic first for ordering, not as a second migration owner: the
+ # rows it writes need the schema, and switch (which normally migrates on
+ # boot) is waiting on this. The upgrade is the same idempotent one.
+ #
+ # Rooms already walked to their start are skipped, so this is cheap on every
+ # boot after the first. Nothing to walk at all is success too — a fresh
+ # stack has no rooms and no admin client.
+ backfill:
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required, set it in .env, there is no default}
+ restart: "no"
+ environment:
+ DB_HOST: postgres
+ DB_PORT: "5432"
+ DB_USER: ${DB_USER}
+ DB_PASSWORD: ${DB_PASSWORD}
+ DB_NAME: ${DB_NAME}
+ MATRIX_SERVER: http://tuwunel:8008
+ MATRIX_SERVER_NAME: localhost
+ MATRIX_ADMIN_USER: ${MATRIX_ADMIN_USER}
+ MATRIX_ADMIN_PASSWORD: ${MATRIX_ADMIN_PASSWORD}
+ MATRIX_REGISTRATION_SHARED_SECRET: ${MATRIX_REGISTRATION_SHARED_SECRET}
+ AGENT_REGISTRATION_TOKEN: ${AGENT_REGISTRATION_TOKEN}
+ JWT_SECRET_KEY: ${JWT_SECRET_KEY}
+ GATEWAY_ADMIN_EMAIL: ${GATEWAY_ADMIN_EMAIL}
+ GATEWAY_ADMIN_PASSWORD: ${GATEWAY_ADMIN_PASSWORD}
+ entrypoint: >
+ sh -c "
+ alembic upgrade head &&
+ python -m switch_core.cli.backfill --allow-empty ||
+ echo 'backfill did not complete; starting anyway. Room history from
+ before this release may be missing until it is re-run.' >&2
+ "
+ depends_on:
+ postgres:
+ condition: service_healthy
+ tuwunel:
+ condition: service_started
+
switch:
image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required, set it in .env, there is no default}
ports:
@@ -168,6 +216,8 @@ services:
condition: service_healthy
tuwunel:
condition: service_started
+ backfill:
+ condition: service_completed_successfully
gateway:
image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:?required, set it in .env, there is no default}
diff --git a/deploy/remote/helm/switch/templates/switch-core/backfill-job.yaml b/deploy/remote/helm/switch/templates/switch-core/backfill-job.yaml
new file mode 100644
index 000000000..8c3015852
--- /dev/null
+++ b/deploy/remote/helm/switch/templates/switch-core/backfill-job.yaml
@@ -0,0 +1,58 @@
+{{- if .Values.switchCore.backfill.enabled }}
+# Reconstructs each room's history from the homeserver into the message log.
+#
+# Off by default and deliberately not part of a normal release: it is a one-off
+# for the move onto the Postgres transport, and as a routine hook it would
+# re-walk every room's entire history on every upgrade.
+#
+# It reads the homeserver, so it can only run while Tuwunel is still deployed —
+# and it is the last thing that needs it. Run it with `dryRun: true` first and
+# read the log before letting it write.
+#
+# Ordered after the migrate hook (weight 10 vs 0): it writes into `messages`,
+# which alembic has to have created.
+apiVersion: batch/v1
+kind: Job
+metadata:
+ name: {{ include "switch.fullname" . }}-backfill
+ labels:
+ {{- include "switch.labels" . | nindent 4 }}
+ {{- include "switch.selectorLabels" (dict "Release" .Release "component" "backfill") | nindent 4 }}
+ annotations:
+ "helm.sh/hook": post-upgrade
+ "helm.sh/hook-weight": "10"
+ "helm.sh/hook-delete-policy": before-hook-creation
+spec:
+ # Backfill is idempotent — a unique transport_event_id and a commit per page,
+ # so a retry resumes rather than duplicates.
+ backoffLimit: 3
+ template:
+ metadata:
+ labels:
+ {{- include "switch.labels" . | nindent 8 }}
+ {{- include "switch.selectorLabels" (dict "Release" .Release "component" "backfill") | nindent 8 }}
+ spec:
+ {{- if .Values.global.imagePullSecrets }}
+ {{- include "switch.imagePullSecrets" . | nindent 6 }}
+ {{- end }}
+ restartPolicy: OnFailure
+ initContainers:
+ {{- include "switch.waitFor" (dict "name" "postgres" "host" (include "switch.postgresHost" .) "port" (include "switch.postgresPort" .)) | nindent 8 }}
+ {{- include "switch.waitFor" (dict "name" "tuwunel" "host" (include "switch.tuwunelHost" .) "port" .Values.tuwunel.service.port) | nindent 8 }}
+ containers:
+ - name: backfill
+ image: {{ include "switch.image" (dict "global" .Values.global "image" .Values.switchCore.image) }}
+ imagePullPolicy: {{ .Values.switchCore.imagePullPolicy }}
+ command:
+ - python
+ - -m
+ - switch_core.cli.backfill
+ {{- if .Values.switchCore.backfill.dryRun }}
+ - --dry-run
+ {{- end }}
+ {{- if .Values.switchCore.backfill.allowEmpty }}
+ - --allow-empty
+ {{- end }}
+ env:
+ {{- include "switch.coreEnv" . | nindent 12 }}
+{{- end }}
diff --git a/deploy/remote/helm/switch/templates/switch-core/reconcile-job.yaml b/deploy/remote/helm/switch/templates/switch-core/reconcile-job.yaml
new file mode 100644
index 000000000..7c8feb5c9
--- /dev/null
+++ b/deploy/remote/helm/switch/templates/switch-core/reconcile-job.yaml
@@ -0,0 +1,43 @@
+{{- if .Values.switchCore.reconcile.enabled }}
+# Compares the recorded messages against what the homeserver holds, and exits
+# non-zero on drift. The check to run after a backfill and before flipping the
+# transport, because afterwards there is only one record and nothing to compare
+# it against.
+#
+# Off by default, for the same reason as the backfill job: this is a step in a
+# migration, not part of a release.
+apiVersion: batch/v1
+kind: Job
+metadata:
+ name: {{ include "switch.fullname" . }}-reconcile
+ labels:
+ {{- include "switch.labels" . | nindent 4 }}
+ {{- include "switch.selectorLabels" (dict "Release" .Release "component" "reconcile") | nindent 4 }}
+ annotations:
+ "helm.sh/hook": post-upgrade
+ "helm.sh/hook-weight": "20"
+ "helm.sh/hook-delete-policy": before-hook-creation
+spec:
+ # Read-only, so a retry costs time and nothing else.
+ backoffLimit: 1
+ template:
+ metadata:
+ labels:
+ {{- include "switch.labels" . | nindent 8 }}
+ {{- include "switch.selectorLabels" (dict "Release" .Release "component" "reconcile") | nindent 8 }}
+ spec:
+ {{- if .Values.global.imagePullSecrets }}
+ {{- include "switch.imagePullSecrets" . | nindent 6 }}
+ {{- end }}
+ restartPolicy: Never
+ initContainers:
+ {{- include "switch.waitFor" (dict "name" "postgres" "host" (include "switch.postgresHost" .) "port" (include "switch.postgresPort" .)) | nindent 8 }}
+ {{- include "switch.waitFor" (dict "name" "tuwunel" "host" (include "switch.tuwunelHost" .) "port" .Values.tuwunel.service.port) | nindent 8 }}
+ containers:
+ - name: reconcile
+ image: {{ include "switch.image" (dict "global" .Values.global "image" .Values.switchCore.image) }}
+ imagePullPolicy: {{ .Values.switchCore.imagePullPolicy }}
+ command: ["python", "-m", "switch_core.cli.reconcile", "--verbose"]
+ env:
+ {{- include "switch.coreEnv" . | nindent 12 }}
+{{- end }}
diff --git a/deploy/remote/helm/switch/values.yaml b/deploy/remote/helm/switch/values.yaml
index 7a813469a..518fce663 100644
--- a/deploy/remote/helm/switch/values.yaml
+++ b/deploy/remote/helm/switch/values.yaml
@@ -208,6 +208,26 @@ switchCore:
# idempotent. Disable only if you run migrations out-of-band.
migrations:
preUpgradeJob: true
+ # One-off migration steps for the move onto the Postgres message store. Both
+ # read the homeserver, so they only work while Tuwunel is still deployed, and
+ # both are off by default: they belong to one release, not to every release.
+ #
+ # 1. enable backfill with dryRun: true, upgrade, read the Job's log
+ # 2. set dryRun: false, upgrade again
+ # 3. enable reconcile, upgrade, confirm it exits clean
+ # 4. set MESSAGE_TRANSPORT=postgres
+ # 5. turn both back off
+ #
+ # Backfill is idempotent and its rows are numbered below the live sequence,
+ # so it can be re-run and nobody is redelivered old history.
+ backfill:
+ enabled: false
+ dryRun: true
+ # Exit 0 when there is no history to walk. For an install with no rooms
+ # yet, where a failed Job would be reporting an empty database as a fault.
+ allowEmpty: false
+ reconcile:
+ enabled: false
resources:
requests:
memory: "512Mi"
diff --git a/justfile b/justfile
index 9b3f537f3..2fa7cf126 100644
--- a/justfile
+++ b/justfile
@@ -101,6 +101,24 @@ migrate:
uv run --project core alembic -c core/alembic.ini upgrade head
+# ── Check the recorded messages against the message bus ───────────────────────
+# Messages are written to Postgres after the send is accepted, so a database
+# problem leaves a row missing for a message that was really delivered. This
+# walks each room's history and reports the difference. Exits non-zero on drift.
+# Needs a real deployment — the question it answers cannot be asked of fakes.
+# just reconcile-messages --room <id> --since <iso8601> --verbose
+reconcile-messages *args:
+ uv run --project core python -m switch_core.cli.reconcile {{ args }}
+
+# ── Reconstruct room history from the bus into the message log ────────────────
+# Rows exist only from when the recorder was deployed; everything older is on
+# the homeserver and invisible to agents now that reads come from Postgres.
+# This walks each room to its start and writes what is missing, numbered below
+# the live log so nothing is redelivered. Safe to re-run. Start with --dry-run.
+# just backfill-messages --dry-run --room <id>
+backfill-messages *args:
+ uv run --project core python -m switch_core.cli.backfill {{ args }}
+
# ── Generate a new alembic migration ──────────────────────────────────────────
migration msg:
uv run --project core alembic -c core/alembic.ini revision --autogenerate -m "{{ msg }}"