Skip to content

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

Store a message's own events together, in two statements (CHOO-3667)

Abel Dantas82689311550e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f38bdf630..51277ff92 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -233,6 +233,10 @@ version of their own to them without also giving them a release of their own.
seven.** The rooms dropped after the agent's cursor are read with its
events, and the unread count reads the agent's baseline, the room's window
and the agent's user id in the statement that counts.
+- **Writing a message no longer costs four statements for each agent it is
+ for.** The agents' own events are stored together, in two statements and
+ one savepoint, where each agent's event took a savepoint, a numbering, an
+ insert and a release of its own.
#### Fixed
- **The agent HTTP API answers a refused or malformed request with a 4xx, not
diff --git a/core/switch_core/bridges/agent/protocol/event_buffer.py b/core/switch_core/bridges/agent/protocol/event_buffer.py
index 8d11f3b17..37022d980 100644
--- a/core/switch_core/bridges/agent/protocol/event_buffer.py
+++ b/core/switch_core/bridges/agent/protocol/event_buffer.py
@@ -50,6 +50,7 @@ baseline (`caught_up_seq`) and the reader currently in the room are stored in
from __future__ import annotations
import asyncio
+import json
import logging
import time
from collections.abc import AsyncIterator, Iterable
@@ -198,6 +199,17 @@ COUNTED_FROM_WINDOW = (
)
+@dataclass(frozen=True)
+class OwnEventToStore:
+ """One agent's own event for `EventBuffer.store_together`."""
+
+ agent_id: str
+ client_id: str
+ event: AgentEvent
+ room_seq: int
+ message_key: str | None
+
+
class CursorExpiredError(Exception):
"""A reader asked to resume from an own event number older than the oldest own event kept.
@@ -401,6 +413,69 @@ _UNREAD_IN_ROOM_SQL = text(
).bindparams(bindparam("throughs", type_=ARRAY(BigInteger)))
+# Locks the rows in `agent_event_heads` of the agents named by `:agent_ids`
+# (in that order, which callers keep sorted, as `store` asks), giving each
+# agent with no row one numbered from `:floor`, and returns each agent's head.
+# An agent deleted meanwhile is not in `agents`, so it gets no row and is not
+# returned. Updating a row to itself is what takes its lock.
+_LOCK_HEADS_SQL = text(
+ """
+ INSERT INTO agent_event_heads (tenant_id, agent_id, first_seq, last_seq)
+ SELECT a.tenant_id, a.id, CAST(:floor AS bigint), CAST(:floor AS bigint) - 1
+ FROM agents a
+ JOIN unnest(CAST(:agent_ids AS text[])) WITH ORDINALITY AS t(agent_id, n)
+ ON t.agent_id = a.id
+ ORDER BY t.n
+ ON CONFLICT (agent_id) DO UPDATE SET last_seq = agent_event_heads.last_seq
+ RETURNING agent_id, last_seq
+ """
+)
+
+# Inserts one own event per agent, numbered `:seqs` (each the agent's head
+# plus one, read under the lock `_LOCK_HEADS_SQL` took), for each agent that is
+# still a member of the room and has no event from the same source yet
+# (`uq_agent_events_source`), and moves each agent whose event went in to its
+# number. An agent whose event did not go in keeps its head, so no number is
+# taken and left unused. Returns the agents stored and their numbers.
+_STORE_OWN_EVENTS_SQL = text(
+ """
+ WITH wanted AS (
+ SELECT * FROM unnest(
+ CAST(:agent_ids AS text[]),
+ CAST(:client_ids AS text[]),
+ CAST(:seqs AS bigint[]),
+ CAST(:room_seqs AS bigint[]),
+ CAST(:message_keys AS text[]),
+ CAST(:types AS text[]),
+ CAST(:payloads AS text[]),
+ CAST(:notifiables AS boolean[])
+ ) AS w(agent_id, client_id, seq, room_seq, message_key, type, payload,
+ notifiable)
+ ),
+ stored AS (
+ INSERT INTO agent_events (tenant_id, agent_id, seq, room_id, room_seq,
+ message_key, type, payload, notifiable)
+ SELECT :tenant_id, w.agent_id, w.seq, :room_id, w.room_seq, w.message_key,
+ w.type, CAST(w.payload AS jsonb), w.notifiable
+ FROM wanted w
+ WHERE EXISTS (
+ SELECT 1 FROM client_rooms m
+ WHERE m.client_id = w.client_id AND m.room_id = :room_id
+ )
+ ON CONFLICT (agent_id, message_key, room_id, room_seq, type)
+ WHERE message_key IS NOT NULL DO NOTHING
+ RETURNING agent_id, seq
+ ),
+ moved AS (
+ UPDATE agent_event_heads h SET last_seq = s.seq
+ FROM stored s WHERE h.agent_id = s.agent_id
+ RETURNING h.agent_id
+ )
+ SELECT agent_id, seq FROM stored
+ """
+)
+
+
def session_slots_for(pool_size: int, max_overflow: int) -> int:
"""How many `EventBuffer.one_session` blocks may hold a connection at once:
half the pool, so requests still find one when the pod is saturated."""
@@ -558,6 +633,84 @@ class EventBuffer:
await savepoint.commit()
return int(seq)
+ async def store_together(
+ self,
+ session: AsyncSession,
+ *,
+ tenant_id: str,
+ room_id: str,
+ events: list[OwnEventToStore],
+ ) -> dict[str, int] | None:
+ """`store` for several agents' own events from one room row, in two
+ statements rather than four per agent: one locks the agents' rows in
+ `agent_event_heads`, and one inserts each event and moves its agent's
+ head to it. Returns each stored event's number by agent, or None when
+ the statements failed, with nothing stored and the caller's
+ transaction usable, for the caller to store the events one at a time.
+
+ `events` must be in the order of their agents' ids, one per agent, as
+ `store` asks of a caller storing several. What `store` promises holds
+ for each: membership is read after the agent's row is locked, an event
+ from a source already stored is not stored again, and an event not
+ stored takes no number. The work runs in one savepoint, and a failure
+ in it costs every agent of the row its event until the caller stores
+ them one at a time, so that one agent's failure stays that agent's.
+ """
+ if not events:
+ return {}
+ savepoint = await session.begin_nested()
+ try:
+ heads: dict[str, int] = dict(
+ (
+ await session.execute(
+ _LOCK_HEADS_SQL,
+ {
+ "agent_ids": [own.agent_id for own in events],
+ "floor": self.sequence_floor,
+ },
+ )
+ )
+ .tuples()
+ .all()
+ )
+ wanted = [own for own in events if own.agent_id in heads]
+ stored: dict[str, int] = dict(
+ (
+ await session.execute(
+ _STORE_OWN_EVENTS_SQL,
+ {
+ "tenant_id": tenant_id,
+ "room_id": room_id,
+ "agent_ids": [own.agent_id for own in wanted],
+ "client_ids": [own.client_id for own in wanted],
+ "seqs": [heads[own.agent_id] + 1 for own in wanted],
+ "room_seqs": [own.room_seq for own in wanted],
+ "message_keys": [own.message_key for own in wanted],
+ "types": [own.event.type for own in wanted],
+ "payloads": [
+ json.dumps(own.event.model_dump(mode="json"))
+ for own in wanted
+ ],
+ "notifiables": [is_notifiable(own.event) for own in wanted],
+ },
+ )
+ )
+ .tuples()
+ .all()
+ )
+ except Exception:
+ await savepoint.rollback()
+ logger.warning(
+ "[EVENT-BUF] storing %d own event(s) together in room %s failed; "
+ "storing them one at a time",
+ len(events),
+ room_id,
+ exc_info=True,
+ )
+ return None
+ await savepoint.commit()
+ return {agent_id: int(seq) for agent_id, seq in stored.items()}
+
def _claim(self, tenant_id: str, agent_id: str) -> Any:
"""The next number of the agent's own events, taken from its row in
`agent_event_heads`, which the statement locks until the transaction
diff --git a/core/switch_core/delivery/router.py b/core/switch_core/delivery/router.py
index 518a1c146..cc33ad81d 100644
--- a/core/switch_core/delivery/router.py
+++ b/core/switch_core/delivery/router.py
@@ -71,6 +71,7 @@ from sqlalchemy.dialects.postgresql import insert
from sqlalchemy.exc import DBAPIError
from switch_core.attachments import ATTACHMENT_GROUP_KEY, parse_attachment_group
+from switch_core.bridges.agent.protocol.event_buffer import OwnEventToStore
from switch_core.budgets import BudgetGuard
from switch_core.clients.actor import AgentActor, ClientConfig
from switch_core.clients.admin_messages import PLATFORM_MARKER
@@ -1335,16 +1336,51 @@ class MessageRouter:
) -> list[tuple[str, int]]:
"""Store every own event decided for `row`, in the order of the
agents' ids, and return the agents whose events were stored, each with
- its event's number."""
- stored: list[tuple[str, int]] = []
+ its event's number.
+
+ Stored together, in two statements whatever the number of agents
+ (`EventBuffer.store_together`). If that fails they are stored one at
+ a time, each in a savepoint of its own, so that one agent's failure
+ costs that agent its event and nothing more."""
+ built: list[tuple[AgentRecipient, OwnEventToStore]] = []
for recipient, delivery in sorted(
deliveries, key=lambda decided: decided[0].agent.id
):
if delivery.own_event is None:
continue
- agent_id = recipient.agent.id
try:
- own = delivery.own_event(row)
+ decided = delivery.own_event(row)
+ except Exception:
+ self._store_failed(recipient, row, reads)
+ continue
+ built.append(
+ (
+ recipient,
+ OwnEventToStore(
+ agent_id=recipient.agent.id,
+ client_id=recipient.client_id,
+ event=decided.event,
+ room_seq=decided.room_seq,
+ message_key=decided.message_key,
+ ),
+ )
+ )
+ together = await self.services.event_buffer.store_together(
+ session,
+ tenant_id=reads.tenant_id,
+ room_id=reads.room_id,
+ events=[own for _, own in built],
+ )
+ if together is not None:
+ return [
+ (own.agent_id, together[own.agent_id])
+ for _, own in built
+ if own.agent_id in together
+ ]
+ stored: list[tuple[str, int]] = []
+ for recipient, own in built:
+ agent_id = own.agent_id
+ try:
seq = await self.services.event_buffer.store(
session,
tenant_id=reads.tenant_id,
@@ -1356,20 +1392,26 @@ class MessageRouter:
message_key=own.message_key,
)
except Exception:
- metrics().increment(ROUTING_FAILURES, {"stage": "store"})
- logger.error(
- "Could not store agent %s's own event for row %s in room %s; "
- "the row is written and the agent misses it",
- recipient.agent.name,
- row.event_id,
- reads.room_id,
- exc_info=True,
- )
+ self._store_failed(recipient, row, reads)
continue
if seq is not None:
stored.append((agent_id, seq))
return stored
+ @staticmethod
+ def _store_failed(
+ recipient: AgentRecipient, row: InboundEvent, reads: RoomReads
+ ) -> None:
+ metrics().increment(ROUTING_FAILURES, {"stage": "store"})
+ logger.error(
+ "Could not store agent %s's own event for row %s in room %s; "
+ "the row is written and the agent misses it",
+ recipient.agent.name,
+ row.event_id,
+ reads.room_id,
+ exc_info=True,
+ )
+
async def _step_group(
self, session: AsyncSession, reads: RoomReads, plan: _Plan, row: InboundEvent
) -> float | None:
diff --git a/core/tests/switch_core/bridges/agent/protocol/test_store_together.py b/core/tests/switch_core/bridges/agent/protocol/test_store_together.py
new file mode 100644
index 000000000..888eae4df
--- /dev/null
+++ b/core/tests/switch_core/bridges/agent/protocol/test_store_together.py
@@ -0,0 +1,167 @@
+"""Several agents' own events from one room row, stored together
+(`EventBuffer.store_together`): numbered from each agent's head, never taking
+a number for an event that is not stored, so each agent's numbers stay
+contiguous."""
+
+from __future__ import annotations
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.bridges.agent.protocol.event_buffer import (
+ EventBuffer,
+ OwnEventToStore,
+)
+from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload
+from switch_core.db.models import TENANT_ZERO_ID, AgentEventHead, ClientRoom, Room
+from switch_core.db.session_scope import tenant_session
+from tests.routing import add_member, make_agent, make_room, own_events, process_on
+
+
+def _own(agent_id: str, client_id: str, room: Room, key: str) -> OwnEventToStore:
+ return OwnEventToStore(
+ agent_id=agent_id,
+ client_id=client_id,
+ event=AgentEvent(
+ type="message",
+ room_id=room.id,
+ payload=MessagePayload(
+ addressed=True,
+ sender="@ada:test",
+ sender_name="Ada",
+ message_id=key,
+ body="@you",
+ timestamp=0,
+ ),
+ ),
+ room_seq=1,
+ message_key=key,
+ )
+
+
+async def _store(
+ buffer: EventBuffer,
+ session_factory: async_sessionmaker[AsyncSession],
+ room: Room,
+ events: list[OwnEventToStore],
+) -> dict[str, int] | None:
+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:
+ stored = await buffer.store_together(
+ session, tenant_id=TENANT_ZERO_ID, room_id=room.id, events=events
+ )
+ await session.commit()
+ return stored
+
+
+async def _head(
+ session_factory: async_sessionmaker[AsyncSession], agent_id: str
+) -> int:
+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:
+ head = await session.scalar(
+ select(AgentEventHead.last_seq).where(AgentEventHead.agent_id == agent_id)
+ )
+ assert head is not None
+ return head
+
+
+async def test_events_are_numbered_from_each_agents_head(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ buffer = process_on(session_factory).buffer
+ room = await make_room(session_factory)
+ first, first_client = await make_agent(session_factory, "first")
+ second, second_client = await make_agent(session_factory, "second")
+ for client, agent in ((first_client, first), (second_client, second)):
+ await add_member(session_factory, room, client, agent=agent)
+ await _store(
+ buffer, session_factory, room, [_own(first.id, first_client.id, room, "$a")]
+ )
+
+ stored = await _store(
+ buffer,
+ session_factory,
+ room,
+ sorted(
+ [
+ _own(first.id, first_client.id, room, "$b"),
+ _own(second.id, second_client.id, room, "$b"),
+ ],
+ key=lambda own: own.agent_id,
+ ),
+ )
+
+ assert stored == {
+ first.id: buffer.sequence_floor + 1,
+ second.id: buffer.sequence_floor,
+ }
+ assert await _head(session_factory, first.id) == buffer.sequence_floor + 1
+ assert await _head(session_factory, second.id) == buffer.sequence_floor
+ assert [e.seq for e in await own_events(session_factory, first.id)] == [
+ buffer.sequence_floor,
+ buffer.sequence_floor + 1,
+ ]
+
+
+async def test_an_agent_out_of_the_room_takes_no_number(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ """Membership is read after the agent's head is locked, and an event not
+ stored leaves the head where it was."""
+ buffer = process_on(session_factory).buffer
+ room = await make_room(session_factory)
+ agent, client = await make_agent(session_factory, "leaver")
+ await add_member(session_factory, room, client, agent=agent)
+ await _store(buffer, session_factory, room, [_own(agent.id, client.id, room, "$a")])
+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:
+ await session.execute(
+ delete(ClientRoom).where(ClientRoom.client_id == client.id)
+ )
+ await session.commit()
+
+ stored = await _store(
+ buffer, session_factory, room, [_own(agent.id, client.id, room, "$b")]
+ )
+
+ assert stored == {}
+ assert await _head(session_factory, agent.id) == buffer.sequence_floor
+
+
+async def test_an_event_already_stored_is_not_stored_again(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ """The same source twice, as an older process's consumer deciding the
+ same row would write it: the second takes no number."""
+ buffer = process_on(session_factory).buffer
+ room = await make_room(session_factory)
+ agent, client = await make_agent(session_factory, "twice")
+ await add_member(session_factory, room, client, agent=agent)
+ own = _own(agent.id, client.id, room, "$same")
+ await _store(buffer, session_factory, room, [own])
+
+ stored = await _store(buffer, session_factory, room, [own])
+
+ assert stored == {}
+ assert [e.seq for e in await own_events(session_factory, agent.id)] == [
+ buffer.sequence_floor
+ ]
+ assert await _head(session_factory, agent.id) == buffer.sequence_floor
+
+
+async def test_an_agent_with_no_head_yet_starts_at_the_floor(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ buffer = process_on(session_factory).buffer
+ room = await make_room(session_factory)
+ agent, client = await make_agent(session_factory, "new")
+ await add_member(session_factory, room, client, agent=agent)
+
+ stored = await _store(
+ buffer, session_factory, room, [_own(agent.id, client.id, room, "$a")]
+ )
+
+ assert stored == {agent.id: buffer.sequence_floor}
+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:
+ first = await session.scalar(
+ select(AgentEventHead.first_seq).where(AgentEventHead.agent_id == agent.id)
+ )
+ assert first == buffer.sequence_floor
diff --git a/core/tests/switch_core/delivery/test_router.py b/core/tests/switch_core/delivery/test_router.py
index e58de81ba..3eb572899 100644
--- a/core/tests/switch_core/delivery/test_router.py
+++ b/core/tests/switch_core/delivery/test_router.py
@@ -32,6 +32,7 @@ from sqlalchemy.exc import DBAPIError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.pool import NullPool
+from switch_core.bridges.agent.protocol import event_buffer
from switch_core.bridges.agent.protocol.agent_connections import (
PROTOCOL_VERSION,
ClientDeclaration,
@@ -428,6 +429,9 @@ class TestFailuresStayWithTheAgent:
return text("SELECT 1 / 0")
return claim(self, tenant_id, agent_id)
+ # The agents' events are stored together first, and when that fails,
+ # one at a time, each in a savepoint of its own.
+ monkeypatch.setattr(event_buffer, "_STORE_OWN_EVENTS_SQL", text("SELECT 1 / 0"))
monkeypatch.setattr(EventBuffer, "_claim", failing_claim)
registry = MetricsRegistry()
install(registry)
@@ -577,6 +581,18 @@ class TestCost:
await process.idle()
return process, room, alice, names
+ @staticmethod
+ async def _events_in(session_factory: SessionFactory, room: Room) -> int:
+ """How many own events, of any agent, were stored for the room."""
+ async with tenant_session(session_factory, room.tenant_id) as session:
+ return int(
+ await session.scalar(
+ text("SELECT count(*) FROM agent_events WHERE room_id = :room"),
+ {"room": room.id},
+ )
+ or 0
+ )
+
@staticmethod
def _kinds(statements: list[str]) -> dict[str, int]:
kinds: dict[str, int] = {}
@@ -648,11 +664,14 @@ class TestCost:
heard = 1 if agents == 1 else 0
assert after == [b + heard for b in before]
- async def test_writes_grow_with_the_agents_a_message_is_for(
+ async def test_writes_do_not_grow_with_the_agents_a_message_is_for(
self, session_factory: SessionFactory, statement_counts: StatementCounts
) -> None:
"""Naming every agent in the room: the reads are what they are for a
- room of one, and each agent named costs its own event's writes."""
+ room of one, and so are the writes. The agents' events are stored
+ together (`EventBuffer.store_together`): one statement locks their
+ rows in `agent_event_heads`, and one inserts their events and moves
+ their heads, in one savepoint."""
counted = []
for size in (1, 6):
process, room, alice, names = await self._room_of(session_factory, size)
@@ -661,17 +680,15 @@ class TestCost:
await process.say(room, body, sender=alice)
await process.idle()
counted.append(self._kinds(scope.statements))
+ assert await self._events_in(session_factory, room) == size
small, large = counted
- assert small.get("SELECT") == large.get("SELECT"), (small, large)
- # One message, then per agent named: its number and its event, each
- # in a savepoint of its own.
- per_agent = {
- kind: (large.get(kind, 0) - small.get(kind, 0)) // 5
- for kind in ("INSERT", "SAVEPOINT", "RELEASE")
- }
- assert per_agent == {"INSERT": 2, "SAVEPOINT": 1, "RELEASE": 1}, (small, large)
- assert large.get("INSERT", 0) == 1 + 2 * 6
+ assert small == large, (small, large)
+ assert (large.get("SAVEPOINT"), large.get("RELEASE")) == (1, 1), large
+ # The message, and the lock on the agents' heads.
+ assert large.get("INSERT") == 2, large
+ # Their events, and their heads moved.
+ assert large.get("WITH") == 1, large
def _message(room: Room, sender: Client, body: str) -> Message: