Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
fix(agent-bridge): page room history instead of reading one page (CHOO-2034)
amaudruz02cacee6cd3d
diff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.pyindex 1ba318e3e..233061b81 100644--- a/core/switch_core/bridges/agent/api/handlers.py+++ b/core/switch_core/bridges/agent/api/handlers.py@@ -979,7 +979,7 @@ async def get_room_history(before_ms = parse_timestamp_ms(before) if before else Nonetry:- raw_messages = await protocol.read_context(+ context = await protocol.read_context(agent.id,room_id,limit=limit,@@ -992,19 +992,23 @@ async def get_room_history(raise HTTPException(status_code=403, detail=str(e)) from emessages: list[HistoryMessage] = []- for msg_dict in raw_messages:- sender = msg_dict.get("sender")- sender_name = msg_dict.get("sender_name") or sender- body = msg_dict.get("body")- ts = msg_dict.get("timestamp")- if body:+ for group in context["threads"]:+ for entry in [group["root"], *group["replies"]]:+ body = entry.get("body")+ if not body:+ continue+ sender = entry.get("sender")messages.append(HistoryMessage(- sender=sender, sender_name=sender_name, body=body, timestamp=ts+ sender=sender,+ sender_name=entry.get("sender_name") or sender,+ body=body,+ timestamp=entry.get("timestamp"),))+ messages.sort(key=lambda m: m.timestamp or 0)- return HistoryResponse(events=messages, has_more=len(messages) >= limit)+ return HistoryResponse(events=messages, has_more=context["truncated"])# Participants endpointdiff --git a/core/switch_core/bridges/agent/operations/definitions.py b/core/switch_core/bridges/agent/operations/definitions.pyindex be13f3aba..389a3bbf9 100644--- a/core/switch_core/bridges/agent/operations/definitions.py+++ b/core/switch_core/bridges/agent/operations/definitions.py@@ -547,19 +547,34 @@ async def read_context(limit: int = 50,since: str | None = None,before: str | None = None,-) -> list[dict[str, Any]]:+) -> dict[str, Any]:"""Get the conversation timeline for the connected room, grouped into threads.- Returns a list of thread groups ordered by latest activity (most-recently- active LAST, so the tail is the freshest), each shaped as::+ Returns::++ {"threads": [...], "truncated": bool, "oldest_timestamp": int|None}++ `threads` is a list of thread groups ordered by latest activity (most-+ recently active LAST, so the tail is the freshest), each shaped as::++ {"root": <entry>, "replies": [<entry>, ...]}++ where <entry> is {"id", "kind", "sender", "sender_name", "body",+ "timestamp", "attachments"}. Top-level entries are roots with an empty+ `replies` list; replies are oldest-first within a thread. Use a root's (or+ any entry's) `id` as the `thread_id` argument to post_message /+ send_targeted_message to reply into that thread.- {"root": <message>, "replies": [<message>, ...]}+ `kind` is "message" for something a participant said, or "room_join" for+ someone arriving in the room (body reads "<name> joined the room"). Joins+ are part of the timeline so the history explains who appeared and when.- where <message> is {"id", "sender", "sender_name", "body", "timestamp",- "attachments"}. Top-level messages are roots with an empty `replies` list;- replies are oldest-first within a thread. Use a root's (or any message's)- `id` as the `thread_id` argument to post_message / send_targeted_message to- reply into that thread.+ **`truncated` matters.** It is True when older history exists that this+ call did not reach — you are looking at a partial conversation. Widen+ `limit`, or page backwards with `before` set to `oldest_timestamp`, before+ concluding you have the full picture. It is deliberately conservative: a+ read that ends exactly on `limit` reports truncated even if nothing older+ exists.`attachments` is a (usually empty) list of files on the message, each{"filename", "mimetype", "size", "mxc", "msgtype"}. Any file type can@@ -568,15 +583,17 @@ async def read_context(you can read.Args:- limit: Maximum number of messages to scan (default 50), grouped into- threads before returning.+ limit: Maximum number of timeline entries to return (default 50),+ grouped into threads. History is paged from the homeserver until+ this many are collected or the room's start is reached.since: ISO-8601 timestamp string (e.g. "2026-05-20T20:55:00Z"). Only- messages at or after this time are returned. Use this when an event+ entries at or after this time are returned. Use this when an eventarrives to fetch just the recent context — pass a timestamp a fewminutes before the event ts. None = no lower bound.- before: ISO-8601 timestamp string. Only messages strictly before this- time are returned. Combine with `since` to page through history.- None = no upper bound.+ before: ISO-8601 timestamp string. Only entries strictly before this+ time are returned; history is paged backwards to reach them, so+ this genuinely walks into older history. Combine with `since` to+ page through a window. None = no upper bound.The room is implicit (the session's currently connected room). Readsfail if you have not called connect_to_room first.diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.pyindex a683c29c9..326f938d0 100644--- a/core/switch_core/bridges/agent/protocol/service.py+++ b/core/switch_core/bridges/agent/protocol/service.py@@ -12,6 +12,7 @@ from typing import TYPE_CHECKING, Anyfrom nio import (DownloadError,RoomGetEventError,+ RoomMemberEvent,RoomMessageMedia,RoomMessagesError,)@@ -106,6 +107,14 @@ logger = logging.getLogger(__name__)_VALID_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9._-]*$")+# 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+class AgentExistsError(Exception):"""Raised when registering an agent whose name is already taken and the@@ -1242,6 +1251,7 @@ class ProtocolService:return {"id": event.event_id,+ "kind": "message","sender": event.sender,"sender_name": sender_name,"body": body,@@ -1249,6 +1259,40 @@ class ProtocolService:"attachments": attachments,}+ @staticmethod+ def _join_dict(event: RoomMemberEvent) -> dict[str, Any] | None:+ """Build a timeline entry for someone joining the room.++ 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.+ """+ if event.membership != "join" or event.prev_membership == "join":+ return None+ content = event.content or {}+ name = content.get("displayname") or event.state_key+ return {+ "id": event.event_id,+ "kind": "room_join",+ "sender": event.state_key,+ "sender_name": name,+ "body": f"{name} joined the room",+ "timestamp": getattr(event, "server_timestamp", None),+ "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+@staticmethoddef _thread_root_id(event: Any) -> str:"""Return the thread root id for an event.@@ -1271,20 +1315,31 @@ class ProtocolService:limit: int = 50,since_ms: int | None = None,before_ms: int | None = None,- ) -> list[dict[str, Any]]:+ ) -> dict[str, Any]:"""Fetch room history grouped into threads.- Returns thread groups ordered by latest activity (most-recently-active- last, so the tail is the freshest), each shaped as::+ Returns::++ {"threads": [...], "truncated": bool, "oldest_timestamp": int|None}- {"root": <message>, "replies": [<message>, ...]}+ where each thread group is ordered by latest activity (most-recently-+ active last, so the tail is the freshest) and shaped as::- where <message> is {"id", "sender", "sender_name", "body", "timestamp"}.- Top-level messages 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.+ {"root": <entry>, "replies": [<entry>, ...]}++ An <entry> is {"id", "kind", "sender", "sender_name", "body",+ "timestamp", "attachments"}. `kind` is "message" for something someone+ 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.++ `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."""room = await self.require_room_member(agent_id, room_id)client = self.client_lifecycle.get_by_agent_id(agent_id)@@ -1293,42 +1348,67 @@ class ProtocolService:if client.nio_client is None:raise ValueError("Agent client not connected to Matrix")- resp = await client.nio_client.room_messages(- room.matrix_room_id, start="", limit=limit * 5- )-- if isinstance(resp, RoomMessagesError):- raise ValueError(f"Failed to fetch room history: {resp.message}")-- # resp.chunk is newest-first. Collect up to `limit` messages within the- # window, then group them by thread root.+ # 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.groups: dict[str, dict[str, Any]] = {}- seen = 0- for event in resp.chunk:- body = getattr(event, "body", None)- if not body:- continue- ts = getattr(event, "server_timestamp", None)- if since_ms is not None and ts is not None and ts < since_ms:- continue- if before_ms is not None and ts is not None and ts >= before_ms:- continue+ collected = 0+ oldest_ts: int | None = None+ start: str | None = None+ pages = 0+ exhausted = False++ while collected < limit and pages < HISTORY_MAX_PAGES:+ 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}")+ pages += 1++ chunk = list(resp.chunk)+ end = getattr(resp, "end", None)++ 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- root_id = self._thread_root_id(event)- msg = self._message_dict(event)- group = groups.setdefault(- root_id, {"root": None, "replies": [], "latest": 0}- )- if msg["id"] == root_id:- group["root"] = msg- else:- group["replies"].append(msg)- if ts is not None and ts > group["latest"]:- group["latest"] = ts+ entry = self._timeline_entry(event)+ if entry is None:+ continue++ 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- seen += 1- if seen >= limit:+ 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# Resolve roots that fall outside the fetched window (orphan replies).for root_id, group in groups.items():@@ -1338,11 +1418,25 @@ class ProtocolService:)ordered = sorted(groups.values(), key=lambda g: g["latest"])- result: list[dict[str, Any]] = []+ threads: list[dict[str, Any]] = []for group in ordered:group["replies"].reverse() # chunk was newest-first → oldest-first- result.append({"root": group["root"], "replies": group["replies"]})- return result+ threads.append({"root": group["root"], "replies": group["replies"]})++ if not exhausted:+ logger.warning(+ "read_context truncated in %s: %d entries over %d pages, "+ "older history not reached",+ room.matrix_room_id,+ collected,+ pages,+ )++ return {+ "threads": threads,+ "truncated": not exhausted,+ "oldest_timestamp": oldest_ts,+ }async def _fetch_root(self, client: ClientBase[Any], matrix_room_id: str, root_id: str@@ -1363,6 +1457,7 @@ class ProtocolService:)return {"id": root_id,+ "kind": "message","sender": None,"sender_name": None,"body": None,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.pyindex d868b5f33..07a1575a4 100644--- 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@@ -40,8 +40,9 @@ def _text_event() -> nio.RoomMessageText:def _build_service(chunk: list[object]) -> ProtocolService:- async def _room_messages(matrix_room_id: str, start: str, limit: int):- return SimpleNamespace(chunk=chunk)+ 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)@@ -65,7 +66,7 @@ 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")+ groups = (await svc.read_context("agent-1", "room-1"))["threads"]assert len(groups) == 1root = groups[0]["root"]@@ -84,7 +85,7 @@ async def test_image_event_carries_attachment() -> None:async def test_text_event_has_empty_attachments() -> None:svc = _build_service([_text_event()])- groups = await svc.read_context("agent-1", "room-1")+ groups = (await svc.read_context("agent-1", "room-1"))["threads"]assert len(groups) == 1root = groups[0]["root"]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.pynew file mode 100644index 000000000..37eb2cb89--- /dev/null+++ b/core/tests/switch_core/bridges/agent/protocol/test_read_context_pagination.py@@ -0,0 +1,205 @@+"""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.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."""++ def __init__(self, pages: list[list[Any]]) -> None:+ self._pages = pages+ 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 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_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.pyindex 048cd92f8..f5ebef013 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_threads.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_threads.py@@ -42,9 +42,9 @@ class _FakeNio:self._events = events or {}async def room_messages(- self, room_id: str, start: str = "", limit: int = 0+ self, room_id: str, start: str | None = None, limit: int = 0) -> SimpleNamespace:- return SimpleNamespace(chunk=self._chunk)+ 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)@@ -108,7 +108,7 @@ class TestReadContextThreads:]svc = _service_with_client(_FakeNio(chunk=chunk))- result = await svc.read_context("agent", "room")+ 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"]@@ -122,7 +122,7 @@ class TestReadContextThreads:events = {"e1": _ev("e1", "old root", 100)}svc = _service_with_client(_FakeNio(chunk=chunk, events=events))- result = await svc.read_context("agent", "room")+ result = (await svc.read_context("agent", "room"))["threads"]assert len(result) == 1assert result[0]["root"]["id"] == "e1"@@ -134,7 +134,7 @@ class TestReadContextThreads:chunk = [_ev("e9", "reply", 200, thread_root="e1")]svc = _service_with_client(_FakeNio(chunk=chunk, events={}))- result = await svc.read_context("agent", "room")+ result = (await svc.read_context("agent", "room"))["threads"]assert len(result) == 1assert result[0]["root"]["id"] == "e1"