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
Read agent events from Postgres, instead of reading from the in-memory buffer (#815)
Abel Dantasa68b768c692e
diff --git a/artifacts.yaml b/artifacts.yamlindex 9a7e0e86d..daeb81848 100644--- a/artifacts.yaml+++ b/artifacts.yaml@@ -218,9 +218,21 @@ contracts:# stream and its beat against a server with no socket. Both go, and# `accepts` rises to 8, once `switch.agents.connected{transport:sse}` stays# at zero.+ #+ # Revision 9 makes the resume point a position: one number per source, the+ # agent's own events (`s`) and each room's conversation (`r:<room>`), so a+ # stream can read the conversation from the rooms themselves instead of a+ # copy per agent. A client that declares it opens with `start_at` (a JSON+ # position, or "head"), reads `position` (the event's source and number)+ # off each delivered event, reports its position on every heartbeat+ # (`position` beside `cursor`), and gets `resumed_position` on a gap. The+ # integer fields stay, so a client that knows only them is served as+ # before: a stream that reads only the agent's own events is one number+ # already, and one that reads the conversation too is handed tickets that+ # stand for its position. Additive, so `accepts` stays at 1.artifacts:- switch-core: { speaks: 8, accepts: 1 }- agent-runtime: { speaks: 8, accepts: 1 }+ switch-core: { speaks: 9, accepts: 1 }+ agent-runtime: { speaks: 9, accepts: 1 }gateway-api:description: >-diff --git a/console/packages/shared/src/artifacts.ts b/console/packages/shared/src/artifacts.tsindex 0e8d163bf..0a0d1bbeb 100644--- a/console/packages/shared/src/artifacts.ts+++ b/console/packages/shared/src/artifacts.ts@@ -42,8 +42,8 @@ export function artifactVersion(artifact: ArtifactName): string {export const CONTRACTS = {// The wire protocol between switch-core's agent bridge and an agent runtime: the event stream, its frame shapes, the resume cursor, and the tool-call channel.'agent-protocol': {- 'switch-core': { speaks: 8, accepts: 1 },- 'agent-runtime': { speaks: 8, accepts: 1 },+ 'switch-core': { speaks: 9, accepts: 1 },+ 'agent-runtime': { speaks: 9, accepts: 1 },},// The HTTP API switch-core serves to first-party UI clients. Excludes the authentication surface, which is deliberately frozen and unversioned so that a client can always authenticate far enough to be told what is wrong.'gateway-api': {diff --git a/console/packages/switch-agent-runtime/src/artifacts.ts b/console/packages/switch-agent-runtime/src/artifacts.tsindex 0e8d163bf..0a0d1bbeb 100644--- a/console/packages/switch-agent-runtime/src/artifacts.ts+++ b/console/packages/switch-agent-runtime/src/artifacts.ts@@ -42,8 +42,8 @@ export function artifactVersion(artifact: ArtifactName): string {export const CONTRACTS = {// The wire protocol between switch-core's agent bridge and an agent runtime: the event stream, its frame shapes, the resume cursor, and the tool-call channel.'agent-protocol': {- 'switch-core': { speaks: 8, accepts: 1 },- 'agent-runtime': { speaks: 8, accepts: 1 },+ 'switch-core': { speaks: 9, accepts: 1 },+ 'agent-runtime': { speaks: 9, accepts: 1 },},// The HTTP API switch-core serves to first-party UI clients. Excludes the authentication surface, which is deliberately frozen and unversioned so that a client can always authenticate far enough to be told what is wrong.'gateway-api': {diff --git a/console/packages/switch-agent-runtime/src/event-stream.old-server.test.ts b/console/packages/switch-agent-runtime/src/event-stream.old-server.test.tsindex 3b6d93837..537ad1ade 100644--- a/console/packages/switch-agent-runtime/src/event-stream.old-server.test.ts+++ b/console/packages/switch-agent-runtime/src/event-stream.old-server.test.ts@@ -1341,9 +1341,9 @@ it('does not acknowledge a delivery before the consumer has saved it', async ()});const { stream, abort } = makeStream(fetchMock, { rooms: ['room'], startCursor: 6, onEvent });await vi.waitFor(() => expect(onEvent).toHaveBeenCalledOnce());- expect(stream.position).toBe(6);+ expect(stream.position).toEqual({ s: 6 });finish();- await vi.waitFor(() => expect(stream.position).toBe(7));+ await vi.waitFor(() => expect(stream.position).toEqual({ s: 7 }));abort.abort();});@@ -1399,10 +1399,10 @@ it('waits for durable reset checkpoint before advancing the cursor or deliveringcursorReset: true,reason: 'buffer reset',});- expect(stream.position).toBe(4);+ expect(stream.position).toEqual({ s: 4 });expect(onEvent).not.toHaveBeenCalled();finish();- await vi.waitFor(() => expect(stream.position).toBe(1));+ await vi.waitFor(() => expect(stream.position).toEqual({ s: 1 }));expect(onEvent).toHaveBeenCalledOnce();} finally {abort.abort();@@ -1420,7 +1420,7 @@ it('does not advance or deliver when persisting the reset checkpoint fails', asy);try {await vi.waitFor(() => expect(onGap).toHaveBeenCalledOnce());- expect(stream.position).toBe(4);+ expect(stream.position).toEqual({ s: 4 });expect(onEvent).not.toHaveBeenCalled();} finally {abort.abort();@@ -1822,7 +1822,7 @@ describe('test_gap_above_cursor_is_not_cursor_reset', () => {const { stream, abort } = makeStream(fetchMock, { rooms: [], onGap: (g) => void gaps.push(g) });await flush();expect(gaps).toEqual([expect.objectContaining({ resumedAt: 2 ** 32 - 1, cursorReset: false })]);- expect(stream.position).toBe(2 ** 32 - 1);+ expect(stream.position).toEqual({ s: 2 ** 32 - 1 });abort.abort();});});@@ -2059,7 +2059,7 @@ describe('choosing the transport', () => {await flush();const params = new URL(urlsFor(fetchMock, '/events')[0]!).searchParams;- expect(params.get('protocol')).toBe('8');+ expect(params.get('protocol')).toBe('9');expect(Number(params.get('protocol_accepts'))).toBeLessThanOrEqual(6);abort.abort();});diff --git a/console/packages/switch-agent-runtime/src/event-stream.test.ts b/console/packages/switch-agent-runtime/src/event-stream.test.tsindex fe93623e9..a3ecf1aca 100644--- a/console/packages/switch-agent-runtime/src/event-stream.test.ts+++ b/console/packages/switch-agent-runtime/src/event-stream.test.ts@@ -274,7 +274,7 @@ describe('the heartbeat', () => {server.sockets[0]!.ping();await flush();- expect(server.sockets[0]!.sent).toEqual([{ type: 'pong', cursor: 3 }]);+ expect(server.sockets[0]!.sent).toEqual([{ type: 'pong', cursor: 3, position: { s: 3 } }]);abort.abort();});@@ -299,15 +299,15 @@ describe('the heartbeat', () => {server.sockets[0]!.ping();await flush();// The cursor it names is the last event fully handled, not the one in hand.- expect(server.sockets[0]!.sent).toEqual([{ type: 'pong', cursor: 6 }]);+ expect(server.sockets[0]!.sent).toEqual([{ type: 'pong', cursor: 6, position: { s: 6 } }]);finish();await flush();server.sockets[0]!.ping();await flush();expect(server.sockets[0]!.sent).toEqual([- { type: 'pong', cursor: 6 },- { type: 'pong', cursor: 7 },+ { type: 'pong', cursor: 6, position: { s: 6 } },+ { type: 'pong', cursor: 7, position: { s: 7 } },]);abort.abort();});@@ -854,9 +854,9 @@ describe('the cursor', () => {});const { stream, abort } = makeStream({ rooms: ['room'], startCursor: 6, onEvent });await vi.waitFor(() => expect(onEvent).toHaveBeenCalledOnce());- expect(stream.position).toBe(6);+ expect(stream.position).toEqual({ s: 6 });finish();- await vi.waitFor(() => expect(stream.position).toBe(7));+ await vi.waitFor(() => expect(stream.position).toEqual({ s: 7 }));abort.abort();});@@ -911,10 +911,10 @@ describe('the cursor', () => {cursorReset: true,reason: 'buffer reset',});- expect(stream.position).toBe(4);+ expect(stream.position).toEqual({ s: 4 });expect(onEvent).not.toHaveBeenCalled();finish();- await vi.waitFor(() => expect(stream.position).toBe(1));+ await vi.waitFor(() => expect(stream.position).toEqual({ s: 1 }));expect(onEvent).toHaveBeenCalledOnce();} finally {abort.abort();@@ -930,7 +930,7 @@ describe('the cursor', () => {const { stream, abort } = makeStream({ rooms: ['room'], startCursor: 4, onGap, onEvent });try {await vi.waitFor(() => expect(onGap).toHaveBeenCalledOnce());- expect(stream.position).toBe(4);+ expect(stream.position).toEqual({ s: 4 });expect(onEvent).not.toHaveBeenCalled();} finally {abort.abort();@@ -938,6 +938,122 @@ describe('the cursor', () => {});});+describe('the position (agent-protocol 9)', () => {+ /** Open, and say where the stream starts, as a server that speaks positions does. */+ const startingAt =+ (position: Record<string, number>): Script =>+ (socket) => {+ socket.open();+ socket.frame('connection_state', { connection_id: 'conn-1', generation: 0, position });+ };++ it('keeps each source’s place, and resumes from all of them', async () => {+ // A room's conversation is numbered in the room, so its events carry no+ // number of the agent's own: only the position says where they were.+ vi.useFakeTimers();+ serve((socket, index) => {+ startingAt({ s: 5 })(socket, index);+ if (index === 0) {+ socket.frame('message', { type: 'message', room_id: 'room', position: { s: 6 } }, 6);+ socket.frame('message', { type: 'message', room_id: 'room', position: { 'r:room': 40 } });+ socket.drop();+ }+ });+ const { abort } = makeStream({ rooms: ['room'] });++ await vi.advanceTimersByTimeAsync(1_000);++ expect(server.sockets.map((socket) => socket.params.get('start_at'))).toEqual([+ 'head',+ JSON.stringify({ s: 6, 'r:room': 40 }),+ ]);+ // What a server from before positions reads instead.+ expect(server.sockets[1]?.params.get('start_from')).toBe('6');+ abort.abort();+ });++ it('resumes an open at head from where head was, not from where it has got to', async () => {+ // Nothing arrived before the socket dropped, so the only record of where+ // this stream started is what the server said when it opened. Without it+ // the reopen asks for head again and skips whatever landed in between.+ vi.useFakeTimers();+ serve((socket, index) => {+ startingAt({ s: 9 })(socket, index);+ if (index === 0) socket.drop();+ });+ const { abort } = makeStream({ rooms: ['room'] });++ await vi.advanceTimersByTimeAsync(1_000);++ expect(server.sockets[1]?.params.get('start_at')).toBe(JSON.stringify({ s: 9 }));+ abort.abort();+ });++ it('takes a gap’s resumed position whole, even where it moves back', async () => {+ const onGap = vi.fn();+ serve((socket) => {+ socket.open();+ socket.frame('gap', {+ from_sequence: 4,+ resumed_at: 2,+ resumed_position: { s: 2, 'r:room': 7 },+ reason: 'the server restarted',+ });+ socket.frame('message', { type: 'message', room_id: 'room', position: { s: 3 } }, 3);+ });+ const { stream, abort } = makeStream({+ rooms: ['room'],+ startCursor: 4,+ onGap,+ });+ try {+ await vi.waitFor(() => expect(stream.position).toEqual({ s: 3, 'r:room': 7 }));+ expect(onGap).toHaveBeenCalledWith(+ expect.objectContaining({ resumedAt: 2, cursorReset: true })+ );+ } finally {+ abort.abort();+ }+ });++ it('refuses a gap whose resumed position is not one, and moves nowhere', async () => {+ const onGap = vi.fn();+ serve((socket) => {+ socket.open();+ socket.frame('gap', { from_sequence: 4, resumed_position: { s: -1 }, reason: 'x' });+ });+ const { stream, abort } = makeStream({ rooms: ['room'], startCursor: 4, onGap });+ try {+ await flush();+ expect(onGap).not.toHaveBeenCalled();+ expect(stream.position).toEqual({ s: 4 });+ } finally {+ abort.abort();+ }+ });++ it('answers a ping with its whole position beside the cursor', async () => {+ serve((socket) => {+ attach(socket, 0);+ socket.frame('message', { type: 'message', room_id: 'room', position: { 'r:room': 12 } });+ });+ const onEvent = vi.fn();+ const { abort } = makeStream({ rooms: ['room'], onEvent });+ try {+ // A pong reports what has been handled, so the ping waits for the event.+ await vi.waitFor(() => expect(onEvent).toHaveBeenCalledOnce());+ server.sockets[0]!.ping();+ await vi.waitFor(() =>+ expect(server.sockets[0]!.sent).toEqual([+ { type: 'pong', cursor: 0, position: { 'r:room': 12 } },+ ])+ );+ } finally {+ abort.abort();+ }+ });+});+describe('the permission to start a session', () => {it('is redeclared on the wire when it changes under a live connection', async () => {// Turning automatic sessions off while the controller is connected has to@@ -1069,7 +1185,7 @@ describe('frames that are not room events', () => {try {await vi.waitFor(() => expect(onCommands).toHaveBeenCalledWith(['session']));expect(onEvent).not.toHaveBeenCalled();- expect(stream.position).toBe(0);+ expect(stream.position).toEqual({});} finally {abort.abort();}diff --git a/console/packages/switch-agent-runtime/src/event-stream.ts b/console/packages/switch-agent-runtime/src/event-stream.tsindex b0dbc5c44..127736663 100644--- a/console/packages/switch-agent-runtime/src/event-stream.ts+++ b/console/packages/switch-agent-runtime/src/event-stream.ts@@ -1,4 +1,5 @@import { contractRange } from './artifacts';+import { furthest, OWN_EVENTS, type Position, readPosition } from './positions';import { ReattachFence } from './reattach-fence';import { readSse } from './sse';import type { AgentBridgeEvent, SwitchCredentials } from './types';@@ -25,11 +26,14 @@ const AGENT_PROTOCOL = contractRange('agent-protocol', RUNTIME_ARTIFACT);* `openFrames`). That path is kept for a compatibility window and goes when* those servers are gone.*- * Every event carries a sequence number, and a reconnect names the last one we- * handled, so we get exactly what we missed. A gap is never silent: if the- * server cannot serve our cursor it says so, and `onGap` fires so the caller- * can tell the agent to re-read context rather than carry on believing it saw- * everything.+ * Each event frame says where the event is numbered, and on reconnect we tell+ * the server how far we have read, so it sends exactly the events we missed. A+ * server that speaks agent-protocol 9 tracks this as a position: one number for+ * the agent's own events and one for each room's conversation (see `Position`).+ * An older server understands only the own-events number, so we send that+ * number as well. A gap is never silent: if the server cannot serve our+ * position it says so, and `onGap` fires so the caller can tell the agent to+ * re-read context rather than carry on believing it saw everything.*//** How long a request on the side (a room claim, placements, a beat) may take. */@@ -98,6 +102,8 @@ export class PlacementsRefusedError extends Error {export type StreamScope = 'single' | 'all';export type DeliveryFilter = 'all' | 'addressed';+export type { Position } from './positions';+/*** Why a stream ended, in the form a caller can branch on.*@@ -302,7 +308,10 @@ export interface SwitchEventStreamDeps {reason: string;/** The rooms that lost events. Absent from a server that predates naming them. */rooms?: string[];+ /** The own-events number (`s`) the server resumes sending from after the gap. */resumedAt?: number;+ /** True when `resumedAt` is behind the own-events number we had already read,+ * which means the server restarted its numbering. */cursorReset?: boolean;}): void | Promise<void>;/** Fired when another stream took this connection over, or it was closed.@@ -353,10 +362,12 @@ type HeaderedWebSocket = new (url: string, init: { headers: Record<string, strinexport class SwitchEventStream {private readonly deps: SwitchEventStreamDeps;- /** Highest sequence number received. Sent with every pong and as- * `start_from` when reopening. Seeded from `startCursor` when the caller- * needs to begin behind head rather than at it. */- private cursor: number;+ /** How far this stream has read. We send it in every WebSocket pong and SSE+ * beat, and as `start_at` when we reopen. When the caller passes+ * `startCursor`, it becomes the own-events number, so the stream resumes from+ * a saved point instead of starting at the current end of the agent's own+ * events. */+ private _position: Position;/** Aborts only the current socket, so a reconnect can replace it without* tearing down the connection. */private socketAbort: AbortController | null = null;@@ -438,13 +449,20 @@ export class SwitchEventStream {constructor(deps: SwitchEventStreamDeps) {this.deps = deps;this.rooms = [...deps.rooms];- this.cursor = deps.startCursor ?? 0;+ this._position = deps.startCursor === undefined ? {} : { [OWN_EVENTS]: deps.startCursor };this.spawnCapable = deps.spawnCapable === true;this.declaredSpawnCapable = this.spawnCapable;}- get position(): number {- return this.cursor;+ get position(): Position {+ return { ...this._position };+ }++ /** The own-events number (`s`) from our position. A server older than+ * agent-protocol 9 understands only this number, so we also send it as+ * `start_from`, as `Last-Event-ID`, and as `cursor` in pongs and beats. */+ private get cursor(): number {+ return this._position[OWN_EVENTS] ?? 0;}/**@@ -800,6 +818,11 @@ export class SwitchEventStream {filter,start_from:this.cursor > 0 || this.deps.startCursor !== undefined ? String(this.cursor) : 'head',+ // Our state vector: where we are in every source. A server that+ // speaks agent-protocol 9 uses it instead of `start_from`. When we+ // have read nothing yet we send `head`, which asks the server to+ // start at the current end of the agent's own events and of each room.+ start_at: Object.keys(this._position).length ? JSON.stringify(this._position) : 'head',// What we are and what we speak, declared on the connect we already// make (CHOO-1865). A client that says nothing records as unknown// server-side, and a declaration cannot be backfilled after the fact@@ -833,7 +856,6 @@ export class SwitchEventStream {});})) {await this.handleFrame(frame);- if (frame.id) this.cursor = Math.max(this.cursor, Number(frame.id) || 0);}} catch (error) {if (error instanceof OpenRefused) {@@ -1018,7 +1040,9 @@ export class SwitchEventStream {return;}if (parsed.event === 'ping') {- socket.send(JSON.stringify({ type: 'pong', cursor: this.cursor }));+ socket.send(+ JSON.stringify({ type: 'pong', cursor: this.cursor, position: this._position })+ );return;}if (parsed.event === 'refused') {@@ -1068,8 +1092,18 @@ export class SwitchEventStream {private async handleFrame(frame: SocketFrame): Promise<void> {const { log, onGap, onEvicted, onEvent } = this.deps;switch (frame.event) {- case 'connection_state':+ case 'connection_state': {if (typeof frame.data.generation === 'number') this.generation = frame.data.generation;+ // `connection_state` is the first frame after the socket connects. Its+ // `position` is the point the server will start sending events from:+ // the `start_at` we asked for, or, when we asked for `head` because we+ // had read nothing yet, the current end of the agent's own events and of+ // each room. We fold it into our own position. Otherwise, if the+ // socket drops and reconnects before any event arrives, we would ask+ // for `head` again, start from wherever the end is by then, and+ // never receive the events that arrived in between.+ const startedAt = readPosition(frame.data.position);+ if (startedAt) this._position = furthest(this._position, startedAt);this.announces = frame.data.announce_session_starts === true;this.attachedOver = this.openingOver;// Reached over the stream: whether the server has a socket for next@@ -1104,6 +1138,7 @@ export class SwitchEventStream {this.redeclare();this.deps.onConnected?.();return;+ }case 'room_released': {const roomId = frame.data.room_id;const sessionId = frame.data.session_id ?? null;@@ -1145,6 +1180,15 @@ export class SwitchEventStream {const resumedAt = frame.data.resumed_at;if (resumedAt !== undefined && (!Number.isSafeInteger(resumedAt) || Number(resumedAt) < 0))throw new Error('Switch returned an invalid gap resume cursor.');+ // A server that speaks agent-protocol 9 sends `resumed_position`, the+ // position it will resume sending from after the gap. We replace our+ // position with it rather than merging it with `furthest`, because a+ // gap is the only case where the server moves a position back. Merging+ // would keep our higher numbers, and the next reconnect would ask to+ // start past events we never received.+ const resumed = readPosition(frame.data.resumed_position);+ if (frame.data.resumed_position !== undefined && resumed === null)+ throw new Error('Switch returned an invalid gap resume position.');await onGap({fromSequence: Number(frame.data.from_sequence ?? 0),reason: String(frame.data.reason ?? 'events were missed'),@@ -1153,7 +1197,9 @@ export class SwitchEventStream {? {}: { resumedAt: Number(resumedAt), cursorReset: Number(resumedAt) < this.cursor }),});- if (resumedAt !== undefined) this.cursor = Number(resumedAt);+ if (resumed) this._position = resumed;+ else if (resumedAt !== undefined)+ this._position = { ...this._position, [OWN_EVENTS]: Number(resumedAt) };return;}case 'evicted': {@@ -1195,18 +1241,34 @@ export class SwitchEventStream {return;}default:- if (typeof frame.data.type !== 'string') {+ if (typeof frame.data.type === 'string')+ await onEvent(frame.data as unknown as AgentBridgeEvent);+ else// A frame this runtime does not know and cannot read as a room event.log.warn('SwitchEventStream: unknown frame dropped', {event: 'switch_stream_unknown_frame',frame: frame.event,});- return;- }- await onEvent(frame.data as unknown as AgentBridgeEvent);+ this.passed(frame);}}+ /**+ * Advances our position past an event after it has been handled. A server+ * that speaks agent-protocol 9 sends the event's `position`; an older server+ * sends only its own-events number, as the frame id.+ *+ * This runs after the handler, not before, so that if the handler throws the+ * event is not counted as read and the server sends it again when the stream+ * reopens.+ */+ private passed(frame: SocketFrame): void {+ const eventPosition =+ readPosition(frame.data.position) ??+ (frame.id ? { [OWN_EVENTS]: Number(frame.id) || 0 } : null);+ if (eventPosition) this._position = furthest(this._position, eventPosition);+ }+/*** The event stream's heartbeat. Proves we are alive and reports the cursor.*@@ -1305,6 +1367,7 @@ export class SwitchEventStream {const resp = await this.post('connection/beat', {connection_id: connectionId,cursor: this.cursor,+ position: this._position,generation: this.generation,});return { answered: true, status: resp.status, ok: resp.ok, body: await resp.text() };diff --git a/console/packages/switch-agent-runtime/src/positions.test.ts b/console/packages/switch-agent-runtime/src/positions.test.tsnew file mode 100644index 000000000..28e0354bf--- /dev/null+++ b/console/packages/switch-agent-runtime/src/positions.test.ts@@ -0,0 +1,32 @@+import { describe, expect, it } from 'vitest';+import { furthest, readPosition } from './positions';++describe('furthest', () => {+ it('takes each source at the further of the two, keeping sources only one has', () => {+ expect(furthest({ s: 5, 'r:a': 2 }, { s: 3, 'r:a': 7, 'r:b': 1 })).toEqual({+ s: 5,+ 'r:a': 7,+ 'r:b': 1,+ });+ });++ it('lands in the same place whatever order and however often reports arrive', () => {+ const a = { s: 4, 'r:a': 9 };+ const b = { s: 6 };+ const c = { 'r:a': 2, 'r:b': 3 };+ const once = furthest(furthest(a, b), c);+ expect(furthest(furthest(c, a), b)).toEqual(once);+ expect(furthest(once, b)).toEqual(once);+ });+});++describe('readPosition', () => {+ it('reads an object of source to non-negative integer', () => {+ expect(readPosition({ s: 18, 'r:a': 43 })).toEqual({ s: 18, 'r:a': 43 });+ });++ it('refuses anything else', () => {+ for (const raw of [null, 7, 's', [1, 2], { s: -1 }, { s: 1.5 }, { s: '3' }])+ expect(readPosition(raw)).toBeNull();+ });+});diff --git a/console/packages/switch-agent-runtime/src/positions.ts b/console/packages/switch-agent-runtime/src/positions.tsnew file mode 100644index 000000000..d39abeff0--- /dev/null+++ b/console/packages/switch-agent-runtime/src/positions.ts@@ -0,0 +1,43 @@+/**+ * A position records how far a connection has read the events the server+ * sends an agent. This module reads positions off the wire and merges them. It+ * mirrors `switch_core/bridges/agent/protocol/positions.py` on the server.+ */++/**+ * How far a connection has read, as one number per source of events, each+ * numbered on its own. `s` is the agent's own events: the events meant for the+ * agent (messages addressed to it, the room joins it listens for, commands,+ * task events), not the ones it sent. `r:<room id>` is a room's conversation, which+ * the server sends only to a connection that reads everything said in the room.+ * The server names the sources, so apart from `s` this runtime keeps whatever+ * keys it is sent without interpreting them.+ */+export type Position = Record<string, number>;++/** The key for the agent's own events in a `Position`. Its number is the only one+ * a server on agent-protocol 8 or older understands. */+export const OWN_EVENTS = 's';++/** Reads a position from a frame field, or returns null when the field is not+ * a valid position. */+export function readPosition(raw: unknown): Position | null {+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return null;+ const position: Position = {};+ for (const [source, value] of Object.entries(raw)) {+ if (!Number.isSafeInteger(value) || (value as number) < 0) return null;+ position[source] = value as number;+ }+ return position;+}++/** The join (least upper bound) of two positions in their join-semilattice:+ * each source at the further of the two. Merging this way never moves a+ * position back. Only a `gap` frame does that, and its `resumed_position`+ * replaces the position instead of being merged. */+export function furthest(current: Position, reported: Position): Position {+ const position = { ...current };+ for (const [source, value] of Object.entries(reported))+ position[source] = Math.max(position[source] ?? 0, value);+ return position;+}diff --git a/console/packages/switch-agent-runtime/src/types.ts b/console/packages/switch-agent-runtime/src/types.tsindex 9599b9fa0..2e387aeaf 100644--- a/console/packages/switch-agent-runtime/src/types.ts+++ b/console/packages/switch-agent-runtime/src/types.ts@@ -73,8 +73,11 @@ export interface AgentBridgeEvent {room_id: string;payload: MessagePayload | CommandPayload | RoomJoinPayload | TaskPayload;/**- * The event's position in the agent's buffer. Present on the push transport,- * absent on the legacy poll.+ * The event's number in the agent's own events (`s`). It is present on the push+ * transport and absent on the legacy poll. It is also absent on a message+ * from a room's conversation sent to a connection that reads the whole room+ * (`filter: 'all'`), because that message is numbered in the room's own+ * sequence, which `position` carries.** Load-bearing when a watcher spawns a session: the session's connection has* to start from *before* the message that triggered the spawn, or the very@@ -91,6 +94,13 @@ export interface AgentBridgeEvent {* `reason` is why. A reason alongside a number means the number is a floor.*/missed?: { count: number | null; reason: string | null };+ /**+ * The event's place as a position with one entry: the source it came from+ * and its number there, for example `{s: 7}` for an event in the agent's+ * own events or `{'r:<room id>': 42}` for a message in a room's conversation. A+ * server that speaks agent-protocol 9 sends it.+ */+ position?: Record<string, number>;}export interface AgentBridgeEventResponse {diff --git a/core/switch_core/artifacts.py b/core/switch_core/artifacts.pyindex 63ef7cb0b..eb5a1b647 100644--- a/core/switch_core/artifacts.py+++ b/core/switch_core/artifacts.py@@ -35,8 +35,8 @@ ARTIFACT_VERSIONS: Final[dict[str, str]] = {CONTRACTS: Final[dict[str, dict[str, ContractRange]]] = {# The wire protocol between switch-core's agent bridge and an agent runtime: the event stream, its frame shapes, the resume cursor, and the tool-call channel."agent-protocol": {- "switch-core": ContractRange(speaks=8, accepts=1),- "agent-runtime": ContractRange(speaks=8, accepts=1),+ "switch-core": ContractRange(speaks=9, accepts=1),+ "agent-runtime": ContractRange(speaks=9, accepts=1),},# The HTTP API switch-core serves to first-party UI clients. Excludes the authentication surface, which is deliberately frozen and unversioned so that a client can always authenticate far enough to be told what is wrong."gateway-api": {diff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.pyindex 12836179f..c720ffd6a 100644--- a/core/switch_core/bridges/agent/api/handlers.py+++ b/core/switch_core/bridges/agent/api/handlers.py@@ -83,6 +83,7 @@ from switch_core.bridges.agent.dependencies import (get_protocol,get_session,)+from switch_core.bridges.agent.protocol import positionsfrom switch_core.bridges.agent.protocol.agent_connections import (HEARTBEAT_INTERVAL_SECONDS,AgentConnection,@@ -104,7 +105,8 @@ from switch_core.bridges.agent.protocol.agent_connections import (evicted_session_warning,)from switch_core.bridges.agent.protocol.agent_core import AgentCore, AgentExistsError-from switch_core.bridges.agent.protocol.event_buffer import Reader+from switch_core.bridges.agent.protocol.event_buffer import TICKET_FLOOR, Reader+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS, Positionfrom switch_core.bridges.agent.protocol.stream import (KEEPALIVE,Frame,@@ -735,6 +737,7 @@ async def poll_events(scope: Annotated[str, Query()] = "single",event_filter: Annotated[str, Query(alias="filter")] = "all",start_from: Annotated[str, Query()] = "head",+ start_at: Annotated[str | None, Query()] = None,spawn_capable: Annotated[bool, Query()] = False,protocol_version: Annotated[int | None, Query(alias="protocol")] = None,protocol_accepts: Annotated[int | None, Query()] = None,@@ -766,6 +769,7 @@ async def poll_events(scope=scope,event_filter=event_filter,start_from=start_from,+ start_at=start_at,spawn_capable=spawn_capable,declaration=ClientDeclaration(speaks=protocol_version,@@ -784,27 +788,66 @@ async def poll_events(return EventResponse(events=events)-def _resolve_start_cursor(+async def _resolve_start_position(protocol: AgentCore,- agent_id: str,+ agent: Agent,+ *,+ start_at: str | None,start_from: str,- last_event_id: str | None = None,-) -> int:- """Where a connection's events begin: the head, or a sequence number.-- `Last-Event-ID` wins when present: an event-stream client that reconnects- sends it, and it is the most accurate statement of what it processed.+ last_event_id: str | None,+ reads_conversation: bool,+) -> tuple[Position, int | None]:+ """Work out the position a new connection starts sending events from.++ Returns the position and, when the client sent a ticket id the server no+ longer has, that id, so the stream can open with a gap that names it.+ Otherwise the second value is None.++ A client on agent-protocol revision 9 sends `start_at`: either "head" or+ a position such as `{"s": 12, "r:<room_id>": 40}`. When the position has+ no `s` entry, the connection starts at the current end of the agent's+ own events.++ An older client holds one integer and sends it as `start_from`, or as+ `Last-Event-ID` when an event stream reconnects. `Last-Event-ID` wins+ because it is the id of the last event the client processed. When the+ connection reads only the agent's own events, the integer is their `seq`.+ When it also reads the room conversation (`reads_conversation`), the+ integer is a ticket id from `agent_position_tickets` and the position is+ looked up there. A ticket that has expired or never existed starts the+ connection at the end of the agent's own events, and the stream reports+ the gap."""+ buffer = protocol.event_buffer+ if start_at:+ if start_at == "head":+ return {OWN_EVENTS: await buffer.head(agent.tenant_id, agent.id)}, None+ try:+ position = positions.parse(start_at)+ except ValueError as exc:+ raise HTTPException(+ status_code=400,+ detail=f"start_at must be 'head' or a position: {exc}",+ ) from exc+ if OWN_EVENTS not in position:+ position[OWN_EVENTS] = await buffer.head(agent.tenant_id, agent.id)+ return position, Noneraw = last_event_id or start_fromif raw in ("", "head"):- return protocol.event_buffer.head(agent_id)+ return {OWN_EVENTS: await buffer.head(agent.tenant_id, agent.id)}, Nonetry:- return max(int(raw), 0)+ number = max(int(raw), 0)except ValueError as exc:raise HTTPException(status_code=400,detail=f"start_from must be 'head' or a sequence number, got {raw!r}",) from exc+ if reads_conversation and number >= TICKET_FLOOR:+ held = await buffer.ticket(agent.tenant_id, agent.id, number)+ if held is None:+ return {OWN_EVENTS: await buffer.head(agent.tenant_id, agent.id)}, number+ return held, None+ return {OWN_EVENTS: number}, Nonedef _register_connection(@@ -815,7 +858,7 @@ def _register_connection(scope: str,event_filter: str,spawn_capable: bool,- cursor: int,+ position: Position,declaration: ClientDeclaration,expected_generation: int | None,transport: Transport,@@ -827,7 +870,7 @@ def _register_connection(scope=cast(Scope, scope),delivery_filter=cast(DeliveryFilter, event_filter),spawn_capable=spawn_capable,- cursor=cursor,+ position=position,declaration=declaration,expected_generation=expected_generation,transport=transport,@@ -874,6 +917,7 @@ async def _open_connection(event_filter: str,start_from: str,spawn_capable: bool,+ start_at: str | None = None,declaration: ClientDeclaration,rooms: str | None,expected_generation: int | None,@@ -903,7 +947,14 @@ async def _open_connection(detail=f"filter must be 'all' or 'addressed', got {event_filter!r}",)- cursor = _resolve_start_cursor(protocol, agent.id, start_from, last_event_id)+ position, lost = await _resolve_start_position(+ protocol,+ agent,+ start_at=start_at,+ start_from=start_from,+ last_event_id=last_event_id,+ reads_conversation=event_filter == "all",+ )conn = _register_connection(protocol=protocol,@@ -912,11 +963,14 @@ async def _open_connection(scope=scope,event_filter=event_filter,spawn_capable=spawn_capable,- cursor=cursor,+ position=position,declaration=declaration,expected_generation=expected_generation,transport=transport,)+ if lost is not None:+ conn.resume_lost = True+ conn.resume_requested = lost# Built before anything below can yield, so it holds the generation this# open produced; a reconnect during the bookkeeping supersedes it rather@@ -955,7 +1009,9 @@ async def _open_connection(protocol.connections.claim_room(conn, room_id, takeover=True)# The room's unread count follows the slot: whoever is told how far# behind the room is has to be the one whose reading clears it.- protocol.event_buffer.take_counting(agent.id, conn.id, room_id, conn.cursor)+ await protocol.event_buffer.take_counting(+ agent.tenant_id, agent.id, conn.id, room_id+ )except (ValueError, PermissionError) as exc:protocol.connections.close(conn.id,@@ -1001,6 +1057,7 @@ async def _open_event_stream(event_filter: str,start_from: str,spawn_capable: bool,+ start_at: str | None = None,declaration: ClientDeclaration,rooms: str | None,last_event_id: str | None,@@ -1021,6 +1078,7 @@ async def _open_event_stream(scope=scope,event_filter=event_filter,start_from=start_from,+ start_at=start_at,spawn_capable=spawn_capable,declaration=declaration,rooms=rooms,@@ -1047,26 +1105,22 @@ def _record_beat(protocol: AgentCore,agent_id: str,connection_id: str,- cursor: int,generation: int | None,) -> AgentConnection:- """Count a client's beat, and adopt its cursor: a pong on the socket, or a- `POST /connection/beat` from an event-stream client.+ """Count a client's beat: the client is still there.- The cursor is clamped to the buffer head first. The buffer is in memory,- so a restart resets the sequence while a client keeps reporting the- number it had reached, and neither `beat()` nor `confirm()` will move a- cursor backwards: adopting the stale number would skip every event up to- it, silently, and mark them consumed on the way past.+ A beat is a pong on the WebSocket, or a `POST /connection/beat` from an+ event-stream client. Clients also report how far they have read; it is not+ read here. The connection's position is moved only by the stream, as it+ sends, and a client that drops resumes from the position it sends when it+ reopens, which is checked against the database then. So a beat costs no+ database query.Raises the registry's refusal when the connection is no longer thisclient's to beat for: another socket took it over (`taken_over`), or ithas no stream attached (`no_stream`), or it is gone."""- cursor = min(cursor, protocol.event_buffer.head(agent_id))- conn = protocol.connections.beat(agent_id, connection_id, cursor, generation)- protocol.event_buffer.confirm(agent_id, conn.id, cursor)- return conn+ return protocol.connections.beat(agent_id, connection_id, generation)@router.post("/{agent_id}/connection/beat")@@ -1080,16 +1134,14 @@ async def connection_beat(The socket carries its own heartbeat; this is for a client built before it,kept with the event stream for the same compatibility window. Proves the- client is alive and reports its cursor. Rejected when the connection is+ client is alive. Rejected when the connection isunknown, dead, has no stream attached, or belongs to another incarnation.A refusal carries a code beside its prose, because the remedies differ:`taken_over` is terminal for the client that receives it, and the rest arerecovered by reopening."""try:- conn = _record_beat(- protocol, agent.id, req.connection_id, req.cursor, req.generation- )+ conn = _record_beat(protocol, agent.id, req.connection_id, req.generation)except (NoStreamAttachedError,SupersededConnectionError,@@ -1100,7 +1152,12 @@ async def connection_beat() from excexcept UnknownConnectionError as exc:raise HTTPException(status_code=404, detail=str(exc)) from exc- return {"ok": True, "rooms": sorted(conn.rooms), "cursor": conn.cursor}+ return {+ "ok": True,+ "rooms": sorted(conn.rooms),+ "cursor": conn.cursor,+ "position": dict(conn.position),+ }# A WebSocket close code for each refusal that would otherwise be an HTTP@@ -1120,6 +1177,7 @@ async def connection_socket(scope: Annotated[str, Query()] = "single",event_filter: Annotated[str, Query(alias="filter")] = "all",start_from: Annotated[str, Query()] = "head",+ start_at: Annotated[str | None, Query()] = None,spawn_capable: Annotated[bool, Query()] = False,protocol_version: Annotated[int | None, Query(alias="protocol")] = None,protocol_accepts: Annotated[int | None, Query()] = None,@@ -1154,6 +1212,7 @@ async def connection_socket(scope=scope,event_filter=event_filter,start_from=start_from,+ start_at=start_at,spawn_capable=spawn_capable,declaration=ClientDeclaration(speaks=protocol_version,@@ -1225,6 +1284,11 @@ async def connection_socket(pump.cancel()pongs.cancel()failure = pump.exception() if pump.done() and not pump.cancelled() else None+ # Cancelling the tasks only requests that they stop. The pump's cleanup+ # may be in the middle of a database read, so this waits for both to+ # finish before returning, which guarantees the stream has detached+ # from the connection by then.+ await asyncio.gather(pump, pongs, return_exceptions=True)if failure is not None:logger.error("[STREAM] agent=%s connection=%s delivery failed, closing its socket",@@ -1276,10 +1340,8 @@ async def _receive_pongs(return Noneif not isinstance(message, dict) or message.get("type") != "pong":continue- raw = message.get("cursor", 0)- cursor = raw if isinstance(raw, int) and raw >= 0 else 0try:- _record_beat(protocol, agent_id, connection_id, cursor, generation)+ _record_beat(protocol, agent_id, connection_id, generation)except ConnectionError_ as refusal:return refusal@@ -1359,7 +1421,9 @@ async def connection_subscribe(# A room slot changes hands here as much as it does on the stream URL or in# connect_to_room, and the room's unread count follows it: the holder being# told how far behind the room is has to be the one whose reading clears it.- protocol.event_buffer.take_counting(agent.id, conn.id, req.room_id, conn.cursor)+ await protocol.event_buffer.take_counting(+ agent.tenant_id, agent.id, conn.id, req.room_id+ )if evicted is not None:logger.warning(@@ -1439,8 +1503,11 @@ async def connection_placements(for session_id, room_id in req.placements.items():if before.get(session_id) != room_id:- protocol.event_buffer.hand_counting_to(- agent.id, Reader(id=session_id, is_session=True), room_id+ await protocol.event_buffer.hand_counting_to(+ agent.tenant_id,+ agent.id,+ Reader(id=session_id, is_session=True),+ room_id,)for lost in released:logger.warning(diff --git a/core/switch_core/bridges/agent/api/schemas.py b/core/switch_core/bridges/agent/api/schemas.pyindex 80b0d4229..90fb572a3 100644--- a/core/switch_core/bridges/agent/api/schemas.py+++ b/core/switch_core/bridges/agent/api/schemas.py@@ -142,13 +142,13 @@ class ConnectionBeatRequest(BaseModel):"""The heartbeat of a connection held over the event stream (CHOO-1857).Kept for clients built before the WebSocket, whose socket carries the- heartbeat itself, for a compatibility window. Proves the client is alive- *and* consuming, and reports how far it has read so the event buffer knows- what has been seen.+ heartbeat itself, for a compatibility window. Proves the client is alive.+ Clients also send how far they have read (`cursor`, `position`); the+ server does not read it, because a client resumes from the position it+ sends when it reopens."""connection_id: str- cursor: int = 0#: The incarnation of the connection this client is attached to, as the#: server told it on `connection_state`. Fences the tick: a client that has#: been displaced still holds the id and the token, and is otherwisediff --git a/core/switch_core/bridges/agent/commands.py b/core/switch_core/bridges/agent/commands.pyindex 7d3cad181..f05704a4a 100644--- a/core/switch_core/bridges/agent/commands.py+++ b/core/switch_core/bridges/agent/commands.py@@ -519,7 +519,8 @@ async def _dispatch_control_command(# Switch Console when we know its deeplink.body = f"{ack} ([Open in Switch Console]({deeplink}))" if deeplink else ackawait _reply(client, room, event, body)- client._event_buffer.enqueue(+ await client._event_buffer.enqueue(+ client.tenant_id,client.agent.id,meta.room_id,AgentEvent(@@ -535,6 +536,8 @@ async def _dispatch_control_command(thread_id=event.thread_id,),),+ room_seq=event.room_seq,+ message_key=event.message_id,)diff --git a/core/switch_core/bridges/agent/operations/definitions.py b/core/switch_core/bridges/agent/operations/definitions.pyindex b8609b5c6..6e1dc395a 100644--- a/core/switch_core/bridges/agent/operations/definitions.py+++ b/core/switch_core/bridges/agent/operations/definitions.py@@ -361,7 +361,9 @@ async def connect_to_room(# one agent share it, and each of them is in a room of its own.reader = counting_reader()if reader is not None:- protocol.event_buffer.hand_counting_to(agent_id, reader, room.id)+ await protocol.event_buffer.hand_counting_to(+ require_tenant_id(), agent_id, reader, room.id+ )await bind_room_for_connectionless_caller(protocol,@@ -700,11 +702,13 @@ async def read_context(before_ms = parse_timestamp_ms(before) if before else Nonebuffer = protocol.event_buffer- # Sampled before the read, because anything enqueued while the history- # response is in flight is not in that response. Clearing through the- # later head would report a zero for a message the agent never saw;- # clearing through this one can only leave something counted twice.- through = buffer.head(agent_id)+ tenant_id = require_tenant_id()+ # The room's newest `messages.seq`, taken before the history read because+ # a message written while the read is in flight is not in its response.+ # Recording the catch-up through a later number would mark such a message+ # as read when the agent never saw it. Recording it through this number+ # can at worst count a message twice.+ through = (await buffer.room_heads(tenant_id, {room_id}))[room_id]context = await protocol.read_context(agent_id, room_id, limit=limit, since_ms=since_ms, before_ms=before_ms@@ -715,7 +719,9 @@ async def read_context(# Catching up is the whole point of the unread count, so doing it# clears this room — and only this room. A read of somewhere else# leaves every count alone, including this one.- buffer.caught_up(agent_id, reader, room_id, through, session_key())+ await buffer.caught_up(+ tenant_id, agent_id, reader, room_id, through, session_key()+ )return contextdiff --git a/core/switch_core/bridges/agent/protocol/agent_connections.py b/core/switch_core/bridges/agent/protocol/agent_connections.pyindex acb996f8d..2b7b0457c 100644--- a/core/switch_core/bridges/agent/protocol/agent_connections.py+++ b/core/switch_core/bridges/agent/protocol/agent_connections.py@@ -45,6 +45,7 @@ from switch_core.bridges.agent.protocol.liveness import (from switch_core.bridges.agent.protocol.liveness import TAKEN_OVER as TAKEN_OVERfrom switch_core.bridges.agent.protocol.liveness import CloseCode as CloseCodefrom switch_core.bridges.agent.protocol.liveness import Closure as Closure+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS, Positionfrom switch_core.logging_context import log_contextfrom switch_core.observability.catalogue import (AGENT_CONNECTIONS_EXPIRED,@@ -93,6 +94,12 @@ SESSION_COMMAND_PROTOCOL_REVISION = 5# or session placement on its connection was taken over by another connection.ROOM_RELEASED_PROTOCOL_REVISION = 6+# From this agent-protocol revision a client tracks a position (one number per+# source, see `positions.py`) instead of a single number. It opens with+# `start_at` and reads `position` from each event. A client on an older+# revision is sent a single number.+POSITIONS_PROTOCOL_REVISION = 9+# Upper bound on simultaneous connections per agent. Runaway growth becomes a# visible error instead of quiet resource creep.MAX_CONNECTIONS_PER_AGENT = 32@@ -114,7 +121,7 @@ class UnknownConnectionError(ConnectionError_):def __init__(self, connection_id: str) -> None:super().__init__(f"connection {connection_id} is not open; reconnect and resume from "- "your cursor"+ "where you got to")self.connection_id = connection_id@@ -156,7 +163,7 @@ class SupersededConnectionError(ConnectionError_):super().__init__(f"connection {connection_id} was reopened since incarnation "f"{presented} and is now at {current}; another client holds it, so "- "this heartbeat was refused and its cursor was not applied"+ "this heartbeat was refused")self.connection_id = connection_idself.presented = presented@@ -391,7 +398,10 @@ class AgentConnection:scope: Scopedelivery_filter: DeliveryFilterspawn_capable: bool- cursor: int+ # How far the server has sent events to this connection, as a position+ # (`positions.py`). It holds the agent's own events (`agent_events`) and,+ # for a connection that receives every room message, each room it covers.+ position: Positionlast_beat: floatopened_at: float# Rooms this connection has subscribed to. A `single` connection holds at@@ -423,10 +433,48 @@ class AgentConnection:# Rooms another connection took off this one, not yet written to its# stream, with the session of this connection that was placed there.released_rooms: dict[str, str | None] = field(default_factory=dict)+ # The ticket last sent to this connection's client. Only a client that+ # receives every room message but holds a single number is sent tickets. A+ # ticket is the id of a row in `agent_position_tickets` that stores a full+ # position, so the client can resume from it by sending back one number.+ ticket: int = 0+ # True when the client asked to resume from a ticket the server does not+ # have, because it expired or never existed. The stream then opens with a+ # gap frame, and `resume_requested` holds the number the client sent so the+ # gap can report it.+ resume_lost: bool = False+ resume_requested: int = 0def is_alive(self, now: float) -> bool:return self.closure is None and (now - self.last_beat) < HEARTBEAT_TTL_SECONDS+ @property+ def reads_conversation(self) -> bool:+ """Whether this connection asked for every room message (`filter=all`),+ read from `messages`, as well as the agent's own events."""+ return self.delivery_filter == "all"++ @property+ def speaks_positions(self) -> bool:+ """Whether the client is on agent-protocol revision 9 or later, and so+ sends and receives positions instead of a single number."""+ speaks = self.declaration.speaks+ return speaks is not None and speaks >= POSITIONS_PROTOCOL_REVISION++ @property+ def cursor(self) -> int:+ """The single number sent in `cursor` fields, for clients that predate+ positions.++ A client that receives every room message and does not speak positions+ is given the ticket last sent to it, because one number cannot hold its+ place in several rooms. Every other client is given its place in the+ agent's own events, the `s` entry of its position.+ """+ if self.reads_conversation and not self.speaks_positions:+ return self.ticket+ return self.position.get(OWN_EVENTS, 0)+# The `(transport, client)` an agent run by an agents controller counts under:# it travels on its controller's connection, whatever that connection uses.@@ -503,7 +551,7 @@ class AgentConnectionRegistry:scope: Scope,delivery_filter: DeliveryFilter,spawn_capable: bool,- cursor: int,+ position: Position,declaration: ClientDeclaration,expected_generation: int | None,transport: Transport = "websocket",@@ -561,7 +609,8 @@ class AgentConnectionRegistry:existing.scope = scopeexisting.delivery_filter = delivery_filterexisting.spawn_capable = spawn_capable- existing.cursor = cursor+ existing.position = dict(position)+ existing.ticket = 0existing.last_beat = time.monotonic()existing.closure = Noneexisting.stream_attached = True@@ -597,7 +646,7 @@ class AgentConnectionRegistry:scope=scope,delivery_filter=delivery_filter,spawn_capable=spawn_capable,- cursor=cursor,+ position=dict(position),last_beat=now,opened_at=now,stream_attached=True,@@ -752,10 +801,13 @@ class AgentConnectionRegistry:self,agent_id: str,connection_id: str,- cursor: int,generation: int | None,) -> AgentConnection:- """Record a client tick and its cursor.+ """Record a client tick: the client is still there.++ A tick says nothing about how far the client has read. The connection's+ position is moved only by the stream, as it sends, and a client that+ drops resumes from the position it sends when it reopens.Rejects a tick for a connection with no stream: the client is alive butreceiving nothing, and must be told to reopen rather than left believing@@ -765,9 +817,9 @@ class AgentConnectionRegistry:actually attached to. Sharing an id is what makes takeover work, and itis also what makes a displaced client's tick indistinguishable from thewinner's — same id, same token. Unfenced, the loser keeps the- connection alive on the winner's behalf and, because a higher cursor is- adopted, drags the winner past events it was never sent. Nothing is- mutated before the check, so a refused tick costs the winner nothing.+ connection alive on the winner's behalf, so the winner is never told it+ was dropped. Nothing is mutated before the check, so a refused tick+ costs the winner nothing.`None` is a tick that cannot be fenced, and it is accepted only from aconnection whose holder is a client built before the fence existed.@@ -793,8 +845,6 @@ class AgentConnectionRegistry:raise NoStreamAttachedError(connection_id)conn.last_beat = time.monotonic()conn.beats += 1- if cursor > conn.cursor:- conn.cursor = cursorreturn conndef require(self, agent_id: str, connection_id: str) -> AgentConnection:diff --git a/core/switch_core/bridges/agent/protocol/agent_core.py b/core/switch_core/bridges/agent/protocol/agent_core.pyindex 1fe21ed8e..a3b22cdd1 100644--- a/core/switch_core/bridges/agent/protocol/agent_core.py+++ b/core/switch_core/bridges/agent/protocol/agent_core.py@@ -2354,6 +2354,7 @@ class AgentCore:await self.agent_session_store.touch_heartbeat(session, agent_id, None)await session.commit()return await self.event_buffer.poll(+ require_tenant_id(),agent_id,timeout=timeout,rooms=await self._rooms_agent_is_in(agent_id),@@ -2377,6 +2378,7 @@ class AgentCore:agent."""return await self.event_buffer.poll_notifications(+ require_tenant_id(),agent_id,timeout=timeout,rooms=await self._rooms_agent_is_in(agent_id),@@ -2406,7 +2408,9 @@ class AgentCore:the long-poll cadence so the TTL can stay short."""await self.require_room_member(agent_id, room_id)- return await self.event_buffer.poll_room(agent_id, room_id, timeout=timeout)+ return await self.event_buffer.poll_room(+ require_tenant_id(), agent_id, room_id, timeout=timeout+ )async def report_events(self,diff --git a/core/switch_core/bridges/agent/protocol/agent_event_listener.py b/core/switch_core/bridges/agent/protocol/agent_event_listener.pynew file mode 100644index 000000000..37641cd39--- /dev/null+++ b/core/switch_core/bridges/agent/protocol/agent_event_listener.py@@ -0,0 +1,138 @@+"""Listens for Postgres notifications of new agent events and wakes this+process's streams for that agent.++A trigger defined in `db/agent_event_notify_ddl.py` sends a notification on the+`switch_agent_event` channel for every new row in `agent_events`. The process+that writes an agent's event is often not the process that holds the agent's+connection, so every process listens here and rings the agent's doorbell+(`EventBuffer.ring`). The stream behind the connection then reads the rows+past its position from the table.++A notification only wakes a stream; the event itself is always read from the+table. If a notification is lost, the stream finds the event when its wait+times out and it reads again, so the event arrives later but still arrives.+Notifications sent while the listening connection is down are lost, so after+every reconnect every stream in this process is woken to look for events it+may have missed.++Connection handling follows `MessageListener`: a dedicated connection outside+the pool, a periodic heartbeat query, and reconnects with a capped backoff.+"""++from __future__ import annotations++import asyncio+import contextlib+import json+import logging+from collections.abc import Callable+from typing import TYPE_CHECKING, Any++from switch_core.db.agent_event_notify_ddl import AGENT_EVENT_CHANNEL++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncEngine++ from switch_core.bridges.agent.protocol.event_buffer import EventBuffer++logger = logging.getLogger(__name__)++HEARTBEAT_SECONDS = 20.0+HEARTBEAT_TIMEOUT_SECONDS = 60.0+RECONNECT_BACKOFF_BASE = 1.0+RECONNECT_BACKOFF_CAP = 15.0++EngineFactory = Callable[[], "AsyncEngine"]+++class AgentEventListener:+ def __init__(self, engine_factory: EngineFactory, buffer: EventBuffer) -> None:+ self._engine_factory = engine_factory+ self._buffer = buffer+ self._task: asyncio.Task[None] | None = None+ self._running = False+ self.connected = asyncio.Event()++ async def start(self) -> None:+ if self._running:+ raise RuntimeError("AgentEventListener is already started")+ self._running = True+ self._task = asyncio.create_task(+ self._listen_forever(), name="agent-event-listener"+ )++ async def stop(self) -> None:+ self._running = False+ if self._task is not None:+ self._task.cancel()+ with contextlib.suppress(asyncio.CancelledError):+ await self._task+ self._task = None+ self.connected.clear()++ 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(+ "Agent event 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 agent event listener; "+ "LISTEN needs asyncpg directly"+ )+ await driver.add_listener(AGENT_EVENT_CHANNEL, self._on_notify)+ try:+ self._buffer.ring_everyone()+ self.connected.set()+ while self._running:+ await asyncio.sleep(HEARTBEAT_SECONDS)+ await driver.execute(+ "SELECT 1", timeout=HEARTBEAT_TIMEOUT_SECONDS+ )+ finally:+ self.connected.clear()+ with contextlib.suppress(Exception):+ await driver.remove_listener(+ AGENT_EVENT_CHANNEL, self._on_notify+ )+ finally:+ await engine.dispose()++ def _on_notify(+ self, _connection: Any, _pid: int, _channel: str, payload: str+ ) -> None:+ """Handle one notification by ringing the agent's doorbell.++ asyncpg calls this from the connection's read loop, so it does nothing+ that waits and returns straight away.+ """+ try:+ agent_id = json.loads(payload)["agent_id"]+ except (ValueError, TypeError, KeyError):+ logger.warning(+ "Ignoring an unreadable agent event announcement: %r", payload[:200]+ )+ return+ self._buffer.ring(agent_id)diff --git a/core/switch_core/bridges/agent/protocol/controller_presence.py b/core/switch_core/bridges/agent/protocol/controller_presence.pyindex d5df3250a..afa4e1fe2 100644--- a/core/switch_core/bridges/agent/protocol/controller_presence.py+++ b/core/switch_core/bridges/agent/protocol/controller_presence.py@@ -161,6 +161,10 @@ class ControllerConnection:stream_token: int = 0closure: Closure | None = Nonewake: asyncio.Event = field(default_factory=asyncio.Event)+ # How far the stream on this connection has sent each attached agent's own+ # events. A beat's confirmed cursor is lowered to it, in memory, so a beat+ # costs no database query.+ sent_cursors: dict[str, int] = field(default_factory=dict)# Frames owed to the stream, written on its next pass.session_commands: list[tuple[str, dict[str, Any]]] = field(default_factory=list)detached: dict[str, str] = field(default_factory=dict)diff --git a/core/switch_core/bridges/agent/protocol/controller_stream.py b/core/switch_core/bridges/agent/protocol/controller_stream.pyindex 195e350d2..3aeaced83 100644--- a/core/switch_core/bridges/agent/protocol/controller_stream.py+++ b/core/switch_core/bridges/agent/protocol/controller_stream.py@@ -97,6 +97,11 @@ class _Attached:outcomes: dict[tuple[str, str], Outcome] = field(default_factory=dict)resync: bool = Falseunsubscribe: Callable[[], None] | None = None+ # Rooms this stream has already passed to `EventBuffer.ensure_counting`,+ # which gives the agent an unread-count baseline for the room in+ # `agent_room_reads`. Each delivery pass calls it only for rooms not in+ # this set, so it does not write to the database for every room each time.+ counted: set[str] = field(default_factory=set)def _eviction(closure: Closure) -> dict[str, Any]:@@ -151,6 +156,11 @@ class _ControllerStream:self._rooms_of = rooms_ofself._idle = idle_secondsself._tenant_id = current_tenant_id()+ if self._tenant_id is None:+ raise RuntimeError(+ "A controller stream runs inside its controller's tenant"+ )+ self._tenant: str = self._tenant_idself._attached: dict[str, _Attached] = {}async def run(self, opening: dict[str, Any]) -> AsyncGenerator[ControllerFrame]:@@ -202,7 +212,7 @@ class _ControllerStream:delivered = Falsefor attached in list(self._attached.values()):- for raw in self._deliver(attached):+ for raw in await self._deliver(attached):delivered = Trueyield rawif delivered:@@ -247,6 +257,7 @@ class _ControllerStream:# Bound here again later, it starts at its head: what it missed in# between was never this controller's.conn.resume_cursors.pop(agent_id, None)+ conn.sent_cursors.pop(agent_id, None)if attached.unsubscribe is not None:attached.unsubscribe()frames.append(@@ -271,7 +282,7 @@ class _ControllerStream:continuerooms = await self._rooms_of(agent_id)self._presence.set_rooms(agent_id, rooms)- head = self._buffer.head(agent_id)+ head = await self._buffer.head(self._tenant, agent_id)requested = conn.resume_cursors.get(agent_id)cursor = head if requested is None else requestedgaps: list[dict[str, Any]] = []@@ -285,7 +296,6 @@ class _ControllerStream:head,)cursor = head- self._buffer.mark_restarted(agent_id)gaps.append({"agent_id": agent_id,@@ -298,22 +308,23 @@ class _ControllerStream:"the restart are gone in every room — re-read room context",})- lost = self._buffer.rooms_dropped_after(agent_id, cursor)- if lost:- resumed_at = max(self._buffer.oldest_retained(agent_id) - 1, 0)+ try:+ await self._buffer.check_cursor(self._tenant, agent_id, cursor)+ except CursorExpiredError as exc:gaps.append({"agent_id": agent_id,"from_sequence": cursor,- "resumed_at": resumed_at,- "rooms": list(lost),+ "resumed_at": exc.resume_after,+ "rooms": list(exc.rooms),"all_rooms": False,"reason": "events older than the retention window were ""dropped; re-read room context",})- cursor = resumed_at+ cursor = exc.resume_afterconn.resume_cursors[agent_id] = cursor+ conn.sent_cursors[agent_id] = cursorattached = _Attached(agent_id=agent_id,reader_id=self._presence.holder_id(binding),@@ -321,12 +332,13 @@ class _ControllerStream:)self._subscribe_outcomes(attached)self._attached[agent_id] = attached- # The conversation this reader has not seen starts where its- # delivery does, which is what the per-agent stream counts from.- for room_id in rooms:- self._buffer.ensure_counting(- agent_id, attached.reader_id, room_id, cursor+ # Give each of the agent's rooms that has no unread-count baseline+ # yet a baseline at the room's newest message.+ for room_id in rooms - attached.counted:+ await self._buffer.ensure_counting(+ self._tenant, agent_id, attached.reader_id, room_id)+ attached.counted.add(room_id)frames.append(frame("agent.attached",@@ -373,19 +385,31 @@ class _ControllerStream:)return frames- def _deliver(self, attached: _Attached) -> list[ControllerFrame]:+ async def _deliver(self, attached: _Attached) -> list[ControllerFrame]:agent_id = attached.agent_id- for room_id in self._presence.rooms(agent_id):- self._buffer.ensure_counting(- agent_id, attached.reader_id, room_id, attached.cursor+ for room_id in self._presence.rooms(agent_id) - attached.counted:+ await self._buffer.ensure_counting(+ self._tenant, agent_id, attached.reader_id, room_id)+ attached.counted.add(room_id)+ # Take the number of the newest of the agent's own events before+ # reading, and read no further than it. A read that finds nothing moves+ # the cursor up to this number. An event added to `agent_events` while+ # the read runs is numbered above it, so the cursor does not skip that+ # event.+ bound = await self._buffer.head(self._tenant, agent_id)try:- pending = self._buffer.read_from(- agent_id, attached.cursor, limit=CATCH_UP_BATCH+ pending = await self._buffer.read_from(+ self._tenant,+ agent_id,+ attached.cursor,+ limit=CATCH_UP_BATCH,+ through_seq=bound,)except CursorExpiredError as exc:- resumed_at = max(exc.oldest - 1, 0)+ resumed_at = exc.resume_afterattached.cursor = resumed_at+ self._conn.sent_cursors[agent_id] = resumed_atreturn [frame("agent.gap",@@ -403,16 +427,20 @@ class _ControllerStream:# Events above the cursor that are no longer held — a room the# agent left takes its events with it — are passed, or every pass# would find work it can never read and spin.- attached.cursor = max(attached.cursor, self._buffer.head(agent_id))+ attached.cursor = max(attached.cursor, bound)+ self._conn.sent_cursors[agent_id] = attached.cursorreturn []frames: list[ControllerFrame] = []for item in pending:data = item.event.model_dump(mode="json")data["sequence"] = item.seqif item.notifiable:- unread = self._buffer.unread(agent_id, item.room_id, item.seq)+ unread = await self._buffer.unread(+ self._tenant, agent_id, item.room_id, item.room_seq+ )data["missed"] = {"count": unread.count, "reason": unread.reason}attached.cursor = item.seq+ self._conn.sent_cursors[agent_id] = item.seqframes.append(frame("agent.event",@@ -421,19 +449,20 @@ class _ControllerStream:)return frames- def _has_work(self) -> bool:+ async def _has_work(self) -> bool:conn = self._conn- return (+ if (conn.closure is not Noneor conn.stream_token != self._tokenor bool(conn.detached or conn.rooms_changed or conn.session_commands)or self._presence.agents_of(conn.controller_id) != set(self._attached)or any(a.outcomes or a.resync for a in self._attached.values())- or any(- self._buffer.head(a.agent_id) > a.cursor- for a in self._attached.values()- )- )+ ):+ return True+ if not self._attached:+ return False+ heads = await self._buffer.heads(self._tenant, set(self._attached))+ return any(heads.get(a.agent_id, 0) > a.cursor for a in self._attached.values())async def _wait(self) -> bool:"""Wait for an event, a nudge or a change to the connection. False when@@ -444,7 +473,7 @@ class _ControllerStream:self._conn.wake.clear()# Re-checked after clearing: anything that arrived between the last# read and the clear would otherwise wait for the idle timeout.- if self._has_work() or self._nudges.wake.is_set():+ if await self._has_work() or self._nudges.wake.is_set():return Truewaiters = [asyncio.ensure_future(event.wait())diff --git a/core/switch_core/bridges/agent/protocol/event_buffer.py b/core/switch_core/bridges/agent/protocol/event_buffer.pyindex 66bcd3b73..7a8867b42 100644--- a/core/switch_core/bridges/agent/protocol/event_buffer.py+++ b/core/switch_core/bridges/agent/protocol/event_buffer.py@@ -1,30 +1,45 @@-"""Per-agent sequenced event buffer (CHOO-1857).--Replaces the destructive per-room `asyncio.Queue` fan-out. Events are appended-with a monotonically increasing sequence number and stay readable until they-age out of the retention window or the per-agent cap forces them out. Reading-never removes, so several readers can consume the same events independently and-a reader that drops off can resume from its cursor.--Retention is deliberately independent of what readers have confirmed: an event-remains readable for its window whether or not somebody has already consumed-it. Cursors record progress; they do not decide what is kept.--The buffer lives in memory: it cannot outlive the process, and persisting it-would recreate the stale-state bug this design removes. `switch-core` is-single-process by construction, so an in-process structure is authoritative.-It sits behind a narrow surface (`enqueue`, `read_from`, `wait`, `confirm`)-so it can be moved to Postgres later without touching its callers.--Overflow is never silent: when the cap forces events out, the rooms that lost-events are flagged and the next reader to ask is told it missed events there.--How far behind a reader is in a room is derived here rather than tallied: every-event is retained with its room and whether it was addressed, so "unaddressed-traffic in this room since you last caught up" is a scan between two sequence-numbers at the moment somebody asks. The only thing recorded is where each room-was last caught up, which is one number and cannot drift out of step with the-events it describes.+"""An agent's events (CHOO-1857), stored in Postgres and read by position.++The events an agent receives come from two tables.++**The agent's own events.** These are the events meant for the agent: a+message addressed to it, a room_join in a room where it listens for joins, a+task it takes part in, a command sent to it. The agent's consumer+(`clients/agent_consumer.py`) decides whether a room row is one of these when+the row is delivered to it live. The decision cannot be repeated later, because+the addressing policy, budgets and role leases it depended on may have changed+by then, so the consumer stores it as a row in `agent_events`. These rows are+called own events. Each agent numbers its own events in its own sequence+(`agent_events.seq`).++**The rest of the conversation.** Everything else said in the agent's rooms is+already stored in `messages`, numbered per room (`messages.seq`), and is read+from there when a reader asks for it. Nothing is copied per agent, so a message+in a busy room costs one write, not one write per agent in the room.++A reader's position (`positions.py`) records how far it has read: one number+for the agent's own events and one number per room for the conversation. Reading+deletes nothing, so several readers can consume the same events independently,+and a reader that disconnects resumes from its position, on any process and+after a restart.++`expire` deletes own events once they are older than the retention window, never+because a reader has confirmed them. Every deletion is recorded: the newest+deleted own event per agent and room goes into `agent_event_drops`, and a reader+that later resumes from before that own event is told which rooms it missed events+in.++When an own event is inserted, Postgres sends a notification+(`db/agent_event_notify_ddl.py`). A listener in every process receives it and+sets that agent's doorbell, an in-memory `asyncio.Event`, so the process that+holds the agent's connection wakes up and reads the new own event from the table.+The doorbell only wakes readers; the table is the record.++An unread count says how much unaddressed conversation in a room the agent has+not caught up on. It is counted from `messages` when asked: the room's messages+after the agent's baseline for the room, minus the ones that became own events. The+baseline (`caught_up_seq`) and the reader currently in the room are stored in+`agent_room_reads`."""from __future__ import annotations@@ -32,78 +47,166 @@ from __future__ import annotationsimport asyncioimport loggingimport time-from collections import deque-from dataclasses import dataclass-+from dataclasses import dataclass, field+from datetime import UTC, datetime, timedelta+from typing import TYPE_CHECKING, Any, cast++from sqlalchemy import BigInteger, delete, func, literal, select, text+from sqlalchemy.dialects.postgresql import insert+from sqlalchemy.exc import DBAPIError, InterfaceError, OperationalError+from sqlalchemy.exc import TimeoutError as PoolTimeoutError++from switch_core.attachments import parse_attachment_group+from switch_core.bridges.agent.protocol.message_events import (+ attachment_ref,+ message_event,+ room_join_event,+)+from switch_core.bridges.agent.protocol.positions import (+ OWN_EVENTS,+ Position,+ merged,+ room_of,+ room_source,+)from switch_core.bridges.agent.protocol.types import AgentEvent-from switch_core.logging_context import log_context+from switch_core.clients.admin_messages import platform_replies_in_channel+from switch_core.db.models import TICKET_FLOOR as TICKET_FLOOR+from switch_core.db.models import (+ Agent,+ AgentEventDrop,+ AgentEventHead,+ AgentEventRow,+ AgentPollPosition,+ AgentPositionTicket,+ AgentRoomRead,+ Client,+ ClientRoom,+ Message,+ MessageAttachment,+ Room,+)+from switch_core.db.session_scope import tenant_sessionfrom switch_core.observability.catalogue import (AGENT_BUFFER_SCAN_DURATION,AGENT_BUFFER_SCANNED,AGENT_EVENTS_DROPPED,)from switch_core.observability.metrics import metrics+from switch_core.transport.stored import to_inbound+from switch_core.transport.types import InboundMedia, InboundMembership, InboundMessage-logger = logging.getLogger(__name__)--# Maximum events retained per agent. Beyond this the oldest are dropped and the-# agent is flagged with a gap. Sized for chat-rate traffic: an agent would have-# to accumulate this many unread events before any reader catches up.-DEFAULT_MAX_EVENTS_PER_AGENT = 2000+if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker-# How long an event stays readable. This is the resume window: a client that-# reconnects within it recovers every event it missed, and one that reconnects-# later is told it has a gap rather than handed a partial stream.-DEFAULT_RETENTION_SECONDS = 15 * 60+logger = logging.getLogger(__name__)-# An agent past the cap drops an event on every enqueue, and a warning per drop-# is a log line per delivered message. One per agent per interval says the same.-OVERFLOW_WARNING_INTERVAL_SECONDS = 60.0+# How long an own event stays in `agent_events` before `expire` deletes it. A client+# that reconnects within this window receives every own event it missed; a client+# that reconnects later is told it has a gap instead of being handed an+# incomplete stream. This module never deletes rows from `messages`, so the+# conversation has no such window.+DEFAULT_RETENTION_SECONDS = 24 * 60 * 60++# How old a row in `messages` must be before it is delivered as conversation.+# The agent's consumer decides, when the row is delivered to it, whether the+# row becomes an own event. If a reader delivered the row as conversation before+# that decision and the consumer then made it an own event, the agent would receive+# the same message twice. The wait is skipped when the agent already has a+# own event for a later row in the same room, because the consumer handles a room's+# rows in order and has therefore decided this one. The consumer normally+# decides within milliseconds, so the duplicate only happens when it stalls+# for longer than this; the agent then sees the message twice, never zero+# times.+CONVERSATION_SETTLE_SECONDS = 2.0++# Several files posted as one message are stored as separate rows in+# `messages` that share an attachment group. A reader waits this many seconds+# beyond the settle time for the rest of the group, then delivers the files+# that did arrive as one message marked incomplete. The agent's consumer waits+# the same time (`ATTACHMENT_GROUP_TIMEOUT_SECONDS`) when it assembles a group.+CONVERSATION_GROUP_GRACE_SECONDS = 5.0++# Some clients can store only one integer as their place in the stream. Such a+# client is sent a ticket: the id of a row in `agent_position_tickets` that+# holds the full position. Ticket ids start at `TICKET_FLOOR`, above every own+# event number the server issues (`db/models.py` derives both from the range of+# `agent_event_boot`), so the server can tell a ticket from an own event number+# when a client sends one back._READ = {"operation": "read"}_UNREAD = {"operation": "unread"}-# Why an unread count is absent or incomplete. Never a bare zero: a reader that-# is told nothing went by must be able to trust it.-NO_BASELINE = "nothing recorded what you had already seen in this room"-RESTARTED = (- "the server restarted, so what you had already seen in this room is no longer known"+# The stored poll position moved forward by the new one, source by source,+# never back: `positions.merged`, written in SQL so that it happens inside the+# upsert and two overlapping saves cannot undo each other.+_MERGED_POLL_POSITION = text(+ "(SELECT jsonb_object_agg(source, GREATEST("+ "COALESCE((agent_poll_positions.position ->> source)::bigint, -1), "+ "COALESCE((excluded.position ->> source)::bigint, -1))) "+ "FROM (SELECT jsonb_object_keys(agent_poll_positions.position) AS source "+ "UNION SELECT jsonb_object_keys(excluded.position)) AS sources)")-COUNTED_FROM_A_HOLE = (- "older events in this room were dropped before anything counted them, so "- "this is a floor rather than a total"++# How long `enqueue` waits before each retry of a write that failed because the+# database connection or the connection pool did. After the last, the error is+# raised.+ENQUEUE_RETRY_DELAYS = (0.5, 2.0, 5.0)++# The reason sent when no unread count can be given, because nothing in+# `agent_room_reads` says how far the agent had read the room. The count is+# left empty rather than set to zero, so that a zero always means nothing was+# missed.+NO_BASELINE = "nothing recorded what you had already seen in this room"+# The reason sent when a count is a lower bound. Own events older than the+# retention window have been deleted, so the count cannot tell which older+# messages were addressed to the agent and starts at the window instead.+COUNTED_FROM_WINDOW = (+ "counted over the retention window only; you have not caught up on this "+ "room for longer than that")class CursorExpiredError(Exception):- """A reader asked to resume from a point the buffer no longer retains.+ """A reader asked to resume from an own event number older than the oldest own event kept.Raised rather than fast-forwarding to head: a client that has missed eventsmust be told, never handed a stream that looks complete."""def __init__(- self, agent_id: str, requested: int, oldest: int, rooms: tuple[str, ...]+ self,+ agent_id: str,+ requested: int,+ oldest: int,+ rooms: tuple[str, ...],+ resume_after: int,) -> None:super().__init__(- f"cursor {requested} for agent {agent_id} is older than the retained "- f"buffer (oldest retained: {oldest}); missed events in "+ f"cursor {requested} for agent {agent_id} is older than what is "+ f"retained (oldest retained: {oldest}); missed events in "f"{', '.join(rooms)}, re-read context")self.agent_id = agent_idself.requested = requestedself.oldest = oldestself.rooms = rooms+ # The own-events number a reader resumes after once it has been told+ # about the gap: past every number `expire` deleted. It is not+ # `oldest - 1`, because when retention has deleted all of the agent's+ # own events there is no oldest one, and a reader moved to 0 would hit+ # the same deleted numbers on its next read and be told again, forever.+ self.resume_after = resume_afterdef is_notifiable(event: AgentEvent) -> bool:"""Whether an event is addressed at the agent rather than ambient context.Addressed messages, task events, and room_join events the agent is- configured to listen for. Excludes unaddressed chatter and admin command- events. This is the `addressed` delivery filter: a supervising connection- watching every room wants only these, while a session in a single room- wants everything.+ configured to listen for. Excludes conversation and admin command events.+ This is the `addressed` delivery filter: a supervising connection watching+ every room wants only these, while a session in a single room wants+ everything."""if event.type == "message":return getattr(event.payload, "addressed", False)@@ -117,13 +220,39 @@ def is_notifiable(event: AgentEvent) -> bool:@dataclass(frozen=True)class BufferedEvent:- """An event with its position in the agent's stream."""+ """An event together with the source it was read from.++ `source` is `positions.OWN_EVENTS` for an event read from the agent's own events in+ `agent_events`, or `room_source(room_id)` for one read from a room's+ conversation in `messages`. `seq` is the event's number in that source;+ once the event is delivered, the reader's position for that source moves+ to it. `room_seq` is the `messages.seq` of the room row the event came+ from. `at` is when the event happened, and is used to order events from+ different sources against each other.+ """seq: introom_id: strevent: AgentEventnotifiable: bool- appended_at: float+ source: str = OWN_EVENTS+ room_seq: int = 0+ at: float = 0.0+++@dataclass(frozen=True)+class Conversation:+ """The result of reading the rooms' conversation from `messages`.++ `events` holds what is to be delivered. `through` maps each room to the+ last row the read examined, whether or not that row was delivered. Rows+ that are not conversation (the agent's own messages, other kinds of event,+ rows that are already own events) are skipped, but they still count as read, so+ the reader's position moves past them and they are not examined again.+ """++ events: list[BufferedEvent] = field(default_factory=list)+ through: dict[str, int] = field(default_factory=dict)@dataclass(frozen=True)@@ -141,108 +270,141 @@ class Reader:is_session: bool-@dataclass-class _Counting:- """What one room is behind by for one agent, and who is entitled to clear it.-- `baseline` is the sequence number the room was last caught up through, or- None for "cannot be said". `occupant` is the session or connection in the- room now: it decides whose `caught_up` counts, and nothing else.- """-- occupant: Reader- baseline: int | None--@dataclass(frozen=True)class Unread:"""Unaddressed messages a reader has yet to catch up on, in one room.`count` is None when nothing about it can be stated — better than a zero- the reader would believe. `reason` says why a count is absent, or why one- that is present is only a floor; it is None exactly when the count is- complete.+ the reader would believe. `reason` explains a count that is missing+ (`NO_BASELINE`) or only a lower bound (`COUNTED_FROM_WINDOW`), and is None+ exactly when the count is complete."""count: int | Nonereason: str | None+def _epoch(when: datetime | None) -> float:+ return when.timestamp() if when is not None else 0.0+++def message_key(row: Message) -> str:+ """The key of the message a `messages` row belongs to.++ Several files posted as one message are stored as separate rows that share+ an attachment group, so their key is the group id. Any other row's key is+ its own transport event id. Own events store the same key in+ `agent_events.message_key`, which is how a row is matched to its own event.+ """+ group = parse_attachment_group(row.content or {})+ return group[0] if group is not None else row.transport_event_id+++# `message_key` as a SQL expression over `messages m`, so that `_UNREAD_SQL`+# can count in the database without loading every row.+_MESSAGE_KEY_SQL = (+ "COALESCE(m.content->'com.switch.attachment_group'->>'id', m.transport_event_id)"+)++_UNREAD_SQL = text(+ f"""+ SELECT count(DISTINCT {_MESSAGE_KEY_SQL})+ FROM messages m+ WHERE m.room_id = :room_id+ AND m.seq > :baseline+ AND m.seq <= :through+ AND m.seq > 0+ AND m.event_type = 'm.room.message'+ AND m.sender_id <> :me+ AND NOT EXISTS (+ SELECT 1 FROM agent_events e+ WHERE e.agent_id = :agent_id+ AND e.room_id = :room_id+ AND e.type = 'message'+ AND e.message_key = {_MESSAGE_KEY_SQL}+ AND e.room_seq >= m.seq+ )+ """+)++class EventBuffer:def __init__(self,- max_events_per_agent: int = DEFAULT_MAX_EVENTS_PER_AGENT,- retention_seconds: float = DEFAULT_RETENTION_SECONDS,+ session_factory: async_sessionmaker[AsyncSession],*,sequence_base: int,+ retention_seconds: float = DEFAULT_RETENTION_SECONDS,+ settle_seconds: float = CONVERSATION_SETTLE_SECONDS,) -> None:- # Each boot numbers from its own base, above every earlier boot's, so a- # sequence number is never reused and a cursor from a previous boot is- # recognisably below this one's floor.+ self._session_factory = session_factory+ # `sequence_base` comes from a database sequence that advances on every+ # boot (`main.py`), so it is above every number an earlier boot handed+ # out. An agent's first own event is numbered from it. A client still holding+ # a number from before the agent had any own events here therefore holds a+ # number below `sequence_floor`, and is recognised as older than every+ # own event. Later own events are numbered from the agent's row in+ # `agent_event_heads`, so their numbers survive restarts.self.sequence_floor = sequence_base + 1- self.boot = sequence_base >> 32- self._max_events = max_events_per_agentself._retention_seconds = retention_seconds- self._events: dict[str, deque[BufferedEvent]] = {}- self._next_seq: dict[str, int] = {}+ self._settle_seconds = settle_seconds+ # The doorbells of this process: one `asyncio.Event` per agent, set to+ # wake this process's readers of that agent when an own event is inserted.+ # `enqueue` sets it for own events written here, and the notification+ # listener sets it for own events written by other processes. The events+ # themselves are always read from `agent_events`.self._notify: dict[str, asyncio.Event] = {}- # reader id -> last sequence number that reader has confirmed. Used to- # resume a reader and to report progress; deliberately NOT used to- # decide what to drop. Retention is by age and cap alone, so a reader- # that connects after an event was already consumed by someone else- # still sees it.- self._cursors: dict[str, dict[str, int]] = {}- # agent -> room -> highest sequence number dropped from that room. Any- # reader resuming from at or below it has missed events there, and- # knowing which room is what lets the warning name one.- self._dropped_through: dict[str, dict[str, int]] = {}- # agent -> room -> how far behind that room is, and who is in it.- # Distinct from the delivery cursor, which records what the server has- # written out: the two are allowed to diverge, and that divergence is- # what makes a count per-room rather than per-connection.- #- # Keyed by room rather than by reader because at most one session of an- # agent may be in a room, so the room names the count on its own — and- # the reader cannot name it once an agent has a single inbound- # connection, which every one of its sessions arrives on. What went- # past unread in a room belongs to the room: a session taking it over- # inherits what the agent has yet to catch up on there rather than- # starting at a zero nothing justifies.- self._counting: dict[str, dict[str, _Counting]] = {}- # Agents whose baselines were lost with a previous life of this- # process. A room counted for the first time after that starts unknown- # rather than at a number: the conversation it missed before the- # restart is gone from the buffer, so a count taken from what is left- # would be a floor presented as a total.- self._restarted: set[str] = set()- # agent -> when its last overflow warning was logged, and how many- # overflow drops have gone unlogged since.- self._overflow_warned_at: dict[str, float] = {}- self._overflow_unlogged: dict[str, int] = {}++ @property+ def settle_seconds(self) -> float:+ return self._settle_seconds# ------------------------------------------------------------------# Producing# ------------------------------------------------------------------- def enqueue(self, agent_id: str, room_id: str, event: AgentEvent) -> int:- """Append an event for an agent and return its sequence number."""- seq = self._next_seq.get(agent_id, self.sequence_floor)- if seq >= self.sequence_floor - 1 + (1 << 32):- raise RuntimeError(- "Agent event sequence range exhausted; restart the server."- )- self._next_seq[agent_id] = seq + 1-- events = self._events.setdefault(agent_id, deque())- events.append(- BufferedEvent(- seq=seq,- room_id=room_id,- event=event,- notifiable=is_notifiable(event),- appended_at=time.monotonic(),- )- )+ async def enqueue(+ self,+ tenant_id: str,+ agent_id: str,+ room_id: str,+ event: AgentEvent,+ *,+ room_seq: int,+ message_key: str | None,+ ) -> int:+ """Store an event meant for the agent as an own event, and return its number.++ The number comes from the agent's row in `agent_event_heads`, which is+ advanced in the same transaction as the insert into `agent_events`, so+ numbers are contiguous and never handed out twice, even after older+ own events have been deleted. `room_seq` and `message_key` identify the+ `messages` row the event came from, so that conversation reads and+ unread counts can recognise that row as already delivered.++ A write that fails because the database connection or the pool did is+ retried after each of `ENQUEUE_RETRY_DELAYS`. The consumer has already+ moved past the room row by the time it calls this, so an event not+ stored here is never stored.+ """+ for delay in (*ENQUEUE_RETRY_DELAYS, None):+ try:+ seq = await self._store_own_event(+ tenant_id, agent_id, room_id, event, room_seq, message_key+ )+ break+ except Exception as exc:+ if delay is None or not _transient(exc):+ raise+ logger.warning(+ "[EVENT-BUF] storing an own event for agent %s in room %s "+ "failed (%s); retrying in %ss",+ agent_id,+ room_id,+ type(exc).__name__,+ delay,+ )+ await asyncio.sleep(delay)logger.debug("[EVENT-BUF] append agent=%s room=%s type=%s seq=%s",agent_id,@@ -250,62 +412,119 @@ class EventBuffer:event.type,seq,)- self._trim(agent_id)- self._wake(agent_id)+ self.ring(agent_id)+ return seq++ async def _store_own_event(+ self,+ tenant_id: str,+ agent_id: str,+ room_id: str,+ event: AgentEvent,+ room_seq: int,+ message_key: str | None,+ ) -> int:+ """Number one own event and insert it, in one transaction."""+ async with tenant_session(self._session_factory, tenant_id) as session:+ claim = (+ insert(AgentEventHead)+ .values(+ tenant_id=tenant_id,+ agent_id=agent_id,+ first_seq=self.sequence_floor,+ last_seq=self.sequence_floor,+ )+ .on_conflict_do_update(+ index_elements=[AgentEventHead.agent_id],+ set_={"last_seq": AgentEventHead.last_seq + 1},+ )+ .returning(AgentEventHead.last_seq)+ )+ seq = (await session.execute(claim)).scalar_one()+ session.add(+ AgentEventRow(+ tenant_id=tenant_id,+ agent_id=agent_id,+ seq=seq,+ room_id=room_id,+ room_seq=room_seq,+ message_key=message_key,+ type=event.type,+ payload=event.model_dump(mode="json"),+ notifiable=is_notifiable(event),+ )+ )+ await session.commit()return seq# ------------------------------------------------------------------- # Consuming+ # The agent's own events# ------------------------------------------------------------------- def read_from(+ async def read_from(self,+ tenant_id: str,agent_id: str,after_seq: int,*,rooms: set[str] | None = None,notifiable_only: bool = False,limit: int | None = None,+ through_seq: int | None = None,) -> list[BufferedEvent]:- """Return retained events after `after_seq`, oldest first.-- `rooms=None` means every room the agent has events for; otherwise only- the given rooms. Raises `CursorExpiredError` if `after_seq` predates- what the buffer still holds.-- The window is enforced here as well as on append, because an agent- that goes quiet appends nothing and would otherwise go on serving- events long past it. Elsewhere the promise that an event stops being- readable when its window ends is relied on to decide how long a record- about it has to be kept.+ """The agent's own events numbered after `after_seq`, oldest first.++ `rooms=None` reads own events from every room; otherwise only own events from the+ given rooms. `through_seq`, when given, is an upper bound the caller+ read before calling. The read stops there, so the caller can move its+ position to that bound knowing it was handed every own event up to it.+ Raises `CursorExpiredError` if `expire` has deleted own events numbered+ after `after_seq`."""started = time.perf_counter()- self._trim(agent_id)- self._check_cursor(agent_id, after_seq)-- out: list[BufferedEvent] = []- events = self._events.get(agent_id, ())- scanned = len(events)- for index, item in enumerate(events):- if item.seq <= after_seq:- continue- if rooms is not None and item.room_id not in rooms:- continue- if notifiable_only and not item.notifiable:- continue- out.append(item)- if limit is not None and len(out) >= limit:- scanned = index + 1- break- self._record_scan(_READ, scanned, started)+ query = (+ select(AgentEventRow)+ .where(AgentEventRow.agent_id == agent_id, AgentEventRow.seq > after_seq)+ .order_by(AgentEventRow.seq)+ )+ if rooms is not None:+ query = query.where(AgentEventRow.room_id.in_(rooms))+ if notifiable_only:+ query = query.where(AgentEventRow.notifiable.is_(True))+ if through_seq is not None:+ query = query.where(AgentEventRow.seq <= through_seq)+ if limit is not None:+ query = query.limit(limit)+ async with tenant_session(self._session_factory, tenant_id) as session:+ rows = (await session.scalars(query)).all()+ # Checked after the read, not before. `expire` deletes rows and records+ # what it deleted in one transaction. A deletion that commits before+ # the read above is recorded by the time of this check, so a reader is+ # never handed the events after a deleted one as if nothing were+ # missing. Checked first, a deletion landing between the check and the+ # read would go unreported. One landing after the read is reported+ # too, though the rows were read: a spare gap, never a silent one.+ await self.check_cursor(tenant_id, agent_id, after_seq)+ out = [+ BufferedEvent(+ seq=row.seq,+ room_id=row.room_id,+ event=AgentEvent.model_validate(row.payload),+ notifiable=row.notifiable,+ source=OWN_EVENTS,+ room_seq=row.room_seq,+ at=_epoch(row.created_at),+ )+ for row in rows+ ]+ self._record_scan(_READ, len(out), started)return outasync def wait(self, agent_id: str, timeout: float) -> None:"""Block until an event is appended for the agent, or the timeout passes.- A wake-up is advisory: callers re-read from their cursor rather than- trusting this to deliver anything. The buffer is the record; this is- only the doorbell.+ A wake-up is advisory: callers re-read from their position rather than+ trusting this to deliver anything."""notify = self._notify.setdefault(agent_id, asyncio.Event())notify.clear()@@ -315,322 +534,1005 @@ class EventBuffer:returndef doorbell(self, agent_id: str) -> asyncio.Event:- """The wake-up signal for an agent, shared by every reader.+ """The agent's doorbell, shared by every reader of the agent in this process.- Set whenever an event is appended. Readers re-read from their own- cursor when woken; the signal carries no payload, so a spurious or- missed wake costs latency, never correctness.+ It is set whenever an own event is inserted for the agent, by this process or+ by another one. A reader that wakes re-reads from its own position. The+ signal carries no payload, so a spurious or missed wake-up costs+ latency, never correctness."""return self._notify.setdefault(agent_id, asyncio.Event())- def head(self, agent_id: str) -> int:- """The sequence number of the most recent event (the floor less one if none)."""- return self._next_seq.get(agent_id, self.sequence_floor) - 1+ def ring(self, agent_id: str) -> None:+ """Set the agent's doorbell in this process.- def oldest_retained(self, agent_id: str) -> int:- """Sequence number of the oldest retained event (0 if the buffer is empty)."""- events = self._events.get(agent_id)- return events[0].seq if events else 0+ `enqueue` calls this after inserting an own event, and the notification+ listener calls it when another process inserts one.+ """+ notify = self._notify.get(agent_id)+ if notify is not None:+ notify.set()- def has_gap_before(self, agent_id: str, after_seq: int) -> bool:- """Whether resuming from `after_seq` would skip dropped events."""- return bool(self.rooms_dropped_after(agent_id, after_seq))+ def ring_everyone(self) -> None:+ """Set every doorbell in this process.- def rooms_dropped_after(self, agent_id: str, after_seq: int) -> tuple[str, ...]:- """The rooms that lost events a reader at `after_seq` would have seen."""- markers = self._dropped_through.get(agent_id, {})- return tuple(sorted(room for room, seq in markers.items() if seq > after_seq))+ The notification listener calls this each time it starts listening on+ a Postgres connection, because it may have missed notifications while+ it was not listening.+ """+ for notify in self._notify.values():+ notify.set()++ async def head(self, tenant_id: str, agent_id: str) -> int:+ """The number of the agent's newest own event, or the number just+ before its first one if it has none yet. This is the agent's head."""+ query = select(AgentEventHead.last_seq).where(+ AgentEventHead.agent_id == agent_id+ )+ async with tenant_session(self._session_factory, tenant_id) as session:+ last = await session.scalar(query)+ if last is None:+ await self._start_numbering(session, {agent_id})+ last = await session.scalar(query)+ return self.sequence_floor - 1 if last is None else last++ async def heads(self, tenant_id: str, agent_ids: set[str]) -> dict[str, int]:+ """`head` for several agents in one query, for a connection that+ serves many agents."""++ def query(ids: set[str]) -> Any:+ return select(AgentEventHead.agent_id, AgentEventHead.last_seq).where(+ AgentEventHead.agent_id.in_(ids)+ )++ async with tenant_session(self._session_factory, tenant_id) as session:+ found = dict((await session.execute(query(agent_ids))).tuples().all())+ missing = agent_ids - found.keys()+ if missing:+ await self._start_numbering(session, missing)+ found.update((await session.execute(query(missing))).tuples().all())+ return {+ agent_id: found.get(agent_id, self.sequence_floor - 1)+ for agent_id in agent_ids+ }++ async def first_seq(self, tenant_id: str, agent_id: str) -> int:+ """The number of the agent's first own event.++ A number below it was handed out before the agent had any own events in+ `agent_events`, so nothing the server holds corresponds to it.+ """+ query = select(AgentEventHead.first_seq).where(+ AgentEventHead.agent_id == agent_id+ )+ async with tenant_session(self._session_factory, tenant_id) as session:+ first = await session.scalar(query)+ if first is None:+ await self._start_numbering(session, {agent_id})+ first = await session.scalar(query)+ return self.sequence_floor if first is None else first++ async def _start_numbering(+ self, session: AsyncSession, agent_ids: set[str]+ ) -> None:+ """Give each agent that has no row in `agent_event_heads` one, numbering+ its own events from this process's `sequence_floor`.++ Called the first time a process reads an agent's head, not only when+ the first own event is written. Processes started at different boots+ have different floors. If each answered from its own floor until the+ first event was written, a reader placed at the head one process+ reported could find the first event numbered below it by another+ process, and never receive it. Once the row exists, every process+ numbers the agent from it. The row is selected from `agents`, so an+ agent deleted meanwhile gets none.+ """+ await session.execute(+ insert(AgentEventHead)+ .from_select(+ [+ AgentEventHead.tenant_id,+ AgentEventHead.agent_id,+ AgentEventHead.first_seq,+ AgentEventHead.last_seq,+ ],+ select(+ Agent.tenant_id,+ Agent.id,+ literal(self.sequence_floor, BigInteger),+ literal(self.sequence_floor - 1, BigInteger),+ ).where(Agent.id.in_(agent_ids)),+ )+ .on_conflict_do_nothing(index_elements=[AgentEventHead.agent_id])+ )+ await session.commit()++ async def oldest_retained(self, tenant_id: str, agent_id: str) -> int:+ """The number of the agent's oldest own event still in `agent_events`, or 0+ if it has none."""+ async with tenant_session(self._session_factory, tenant_id) as session:+ oldest = await session.scalar(+ select(func.min(AgentEventRow.seq)).where(+ AgentEventRow.agent_id == agent_id+ )+ )+ return oldest or 0++ async def rooms_dropped_after(+ self, tenant_id: str, agent_id: str, after_seq: int+ ) -> tuple[str, ...]:+ """The rooms in which `expire` deleted own events numbered after+ `after_seq`, so a reader at `after_seq` has missed events there."""+ async with tenant_session(self._session_factory, tenant_id) as session:+ rooms = (+ await session.scalars(+ select(AgentEventDrop.room_id).where(+ AgentEventDrop.agent_id == agent_id,+ AgentEventDrop.dropped_through > after_seq,+ )+ )+ ).all()+ return tuple(sorted(rooms))# ------------------------------------------------------------------- # Reader bookkeeping+ # The rooms' conversation# ------------------------------------------------------------------- def ensure_counting(- self, agent_id: str, connection_id: str, room_id: str, from_seq: int- ) -> None:- """A connection is delivering this room: count it from `from_seq` if- nothing is counting it yet.+ async def member_rooms(self, tenant_id: str, agent_id: str) -> set[str]:+ """The rooms the agent is in now."""+ async with tenant_session(self._session_factory, tenant_id) as session:+ rooms = (+ await session.scalars(+ select(ClientRoom.room_id)+ .join(Agent, Agent.client_id == ClientRoom.client_id)+ .where(Agent.id == agent_id)+ )+ ).all()+ return set(rooms)++ async def room_heads(self, tenant_id: str, room_ids: set[str]) -> dict[str, int]:+ """Each room's highest `messages.seq`, or 0 for a room with no rows yet."""+ if not room_ids:+ return {}+ async with tenant_session(self._session_factory, tenant_id) as session:+ rows = (+ await session.execute(+ select(Message.room_id, func.max(Message.seq))+ .where(Message.room_id.in_(room_ids))+ .group_by(Message.room_id)+ )+ ).all()+ found = {room_id: head for room_id, head in rows}+ return {room_id: max(found.get(room_id) or 0, 0) for room_id in room_ids}++ async def within_rooms(+ self, tenant_id: str, position: Position+ ) -> tuple[Position, list[str]]:+ """`position` with each room's number lowered to the room's highest+ `messages.seq` where it was higher, and the rooms that were lowered.++ A number beyond the end of a room can only come from a different+ history of the database, for example after a restore from backup. If+ it were kept, the reader would silently skip that many of the room's+ next messages, because a position never moves backwards.+ """+ rooms = {+ room_id for source in position if (room_id := room_of(source)) is not None+ }+ clamped = dict(position)+ past: list[str] = []+ for room_id, head in (await self.room_heads(tenant_id, rooms)).items():+ source = room_source(room_id)+ if clamped[source] > head:+ clamped[source] = head+ past.append(room_id)+ return clamped, sorted(past)++ async def room_window_starts(+ self, tenant_id: str, room_ids: set[str]+ ) -> dict[str, int]:+ """For each room, the `messages.seq` of its newest row older than the+ retention window, or 0 if there is none.++ A reader with no number for a room starts reading there, and a room+ with no unread baseline starts counting there, so both cover the same+ span of time that own events are kept for.+ """+ if not room_ids:+ return {}+ cutoff = datetime.now(UTC) - timedelta(seconds=self._retention_seconds)+ async with tenant_session(self._session_factory, tenant_id) as session:+ return {+ room_id: max(+ await session.scalar(_window_start(room_id, cutoff)) or 0, 0+ )+ for room_id in room_ids+ }++ async def read_conversation(+ self,+ tenant_id: str,+ agent_id: str,+ after: dict[str, int],+ *,+ limit: int,+ ) -> Conversation:+ """The conversation in each room of `after`, read from `messages`+ after the room's number in `after`.++ A row is delivered when it is a message or a join by someone other+ than the agent, sent after the agent joined the room, and not already+ an own event. A row may only be delivered once the agent's consumer has+ decided whether it becomes an own event. The consumer handles a room's rows+ one at a time, in order, so every row up to the room row of the+ agent's newest own event in that room is decided. A later row is treated as+ decided once it is older than `CONVERSATION_SETTLE_SECONDS`. Each room+ is read in order and the read stops at the first undecided row.+ Several files posted as one message are delivered as one event, once+ all of them are present or `CONVERSATION_GROUP_GRACE_SECONDS` has+ passed.+ """+ if not after:+ return Conversation()+ started = time.perf_counter()+ events: list[BufferedEvent] = []+ through: dict[str, int] = {}+ async with tenant_session(self._session_factory, tenant_id) as session:+ me = await session.execute(+ select(Client.transport_user_id, Client.id)+ .join(Agent, Agent.client_id == Client.id)+ .where(Agent.id == agent_id)+ )+ identity = me.first()+ if identity is None:+ return Conversation()+ my_sender, my_client = identity+ joined: dict[str, Any] = {+ room_id: joined_at+ for room_id, joined_at in (+ await session.execute(+ select(ClientRoom.room_id, ClientRoom.joined_at).where(+ ClientRoom.client_id == my_client,+ ClientRoom.room_id.in_(after),+ )+ )+ ).all()+ }+ rooms = {+ room.id: room+ for room in (+ await session.scalars(select(Room).where(Room.id.in_(after)))+ ).all()+ }+ # Computed with the database's clock, which is the clock that+ # stamped `sent_at`, so a difference between this process's clock+ # and the database's cannot shorten or lengthen the settle time.+ settled_before: datetime = cast(+ datetime,+ await session.scalar(+ select(func.now() - timedelta(seconds=self._settle_seconds))+ ),+ )+ group_deadline = settled_before - timedelta(+ seconds=CONVERSATION_GROUP_GRACE_SECONDS+ )+ # For each room, the room row of the agent's newest own event written by+ # its consumer. Only message and room_join own events count: command+ # own events are written elsewhere, so they say nothing about how far+ # the consumer has got in the room.+ decided_through: dict[str, int] = {+ room_id: seq+ for room_id, seq in (+ await session.execute(+ select(AgentEventRow.room_id, func.max(AgentEventRow.room_seq))+ .where(+ AgentEventRow.agent_id == agent_id,+ AgentEventRow.room_id.in_(after),+ AgentEventRow.type.in_(("message", "room_join")),+ )+ .group_by(AgentEventRow.room_id)+ )+ ).all()+ }+ for room_id, after_seq in sorted(after.items()):+ room = rooms.get(room_id)+ if room is None or room_id not in joined:+ continue+ rows: list[Message] = []+ for row in (+ await session.scalars(+ select(Message)+ .where(+ Message.room_id == room_id,+ Message.seq > max(after_seq, 0),+ )+ .order_by(Message.seq)+ .limit(limit)+ )+ ).all():+ if (+ row.seq > decided_through.get(room_id, 0)+ and cast(datetime, row.sent_at) >= settled_before+ ):+ break+ rows.append(row)+ if not rows:+ continue+ room_events, room_through = await self._conversation_in(+ session,+ room,+ rows,+ my_sender=my_sender,+ joined_at=joined[room_id],+ agent_id=agent_id,+ group_deadline=group_deadline,+ )+ events.extend(room_events)+ if room_through > after_seq:+ through[room_id] = room_through+ self._record_scan(_READ, len(events), started)+ return Conversation(events=events, through=through)++ async def _conversation_in(+ self,+ session: AsyncSession,+ room: Room,+ rows: list[Message],+ *,+ my_sender: str,+ joined_at: Any,+ agent_id: str,+ group_deadline: datetime,+ ) -> tuple[list[BufferedEvent], int]:+ """Turn one room's rows into conversation events, and return them with+ the `messages.seq` of the last row examined."""+ # For each message key, the highest room row an own event for that message+ # was delivered through. A row at or below it is already an own event and is+ # skipped. A file of a multi-file message that arrives after the own event+ # for its group was written is above that row, so it is delivered as+ # conversation.+ keys = {message_key(row) for row in rows}+ delivered_through: dict[str, int] = {+ key: seq+ for key, seq in (+ await session.execute(+ select(AgentEventRow.message_key, func.max(AgentEventRow.room_seq))+ .where(+ AgentEventRow.agent_id == agent_id,+ AgentEventRow.message_key.in_(keys),+ )+ .group_by(AgentEventRow.message_key)+ )+ ).all()+ }++ def already_an_own_event(row: Message) -> bool:+ return row.seq <= delivered_through.get(message_key(row), -1)++ attachments: dict[str, list[MessageAttachment]] = {}+ message_ids = [row.id for row in rows if row.event_type == "m.room.message"]+ if message_ids:+ for attachment in (+ await session.scalars(+ select(MessageAttachment)+ .where(MessageAttachment.message_id.in_(message_ids))+ .order_by(MessageAttachment.message_id, MessageAttachment.position)+ )+ ).all():+ attachments.setdefault(attachment.message_id, []).append(attachment)++ # The files of each multi-file message present in `rows`, keyed by+ # attachment group id, as (index, total, row).+ groups: dict[str, list[tuple[int, int, Message]]] = {}+ for row in rows:+ if already_an_own_event(row):+ continue+ group = parse_attachment_group(row.content or {})+ if group is not None:+ groups.setdefault(group[0], []).append((group[1], group[2], row))++ # A group that is still incomplete and within its grace time stops the+ # read at its first file, so the whole group is delivered by a later+ # read instead of in pieces.+ held_from: int | None = None+ for parts in groups.values():+ total = parts[0][1]+ lead = min(parts, key=lambda part: part[0])[2]+ complete = len({index for index, _, _ in parts}) >= total+ if not complete and cast(datetime, lead.sent_at) >= group_deadline:+ first = min(row.seq for _, _, row in parts)+ held_from = first if held_from is None else min(held_from, first)++ member_names = await self._member_names(+ session,+ {+ row.sender_id+ for row in rows+ if row.event_type == "m.room.member" and row.sender_id != my_sender+ },+ )- Covering a room is not being in it. A connection carries every session- of an agent and delivers the union of their rooms, so a connection- saying what it covers must not take a room from whoever is in it — and- a delivery loop says it on every pass.+ events: list[BufferedEvent] = []+ through = 0+ for row in rows:+ if held_from is not None and row.seq >= held_from:+ break+ through = row.seq+ if row.sender_id == my_sender or row.sent_at < joined_at:+ continue+ if already_an_own_event(row):+ continue+ key = message_key(row)+ inbound = to_inbound(+ row, attachments.get(row.id, []), transport_room_id=room.id+ )+ event: AgentEvent | None = None+ seq = row.seq+ if isinstance(inbound, InboundMembership):+ if inbound.membership != "join" or inbound.prev_membership == "join":+ continue+ event = room_join_event(+ room_id=room.id,+ bridge_id=room.bridge_id,+ channel_type=room.channel_type,+ member=inbound.state_key,+ member_name=member_names.get(inbound.state_key)+ or inbound.display_name+ or inbound.state_key.split(":")[0].lstrip("@"),+ timestamp=inbound.timestamp,+ listening=False,+ )+ elif isinstance(inbound, InboundMedia) and key in groups:+ # A multi-file message goes out once, at its last file, which is+ # the room row its event is numbered by. A message posted+ # between its files goes out before it, so a room's events go+ # out in rising order. Were the group sent at its first file, a+ # client that disconnected right after it would hold a place+ # past the message in between and never receive that message.+ if row.seq != max(part.seq for _, _, part in groups[key]):+ continue+ event, seq = self._grouped_media(+ room, inbound, groups[key], attachments+ )+ elif isinstance(inbound, InboundMedia):+ event = message_event(+ room_id=room.id,+ bridge_id=room.bridge_id,+ channel_type=room.channel_type,+ event=inbound,+ addressed=False,+ sender_name=inbound.sender_name or inbound.sender,+ body=inbound.body,+ thread_id=inbound.thread_root_id,+ attachments=[attachment_ref(inbound)],+ )+ elif isinstance(inbound, InboundMessage):+ event = message_event(+ room_id=room.id,+ bridge_id=room.bridge_id,+ channel_type=room.channel_type,+ event=inbound,+ addressed=False,+ sender_name=inbound.sender_name or inbound.sender,+ body=inbound.body,+ thread_id=None+ if platform_replies_in_channel(inbound.content)+ else inbound.thread_root_id,+ )+ if event is None:+ continue+ events.append(+ BufferedEvent(+ seq=seq,+ room_id=room.id,+ event=event,+ notifiable=False,+ source=room_source(room.id),+ room_seq=seq,+ at=_epoch(cast(datetime, row.sent_at)),+ )+ )+ return events, through- Nothing already recorded is touched: what is there is either progress- or a deliberate unknown, and replacing either would invent a zero.+ def _grouped_media(+ self,+ room: Room,+ lead_inbound: InboundMedia,+ parts: list[tuple[int, int, Message]],+ attachments: dict[str, list[MessageAttachment]],+ ) -> tuple[AgentEvent, int]:+ """Build one message event from the files of a multi-file message, and+ return it with the highest room row among the files.++ The event is based on the lowest-numbered file present, which carries+ the caption and the message id the sender was given. When files are+ missing, the body says how many arrived, as a live delivery by the+ consumer does."""- if room_id in self._counting.setdefault(agent_id, {}):- return- self._begin(- agent_id, room_id, Reader(id=connection_id, is_session=False), from_seq+ ordered = sorted(parts, key=lambda part: part[0])+ total = ordered[0][1]+ lead = ordered[0][2]+ refs = []+ for _, _, row in ordered:+ inbound = to_inbound(+ row, attachments.get(row.id, []), transport_room_id=room.id+ )+ if isinstance(inbound, InboundMedia):+ refs.append(attachment_ref(inbound))+ anchor = to_inbound(+ lead, attachments.get(lead.id, []), transport_room_id=room.id+ )+ if not isinstance(anchor, InboundMedia):+ anchor = lead_inbound+ body = anchor.body+ present = len({index for index, _, _ in ordered})+ if present < total:+ notice = (+ f"[incomplete attachment group: {present} of {total} files arrived]"+ )+ body = f"{body}\n{notice}" if body else notice+ event = message_event(+ room_id=room.id,+ bridge_id=room.bridge_id,+ channel_type=room.channel_type,+ event=anchor,+ addressed=False,+ sender_name=anchor.sender_name or anchor.sender,+ body=body,+ thread_id=anchor.thread_root_id,+ attachments=refs,)+ return event, max(row.seq for _, _, row in ordered)++ async def _member_names(+ self, session: AsyncSession, transport_ids: set[str]+ ) -> dict[str, str]:+ if not transport_ids:+ return {}+ rows = (+ await session.execute(+ select(Client.transport_user_id, Client.display_name).where(+ Client.transport_user_id.in_(transport_ids)+ )+ )+ ).all()+ return {transport_id: name for transport_id, name in rows}- def take_counting(- self, agent_id: str, connection_id: str, room_id: str, from_seq: int- ) -> None:- """A connection has taken this room from whoever held it.-- For the doors where the room slot itself changes hands and the registry- has granted the takeover — not for a connection re-stating what it- delivers. Whoever is being told how far behind the room is has to be- the one whose reading clears it, so the taker becomes the occupant- whether it took the room from another connection or from a session that- has now been displaced from it.-- What the room is behind by survives the change of hands: the messages- went past unread whoever was there, and a successor told zero would be- told something nobody has established.+ # ------------------------------------------------------------------+ # Reading a position+ # ------------------------------------------------------------------++ async def read(+ self,+ tenant_id: str,+ agent_id: str,+ position: Position,+ *,+ conversation_rooms: set[str],+ notifiable_only: bool = False,+ own_event_rooms: set[str] | None = None,+ limit: int,+ ) -> tuple[list[BufferedEvent], Position]:+ """The agent's own events and its rooms' conversation after `position`, in+ the order they happened, and how far each source was read.++ Own events are read up to the agent's head as it was before the read, so the+ returned position never moves past an own event inserted during the read.+ Events from one source keep that source's order, and events from+ different sources are interleaved by time. Each room in+ `conversation_rooms` is read from its number in `position`; a room with+ no number in `position` is not read."""- rooms = self._counting.setdefault(agent_id, {})- taker = Reader(id=connection_id, is_session=False)- held = rooms.get(room_id)- if held is None:- self._begin(agent_id, room_id, taker, from_seq)- return- held.occupant = taker+ after = position.get(OWN_EVENTS, self.sequence_floor - 1)+ bound = await self.head(tenant_id, agent_id)+ own_events = await self.read_from(+ tenant_id,+ agent_id,+ after,+ rooms=own_event_rooms,+ notifiable_only=notifiable_only,+ limit=limit,+ through_seq=bound,+ )+ looked: Position = {}+ if len(own_events) < limit and bound > after:+ looked[OWN_EVENTS] = bound+ conversation = await self.read_conversation(+ tenant_id,+ agent_id,+ {+ room_id: position[room_source(room_id)]+ for room_id in conversation_rooms+ if room_source(room_id) in position+ },+ limit=limit,+ )+ for room_id, seq in conversation.through.items():+ looked[room_source(room_id)] = seq+ return _interleaved([own_events, *_by_source(conversation.events)]), looked- def hand_counting_to(self, agent_id: str, reader: Reader, room_id: str) -> None:- """Record that `reader` is the one in the room now.+ # ------------------------------------------------------------------+ # Tickets, for clients that hold one number+ # ------------------------------------------------------------------- Connecting to a room is taking it, so the newcomer becomes the only- caller whose reading clears the count there — which is what stops a- read begun by the session it displaced from clearing a count that is- no longer that session's to clear.+ async def mint_tickets(+ self, tenant_id: str, agent_id: str, positions: list[Position]+ ) -> list[int]:+ """Store each position in `agent_position_tickets` and return the ticket+ ids, in order.- What the room is behind by survives the change of hands: the messages- went past unread whoever was there, and a successor told zero would be- told something nobody has established. A room nothing has counted yet- starts from the oldest event still retained, the most that can be said- about how far behind it is.+ A client that can hold only one integer is sent a ticket id. When it+ sends the id back, `ticket` returns the stored position."""- rooms = self._counting.setdefault(agent_id, {})- held = rooms.get(room_id)- if held is None:- self._begin(agent_id, room_id, reader, 0)- return- held.occupant = reader+ if not positions:+ return []+ ids: list[int] = []+ async with tenant_session(self._session_factory, tenant_id) as session:+ for position in positions:+ ticket = await session.scalar(+ insert(AgentPositionTicket)+ .values(tenant_id=tenant_id, agent_id=agent_id, position=position)+ .returning(AgentPositionTicket.id)+ )+ assert ticket is not None+ ids.append(ticket)+ await session.commit()+ return ids++ async def ticket(+ self, tenant_id: str, agent_id: str, ticket_id: int+ ) -> Position | None:+ """The position stored under a ticket id, or None when the ticket does+ not exist, has been deleted by `expire`, or belongs to another agent."""+ async with tenant_session(self._session_factory, tenant_id) as session:+ position = await session.scalar(+ select(AgentPositionTicket.position).where(+ AgentPositionTicket.id == ticket_id,+ AgentPositionTicket.agent_id == agent_id,+ )+ )+ return dict(position) if position is not None else None- def mark_restarted(self, agent_id: str) -> None:- """Record that how far behind any of this agent's rooms are cannot be said.+ # ------------------------------------------------------------------+ # Unread counts+ # ------------------------------------------------------------------++ async def ensure_counting(+ self, tenant_id: str, agent_id: str, reader_id: str, room_id: str+ ) -> None:+ """Start counting unread messages in a room that a connection+ delivers, unless the room already has a row in `agent_room_reads`.++ A connection carries every session of an agent and delivers the union+ of their rooms, so delivering a room does not mean being in it. A+ connection listing the rooms it delivers must not take a room from the+ session that is in it, so an existing row is left unchanged. A new+ row's baseline is the room's current end, so the count starts now.+ """+ async with tenant_session(self._session_factory, tenant_id) as session:+ await session.execute(+ _counting(+ agent_id,+ room_id,+ baseline=_room_head(room_id),+ occupant=Reader(id=reader_id, is_session=False),+ ).on_conflict_do_nothing(+ index_elements=[AgentRoomRead.agent_id, AgentRoomRead.room_id]+ )+ )+ await session.commit()++ async def take_counting(+ self, tenant_id: str, agent_id: str, reader_id: str, room_id: str+ ) -> None:+ """Record that a connection has taken this room from whoever held it.- The buffer is in memory, so a restart takes every room's baseline with- it — not only the rooms of whichever connection noticed. An `all`-scope- connection names no rooms at all and the rooms its sessions work in- arrive afterwards, so the rule has to outlive the reconnection that- reports it: a room first counted after a restart starts unknown too.+ This is for callers where the room itself changes hands and the+ registry has granted the takeover. The connection becomes the occupant+ in `agent_room_reads`, the only reader whose reads clear the room's+ unread count. The baseline is kept, so messages the room had not caught+ up on are still counted after the change.+ """+ async with tenant_session(self._session_factory, tenant_id) as session:+ await session.execute(+ _counting(+ agent_id,+ room_id,+ baseline=_room_head(room_id),+ occupant=Reader(id=reader_id, is_session=False),+ ).on_conflict_do_update(+ index_elements=[AgentRoomRead.agent_id, AgentRoomRead.room_id],+ set_={"occupant_id": reader_id, "occupant_is_session": False},+ )+ )+ await session.commit()++ async def hand_counting_to(+ self, tenant_id: str, agent_id: str, reader: Reader, room_id: str+ ) -> None:+ """Record that `reader` is now the reader in the room.- Sticky either way, so a room is not quietly given a fresh baseline and- its reader told nothing went by. The next time one catches up it gets a- real baseline again. Whoever is in a room stays in it: losing the- buffer says nothing about who is where.+ Connecting to a room takes it, so the new reader becomes the only one+ whose reads clear the room's unread count. The baseline is kept, so+ messages the room had not caught up on are still counted after the+ change. A room with no row yet gets a baseline at the start of the+ retention window, which is as far back as a count can reach."""- self._restarted.add(agent_id)- for counting in self._counting.get(agent_id, {}).values():- counting.baseline = None+ start = (await self.room_window_starts(tenant_id, {room_id}))[room_id]+ async with tenant_session(self._session_factory, tenant_id) as session:+ await session.execute(+ _counting(+ agent_id, room_id, baseline=literal(start), occupant=reader+ ).on_conflict_do_update(+ index_elements=[AgentRoomRead.agent_id, AgentRoomRead.room_id],+ set_={+ "occupant_id": reader.id,+ "occupant_is_session": reader.is_session,+ },+ )+ )+ await session.commit()- def caught_up(+ async def caught_up(self,+ tenant_id: str,agent_id: str,reader: Reader,room_id: str,through_seq: int,arrived_on: str | None,) -> None:- """Record that the room's occupant has caught up through `through_seq`.-- Forward only, and only for the room named: catching up on one room- says nothing about any other, which is the whole point of counting- per room.-- Ignored from anyone but the occupant. A read is begun before its- history arrives, so a session displaced from the room while its read- was in flight comes back holding an answer for a room it has left; the- session that took the room has not read a word of it, and must not be- told otherwise.-- A session may take the count over from the connection it is speaking- over — `arrived_on` — and from nothing else. That connection carried it- into the room, so a count opened in the connection's name is the- session's own to clear, which is how a session recovers one rather than- reading forever against a baseline nothing it can say will clear. A- count any other connection holds belongs to whoever took the room, and- a session outranking it would put the displaced back in charge of it.+ """Record that the room's occupant has read the room through+ `through_seq`, a `messages.seq` in that room.++ The baseline only moves forward, and only for the room named. A call+ from any reader other than the occupant is ignored. A read starts+ before its history arrives, so a session displaced while its read was+ in flight comes back with a result for a room it has left, and must not+ clear the new occupant's count. The one exception is a session taking+ the room over from the connection it arrived on (`arrived_on`); it+ cannot take it over from any other reader."""- rooms = self._counting.setdefault(agent_id, {})- held = rooms.get(room_id)- if held is None:- rooms[room_id] = _Counting(occupant=reader, baseline=through_seq)- return- if held.occupant != reader:- if not reader.is_session:- return- if held.occupant.is_session or held.occupant.id != arrived_on:+ async with tenant_session(self._session_factory, tenant_id) as session:+ held = await session.scalar(+ select(AgentRoomRead)+ .where(+ AgentRoomRead.agent_id == agent_id,+ AgentRoomRead.room_id == room_id,+ )+ .with_for_update()+ )+ if held is None:+ session.add(+ AgentRoomRead(+ tenant_id=tenant_id,+ agent_id=agent_id,+ room_id=room_id,+ caught_up_seq=through_seq,+ occupant_id=reader.id,+ occupant_is_session=reader.is_session,+ )+ )+ await session.commit()return- held.occupant = reader- if held.baseline is None or through_seq > held.baseline:- held.baseline = through_seq-- def unread(self, agent_id: str, room_id: str, through_seq: int) -> Unread:- """Unaddressed messages in one room the agent has not caught up on.-- Counted on demand from the retained events rather than tallied as they- arrive, so it cannot disagree with what the buffer holds. Only- messages: an agent is told how much conversation went past it, not how- many admin events did.-- Asked by room alone, with no reader: a connection carrying every- session of an agent could not say which of them a room's count belongs- to, and only one of them can be in the room to be told.+ occupant = Reader(id=held.occupant_id, is_session=held.occupant_is_session)+ if occupant != reader:+ if not reader.is_session:+ return+ if occupant.is_session or occupant.id != arrived_on:+ return+ held.occupant_id = reader.id+ held.occupant_is_session = True+ if through_seq > held.caught_up_seq:+ held.caught_up_seq = through_seq+ await session.commit()++ async def unread(+ self, tenant_id: str, agent_id: str, room_id: str, through_seq: int+ ) -> Unread:+ """Count the unaddressed messages in one room that the agent has not+ caught up on, up to `through_seq`, a `messages.seq` in that room.++ The count is computed from `messages` when asked, so it always agrees+ with the room's log. It counts messages only, leaving out the ones the agent+ sent and the ones that became own events, because it tells the agent how much+ conversation went past it. Several files posted as one message count+ once. The count never reaches further back than the retention window:+ older own events have been deleted, so older messages addressed to the agent+ can no longer be told apart. A count cut at the window says so in its+ `reason`."""- held = self._counting.get(agent_id, {}).get(room_id)- if held is None:- return Unread(count=None, reason=NO_BASELINE)- baseline = held.baseline- if baseline is None:- return Unread(count=None, reason=RESTARTED)-- started = time.perf_counter()- events = self._events.get(agent_id, ())- count = sum(- 1- for item in events- if item.room_id == room_id- and baseline < item.seq <= through_seq- and item.event.type == "message"- and not item.notifiable- )- self._record_scan(_UNREAD, len(events), started)- dropped = self._dropped_through.get(agent_id, {}).get(room_id, 0)- if dropped > baseline:- return Unread(count=count, reason=COUNTED_FROM_A_HOLE)- return Unread(count=count, reason=None)+ async with tenant_session(self._session_factory, tenant_id) as session:+ baseline = await session.scalar(+ select(AgentRoomRead.caught_up_seq).where(+ AgentRoomRead.agent_id == agent_id,+ AgentRoomRead.room_id == room_id,+ )+ )+ if baseline is None:+ return Unread(count=None, reason=NO_BASELINE)+ cutoff = datetime.now(UTC) - timedelta(seconds=self._retention_seconds)+ window_start = await session.scalar(_window_start(room_id, cutoff)) or 0+ reason = None+ if baseline < window_start:+ baseline, reason = window_start, COUNTED_FROM_WINDOW+ me = await session.scalar(+ select(Client.transport_user_id)+ .join(Agent, Agent.client_id == Client.id)+ .where(Agent.id == agent_id)+ )+ started = time.perf_counter()+ count = await session.scalar(+ _UNREAD_SQL,+ {+ "room_id": room_id,+ "baseline": baseline,+ "through": through_seq,+ "me": me or "",+ "agent_id": agent_id,+ },+ )+ self._record_scan(_UNREAD, count or 0, started)+ return Unread(count=count or 0, reason=reason)- def register_reader(self, agent_id: str, reader_id: str, cursor: int) -> None:- self._cursors.setdefault(agent_id, {})[reader_id] = cursor+ # ------------------------------------------------------------------+ # Leaving+ # ------------------------------------------------------------------- def confirm(self, agent_id: str, reader_id: str, cursor: int) -> None:- """Record how far a reader has consumed, so its events can be trimmed.+ def remove(self, agent_id: str) -> None:+ """Forget this process's doorbell for an agent.- Cursors only move forward. A reader reporting a lower value than it has- already confirmed is ignored rather than allowed to rewind the buffer.+ The agent's rows in the tables this module uses are deleted with its+ row in `agents` (`ON DELETE CASCADE`)."""- readers = self._cursors.setdefault(agent_id, {})- if cursor > readers.get(reader_id, 0):- readers[reader_id] = cursor+ self._notify.pop(agent_id, None)- def drop_reader(self, agent_id: str, reader_id: str) -> None:- """Forget a reader's delivery cursor. What its rooms are behind by stays.+ async def drop_room(self, tenant_id: str, agent_id: str, room_id: str) -> None:+ """Delete the agent's own events in one room.- A reader going away does not mean the conversation it was not reading- was read. The next session in the room is told what went past.+ Called when the agent is removed from it. Sequence numbers are untouched+ and no gap is recorded: a reader that skips these has missed nothing it+ was entitled to, and saying otherwise would send it to re-read the+ context of a room it is not in."""- readers = self._cursors.get(agent_id)- if readers:- readers.pop(reader_id, None)-- def remove(self, agent_id: str) -> None:- self._events.pop(agent_id, None)- self._notify.pop(agent_id, None)- self._cursors.pop(agent_id, None)- self._dropped_through.pop(agent_id, None)- self._counting.pop(agent_id, None)- self._restarted.discard(agent_id)- self._overflow_warned_at.pop(agent_id, None)- self._overflow_unlogged.pop(agent_id, None)-- def _begin(- self, agent_id: str, room_id: str, occupant: Reader, baseline: int- ) -> None:- """Start counting a room, unknown when the buffer restarted under it."""- self._counting.setdefault(agent_id, {})[room_id] = _Counting(- occupant=occupant,- baseline=None if agent_id in self._restarted else baseline,- )+ async with tenant_session(self._session_factory, tenant_id) as session:+ result = await session.execute(+ delete(AgentEventRow).where(+ AgentEventRow.agent_id == agent_id,+ AgentEventRow.room_id == room_id,+ )+ )+ await session.commit()+ dropped = result.rowcount or 0 # type: ignore[attr-defined]+ if dropped:+ logger.info(+ "[EVENT-BUF] dropped %s retained event(s) for agent=%s room=%s: "+ "no longer a member",+ dropped,+ agent_id,+ room_id,+ )- def drop_room(self, agent_id: str, room_id: str) -> None:- """Forget everything retained for this agent in one room.+ # ------------------------------------------------------------------+ # Retention+ # ------------------------------------------------------------------- Called when the agent is removed from it. The buffer is keyed by agent- and knows nothing about who is in what, so an event queued while it was- a member stays readable after it is not.+ async def expire(self, tenant_id: str) -> int:+ """Delete one tenant's own events and tickets older than the retention window.- Sequence numbers are untouched and no gap is recorded: a reader that- skips these has missed nothing it was entitled to, and saying otherwise- would send it to re-read the context of a room it is not in.+ For each agent and room it records the newest own event it deleted in+ `agent_event_drops`, so a reader resuming from before that own event is told+ it missed events there. Retention is independent of what readers have confirmed: an+ event stays readable for its window whether or not somebody has already+ consumed it, so a reader that arrives late still sees recent history."""- events = self._events.get(agent_id)- if not events:- return- kept = [item for item in events if item.room_id != room_id]- dropped = len(events) - len(kept)- if not dropped:- return- events.clear()- events.extend(kept)- logger.info(- "[EVENT-BUF] dropped %s retained event(s) for agent=%s room=%s: "- "no longer a member",- dropped,- agent_id,- room_id,- )+ cutoff = datetime.now(UTC) - timedelta(seconds=self._retention_seconds)+ async with tenant_session(self._session_factory, tenant_id) as session:+ deleted = (+ await session.execute(+ delete(AgentEventRow)+ .where(AgentEventRow.created_at < cutoff)+ .returning(+ AgentEventRow.agent_id, AgentEventRow.room_id, AgentEventRow.seq+ )+ )+ ).all()+ through: dict[tuple[str, str], int] = {}+ for agent_id, room_id, seq in deleted:+ key = (agent_id, room_id)+ through[key] = max(seq, through.get(key, 0))+ for (agent_id, room_id), seq in through.items():+ await session.execute(+ insert(AgentEventDrop)+ .values(+ tenant_id=tenant_id,+ agent_id=agent_id,+ room_id=room_id,+ dropped_through=seq,+ )+ .on_conflict_do_update(+ index_elements=[+ AgentEventDrop.agent_id,+ AgentEventDrop.room_id,+ ],+ set_={+ "dropped_through": func.greatest(+ AgentEventDrop.dropped_through, seq+ )+ },+ )+ )+ await session.execute(+ delete(AgentPositionTicket).where(+ AgentPositionTicket.created_at < cutoff+ )+ )+ await session.commit()+ if deleted:+ metrics().increment(+ AGENT_EVENTS_DROPPED, {"reason": "retention"}, len(deleted)+ )+ return len(deleted)# ------------------------------------------------------------------# Legacy long-poll compatibility#- # Polling clients send no cursor and have nowhere to keep one, so the- # server holds it for them: "everything after the last thing I gave you,- # and record that I gave it". Behaviour is unchanged from their point of- # view — they never see a duplicate — but reads are no longer destructive,- # so a streaming reader on the same agent is unaffected.+ # Long-polling clients send no position and have nowhere to store one, so+ # the server stores it for them in `agent_poll_positions`, one row per+ # agent and poll endpoint (`reader_id`). Each poll returns everything after+ # what the server last gave that reader, and records what it gave. These+ # clients never see a duplicate. Reading deletes nothing, so a streaming+ # reader of the same agent is unaffected.#- # Delivery stays at-most-once for these callers, exactly as before: the- # cursor advances on send, so a response lost in flight loses its events.- # Confirming clients get at-least-once instead.+ # Delivery to these clients is at most once: the position advances when a+ # response is sent, so a response lost in flight loses its events.# ------------------------------------------------------------------async def poll(- self, agent_id: str, *, rooms: set[str], timeout: float = 30+ self, tenant_id: str, agent_id: str, *, rooms: set[str], timeout: float = 30) -> list[AgentEvent]:- """Everything queued for this agent in the rooms it is in.-- `rooms` is how the caller applies membership, and it is required: the- buffer is keyed by agent and knows nothing about who is in what, so an- event queued while the agent was a member stays queued after it is- removed. A default would make the leak the thing a new caller gets for- free.-- Read once, before the wait. A room the agent is added to while this is- parked has its first events held back to the next poll, which the- caller makes immediately; asking the caller to re-read membership- mid-poll would buy that one round trip at the cost of a callback- reaching back out of the buffer, and this stays behind the narrow- surface described at the top of the module.+ """Every event for this agent in the rooms it is in: its own events and the+ rooms' conversation.++ `rooms` is the agent's current room membership, and it is required.+ Own events are stored per agent with no record of membership, so an own event+ written while the agent was in a room stays readable after the agent+ is removed from it. Without a required filter, a new caller would by+ default receive events from rooms the agent has left."""return await self._legacy_poll(- agent_id, "legacy:all", timeout=timeout, rooms=rooms+ tenant_id,+ agent_id,+ "legacy:all",+ timeout=timeout,+ rooms=rooms,+ conversation=True,)async def poll_room(- self, agent_id: str, room_id: str, timeout: float = 30+ self, tenant_id: str, agent_id: str, room_id: str, timeout: float = 30) -> list[AgentEvent]:return await self._legacy_poll(+ tenant_id,agent_id,f"legacy:room:{room_id}",timeout=timeout,rooms={room_id},+ conversation=True,rooms_are_membership=False,)async def poll_notifications(- self, agent_id: str, *, rooms: set[str], timeout: float = 30+ self, tenant_id: str, agent_id: str, *, rooms: set[str], timeout: float = 30) -> list[AgentEvent]:- """The notifiable half of `poll`, under the same membership rule.+ """The agent's notifiable own events (see `is_notifiable`), filtered by+ `rooms` in the same way as `poll`.- This is the stream carrying messages addressed at the agent, so it is- the one a removal matters most on.+ This stream carries the messages addressed to the agent, so it is where+ leaking events from a room the agent has left would matter most."""return await self._legacy_poll(+ tenant_id,agent_id,"legacy:notifications",timeout=timeout,@@ -640,93 +1542,78 @@ class EventBuffer:async def _legacy_poll(self,+ tenant_id: str,agent_id: str,reader_id: str,*,timeout: float,rooms: set[str],+ conversation: bool = False,notifiable_only: bool = False,rooms_are_membership: bool = True,) -> list[AgentEvent]:- args = (agent_id, reader_id, rooms, notifiable_only, rooms_are_membership)- events = self._legacy_take(*args)+ args = (+ tenant_id,+ agent_id,+ reader_id,+ rooms,+ conversation,+ notifiable_only,+ rooms_are_membership,+ )+ events = await self._legacy_take(*args)if events:return events- await self.wait(agent_id, timeout)+ if conversation:+ # New conversation rows do not set the doorbell, and they are only+ # delivered once they have settled, so a poll that includes+ # conversation wakes after twice the settle time to look again+ # instead of sleeping through the whole timeout.+ await self.wait(agent_id, min(timeout, self._settle_seconds * 2))+ else:+ await self.wait(agent_id, timeout)- return self._legacy_take(*args)+ return await self._legacy_take(*args)- def _legacy_take(+ async def _legacy_take(self,+ tenant_id: str,agent_id: str,reader_id: str,rooms: set[str],+ conversation: bool,notifiable_only: bool,rooms_are_membership: bool,) -> list[AgentEvent]:- """One read, moving the cursor past what this reader can never want.-- Past what it can never want, and no further. A legacy read has no- limit, so it always reaches the end of the buffer, and leaving the- cursor behind an event the filter excluded parks it below the head- indefinitely — until retention trims it and the next read reports a- gap that never happened.-- Which exclusions are permanent depends on the filter.- `notifiable_only` tests a property of the event, which is fixed, so- those can be skipped for good. A room set taken from membership is not- fixed: an agent added to a room the buffer already holds events for- would find the cursor already past them, and they would never be- delivered. `poll_room`'s filter is the reader's own scope rather than a- membership snapshot, so there the exclusions are permanent too — hence- `rooms_are_membership`.+ """Read once for a long-polling reader, save its new position, and+ return the events.++ The bound on own event numbers is read before the own events and the read stops+ at it, so the saved position covers exactly the own events returned. When+ `rooms` is the agent's membership, the bound is the newest own event in+ those rooms rather than the agent's head. Membership can grow: if the+ position moved to the head, own events already written for a room the agent+ is added to later would sit below the position and never be delivered.+ `poll_room` reads a fixed room chosen by the reader, so it passes+ `rooms_are_membership=False` and moves to the head."""- cursor = self._legacy_cursor(agent_id, reader_id)- events = self._legacy_read(agent_id, reader_id, cursor, rooms, notifiable_only)+ position = await self._poll_position(+ tenant_id, agent_id, reader_id, rooms if conversation else set()+ )+ after = position[OWN_EVENTS]if rooms_are_membership:- self.confirm(- agent_id, reader_id, self._last_seq_in_rooms(agent_id, cursor, rooms)- )+ through = await self._last_seq_in_rooms(tenant_id, agent_id, after, rooms)else:- self.confirm(agent_id, reader_id, self.head(agent_id))- return [item.event for item in events]-- def _last_seq_in_rooms(self, agent_id: str, after_seq: int, rooms: set[str]) -> int:- """The newest retained event after `after_seq` in one of `rooms`.-- `after_seq` itself when there is none, so a caller confirming this- never moves a cursor over an event held for a room the agent is not in- yet.- """- last = after_seq- for item in self._events.get(agent_id, ()):- if item.seq > after_seq and item.room_id in rooms:- last = item.seq- return last-- def _legacy_cursor(self, agent_id: str, reader_id: str) -> int:- readers = self._cursors.setdefault(agent_id, {})- if reader_id not in readers:- # A poller seen for the first time starts before the oldest- # retained event, mirroring the queue it replaces: events- # accumulated while nobody was polling and the first poll drained- # them. Starting at head would silently swallow anything that- # arrived before the client got around to asking.- readers[reader_id] = max(self.oldest_retained(agent_id) - 1, 0)- return readers[reader_id]-- def _legacy_read(- self,- agent_id: str,- reader_id: str,- cursor: int,- rooms: set[str],- notifiable_only: bool,- ) -> list[BufferedEvent]:+ through = await self.head(tenant_id, agent_id)try:- return self.read_from(- agent_id, cursor, rooms=rooms, notifiable_only=notifiable_only+ own_events = await self.read_from(+ tenant_id,+ agent_id,+ after,+ rooms=rooms,+ notifiable_only=notifiable_only,+ through_seq=through,)except CursorExpiredError as exc:# A polling client cannot be told about a gap — it has no protocol@@ -740,11 +1627,116 @@ class EventBuffer:exc.requested,exc.oldest,)- resumed = max(exc.oldest - 1, 0)- self._cursors.setdefault(agent_id, {})[reader_id] = resumed- return self.read_from(- agent_id, resumed, rooms=rooms, notifiable_only=notifiable_only+ after = exc.resume_after+ own_events = await self.read_from(+ tenant_id,+ agent_id,+ after,+ rooms=rooms,+ notifiable_only=notifiable_only,+ through_seq=through,+ )+ moved = merged(position, {OWN_EVENTS: max(through, after)})+ found: list[list[BufferedEvent]] = [own_events]+ if conversation:+ said = await self.read_conversation(+ tenant_id,+ agent_id,+ {room_id: moved[room_source(room_id)] for room_id in rooms},+ limit=10_000,+ )+ found.extend(_by_source(said.events))+ moved = merged(+ moved,+ {room_source(room_id): seq for room_id, seq in said.through.items()},+ )+ await self._save_poll_position(tenant_id, agent_id, reader_id, moved)+ return [item.event for item in _interleaved(found)]++ async def _poll_position(+ self, tenant_id: str, agent_id: str, reader_id: str, rooms: set[str]+ ) -> Position:+ """A long-polling reader's position from `agent_poll_positions`, with a+ number for each room in `rooms`.++ A reader seen for the first time starts just before the agent's oldest+ own event still kept, so own events written before the client first polled are+ delivered. Starting at the head would silently skip them. A room the+ reader has no number for starts at the beginning of the retention+ window, for the same reason.+ """+ async with tenant_session(self._session_factory, tenant_id) as session:+ stored = await session.scalar(+ select(AgentPollPosition.position).where(+ AgentPollPosition.agent_id == agent_id,+ AgentPollPosition.reader_id == reader_id,+ )+ )+ position: Position = dict(stored) if stored is not None else {}+ if OWN_EVENTS not in position:+ position[OWN_EVENTS] = await self.before_retained(tenant_id, agent_id)+ missing = {room_id for room_id in rooms if room_source(room_id) not in position}+ if missing:+ starts = await self.room_window_starts(tenant_id, missing)+ for room_id, start in starts.items():+ position[room_source(room_id)] = start+ return position++ async def _save_poll_position(+ self, tenant_id: str, agent_id: str, reader_id: str, position: Position+ ) -> None:+ # The row is inserted from a SELECT on `agents`, so if the agent was+ # deleted while the poll was in flight, nothing is saved and the insert+ # does not fail on the foreign key. An existing row is merged with the+ # new position, source by source, rather than replaced: two polls of+ # the same reader can overlap, and the one that finishes last may have+ # read less, so replacing would move the reader back and deliver the+ # same events again.+ async with tenant_session(self._session_factory, tenant_id) as session:+ await session.execute(+ insert(AgentPollPosition)+ .from_select(+ [+ AgentPollPosition.tenant_id,+ AgentPollPosition.agent_id,+ AgentPollPosition.reader_id,+ AgentPollPosition.position,+ ],+ select(+ Agent.tenant_id,+ Agent.id,+ literal(reader_id),+ literal(position, AgentPollPosition.position.type),+ ).where(Agent.id == agent_id),+ )+ .on_conflict_do_update(+ index_elements=[+ AgentPollPosition.agent_id,+ AgentPollPosition.reader_id,+ ],+ set_={"position": _MERGED_POLL_POSITION},+ )+ )+ await session.commit()++ async def _last_seq_in_rooms(+ self, tenant_id: str, agent_id: str, after_seq: int, rooms: set[str]+ ) -> int:+ """The newest retained event after `after_seq` in one of `rooms`.++ Returns `after_seq` itself when there is none. A caller that moves its+ position to the returned number therefore never moves past an own event held+ for a room the agent has not joined yet.+ """+ async with tenant_session(self._session_factory, tenant_id) as session:+ last = await session.scalar(+ select(func.max(AgentEventRow.seq)).where(+ AgentEventRow.agent_id == agent_id,+ AgentEventRow.seq > after_seq,+ AgentEventRow.room_id.in_(rooms),+ ))+ return after_seq if last is None else last# ------------------------------------------------------------------# Internals@@ -760,85 +1752,123 @@ class EventBuffer:)registry.observe(AGENT_BUFFER_SCANNED, operation, scanned)- def _wake(self, agent_id: str) -> None:- notify = self._notify.get(agent_id)- if notify is not None:- notify.set()-- def _check_cursor(self, agent_id: str, after_seq: int) -> None:- rooms = self.rooms_dropped_after(agent_id, after_seq)+ async def check_cursor(self, tenant_id: str, agent_id: str, after_seq: int) -> None:+ """Raise `CursorExpiredError` if `expire` has deleted any of the agent's+ own events numbered after `after_seq`, naming the rooms they were in+ and the number to resume after."""+ rooms = await self.rooms_dropped_after(tenant_id, agent_id, after_seq)if not rooms:return- markers = self._dropped_through[agent_id]- raise CursorExpiredError(agent_id, after_seq, max(markers.values()) + 1, rooms)-- def _trim(self, agent_id: str) -> None:- """Enforce the retention window and the cap.-- Both are lossy, so both record a gap that the next reader resuming from- before it will be told about. Retention is deliberately independent of- what readers have confirmed: an event stays readable for its window- whether or not somebody has already consumed it, so a reader that- arrives late still sees recent history.+ oldest = await self.oldest_retained(tenant_id, agent_id)+ resume_after = await self.before_retained(tenant_id, agent_id)+ raise CursorExpiredError(agent_id, after_seq, oldest, rooms, resume_after)++ async def before_retained(self, tenant_id: str, agent_id: str) -> int:+ """The own-events number just before the agent's oldest one still kept,+ and past every number `expire` deleted.++ `expire` deletes an agent's own events oldest first, so everything it+ deleted is numbered below everything it kept. When it has deleted all+ of them, this is the highest number it deleted rather than 0: a reader+ placed at 0 would find the deleted numbers ahead of it on every read."""- events = self._events.get(agent_id)- if not events:- return+ async with tenant_session(self._session_factory, tenant_id) as session:+ oldest = await session.scalar(+ select(func.min(AgentEventRow.seq)).where(+ AgentEventRow.agent_id == agent_id+ )+ )+ dropped_through = await session.scalar(+ select(func.max(AgentEventDrop.dropped_through)).where(+ AgentEventDrop.agent_id == agent_id+ )+ )+ return max(dropped_through or 0, (oldest or 0) - 1, 0)- dropped: dict[str, int] = {}- expired = 0- cutoff = time.monotonic() - self._retention_seconds- while events and events[0].appended_at < cutoff:- item = events.popleft()- dropped[item.room_id] = item.seq- expired += 1- if expired:- metrics().increment(AGENT_EVENTS_DROPPED, {"reason": "retention"}, expired)-- overflow = len(events) - self._max_events- if overflow > 0:- for _ in range(overflow):- item = events.popleft()- dropped[item.room_id] = item.seq- metrics().increment(AGENT_EVENTS_DROPPED, {"reason": "overflow"}, overflow)- self._warn_overflow(agent_id, overflow, dropped)- if dropped:- markers = self._dropped_through.setdefault(agent_id, {})- for room_id, seq in dropped.items():- markers[room_id] = max(seq, markers.get(room_id, 0))+def _transient(exc: BaseException) -> bool:+ """Whether a failed database call is worth retrying: the connection or the+ connection pool failed, not the statement itself."""+ if isinstance(exc, OperationalError | InterfaceError | PoolTimeoutError):+ return True+ return isinstance(exc, DBAPIError) and exc.connection_invalidated- def _warn_overflow(- self, agent_id: str, overflow: int, dropped: dict[str, int]- ) -> None:- """Log that the cap forced events out, at most once per interval per agent.- The drops in between are not lost: the metric still counts each one, and- the next line says how many went unlogged.- """- now = time.monotonic()- last = self._overflow_warned_at.get(agent_id)- if last is not None and now - last < OVERFLOW_WARNING_INTERVAL_SECONDS:- self._overflow_unlogged[agent_id] = (- self._overflow_unlogged.get(agent_id, 0) + overflow- )- return- unlogged = self._overflow_unlogged.pop(agent_id, 0)- self._overflow_warned_at[agent_id] = now- # The agent is a field as well as being in the message: this fires- # from the buffer's own bookkeeping rather than from anything the- # agent called, so there is no request context to inherit it from,- # and "which agent is falling behind" is the only question this- # line is ever read to answer.- with log_context(agent_id=agent_id):- logger.warning(- "[EVENT-BUF] agent=%s exceeded %s buffered events; dropped "- "through seq=%s in rooms %s, plus %s dropped since the last "- "warning; readers resuming from before this will be told they "- "missed events",- agent_id,- self._max_events,- max(dropped.values()),- ", ".join(sorted(dropped)),- unlogged,- )+def _counting(agent_id: str, room_id: str, *, baseline: Any, occupant: Reader) -> Any:+ """An insert of an `agent_room_reads` row, selected from `rooms` so that it+ inserts nothing when the room does not exist.++ A room can be deleted while a reader still delivers it. The insert then+ does nothing, instead of failing the reader's stream on the foreign key.+ """+ return insert(AgentRoomRead).from_select(+ [+ AgentRoomRead.tenant_id,+ AgentRoomRead.agent_id,+ AgentRoomRead.room_id,+ AgentRoomRead.caught_up_seq,+ AgentRoomRead.occupant_id,+ AgentRoomRead.occupant_is_session,+ ],+ select(+ Room.tenant_id,+ literal(agent_id),+ Room.id,+ baseline,+ literal(occupant.id),+ literal(occupant.is_session),+ ).where(Room.id == room_id),+ )+++def _window_start(room_id: str, cutoff: datetime) -> Any:+ """A query for the `messages.seq` of the room's newest row sent before+ `cutoff`. It reads one entry of the room's `sent_at` index instead of+ scanning every row sent since."""+ return (+ select(Message.seq)+ .where(Message.room_id == room_id, Message.sent_at < cutoff)+ .order_by(Message.sent_at.desc())+ .limit(1)+ )+++def _room_head(room_id: str) -> Any:+ """The room's highest `messages.seq` (0 when it has none), as a subquery+ to use inside an insert."""+ return (+ select(func.coalesce(func.max(Message.seq), 0))+ .where(Message.room_id == room_id)+ .scalar_subquery()+ )+++def _by_source(events: list[BufferedEvent]) -> list[list[BufferedEvent]]:+ """Events split by the source they came from, each in its own order."""+ sources: dict[str, list[BufferedEvent]] = {}+ for item in events:+ sources.setdefault(item.source, []).append(item)+ return list(sources.values())+++def _interleaved(sources: list[list[BufferedEvent]]) -> list[BufferedEvent]:+ """Merge several sources' events into one list, earliest first.++ Only the next event of each source is compared, so each source's events+ stay in their own order. That order is what makes it safe to move a+ reader's position after each delivered event. Events from different+ sources are merged by when they happened.+ """+ heads = [0] * len(sources)+ out: list[BufferedEvent] = []+ while True:+ best: int | None = None+ for index, items in enumerate(sources):+ if heads[index] >= len(items):+ continue+ if best is None or items[heads[index]].at < sources[best][heads[best]].at:+ best = index+ if best is None:+ return out+ out.append(sources[best][heads[best]])+ heads[best] += 1diff --git a/core/switch_core/bridges/agent/protocol/message_events.py b/core/switch_core/bridges/agent/protocol/message_events.pynew file mode 100644index 000000000..b8c9fc0e9--- /dev/null+++ b/core/switch_core/bridges/agent/protocol/message_events.py@@ -0,0 +1,114 @@+"""Builds the agent event for a room message or join, for every code path.++A room row reaches an agent in one of two ways. `AgentConsumer` builds an event+when the row is delivered and is for the agent (an addressed message, a join it+listens for), and writes it to the agent's own events (`agent_events`), the+events meant for the agent, not ones it sent. `EventBuffer` builds one later+from the `messages` row itself, for a reader that asked for the rest of the+room's conversation too. Both call the functions here, so the agent receives+the same event whichever path produced it.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++from switch_core.bridges.agent.protocol.types import (+ AgentEvent,+ AttachmentRef,+ MessagePayload,+ RoomJoinPayload,+)+from switch_core.clients.admin_messages import PLATFORM_MARKER, platform_on_behalf_of++if TYPE_CHECKING:+ from switch_core.transport.types import InboundMedia, InboundMessage+++def attachment_ref(event: InboundMedia) -> AttachmentRef:+ """The file a media event carries. When the file was sent with a caption,+ `body` is the caption and the filename is in `filename`; without a+ caption, `body` is the filename."""+ return AttachmentRef(+ filename=event.filename or event.body,+ mimetype=event.mimetype or "",+ size=event.size or 0,+ mxc=event.uri,+ msgtype=event.msgtype,+ )+++def message_event(+ *,+ room_id: str,+ bridge_id: str | None,+ channel_type: str | None,+ event: InboundMessage,+ addressed: bool,+ sender_name: str,+ body: str,+ thread_id: str | None,+ attachments: list[AttachmentRef] | None = None,+) -> AgentEvent:+ """Build the `message` event the agent receives, with any attached files.++ When a platform client posted the message on behalf of a person, the+ event names that person as the sender (and in `on_behalf_of`), because+ the agent should answer the person and not the client that carried the+ message.+ """+ sender_kind: str | None = None+ on_behalf_of: str | None = None+ if PLATFORM_MARKER in event.content:+ sender_kind = "platform"+ person = platform_on_behalf_of(event.content)+ if person is not None:+ on_behalf_of = person.name+ sender_name = person.name+ return AgentEvent(+ type="message",+ room_id=room_id,+ bridge_id=bridge_id,+ channel_type=channel_type,+ payload=MessagePayload(+ addressed=addressed,+ sender=event.sender,+ sender_name=sender_name,+ sender_kind=sender_kind,+ on_behalf_of=on_behalf_of,+ message_id=event.event_id,+ body=body,+ timestamp=event.timestamp,+ thread_id=thread_id,+ attachments=attachments or [],+ ),+ )+++def room_join_event(+ *,+ room_id: str,+ bridge_id: str | None,+ channel_type: str | None,+ member: str,+ member_name: str,+ timestamp: int,+ listening: bool,+) -> AgentEvent:+ """Build the `room_join` event for someone arriving in a room.++ `listening` says whether this agent is set to receive join events in that+ room. The rest of the event is the same either way.+ """+ return AgentEvent(+ type="room_join",+ room_id=room_id,+ bridge_id=bridge_id,+ channel_type=channel_type,+ payload=RoomJoinPayload(+ member=member,+ member_name=member_name,+ timestamp=timestamp,+ listening=listening,+ ),+ )diff --git a/core/switch_core/bridges/agent/protocol/positions.py b/core/switch_core/bridges/agent/protocol/positions.pynew file mode 100644index 000000000..f59aa9339--- /dev/null+++ b/core/switch_core/bridges/agent/protocol/positions.py@@ -0,0 +1,83 @@+"""Positions record how far a reader of an agent's events has read, with one+number per source.++An agent's events come from more than one table. Its own events are the events+meant for the agent (addressed messages, room joins it listens for, task+events, commands), not ones it sent. They are rows in `agent_events`, numbered+per agent (`agent_events.seq`). The rest of each room's conversation is read+from `messages`, which numbers each room separately (`messages.seq`). One+number cannot say how far a reader has got in several separately numbered+lists, so a position holds one number per source.+`{"s": 18, "r:<room_id>": 43}` means the reader has read the agent's own events+up to 18 and that room up to 43.++Two positions merge by taking the larger number for each source (`merged`).+The result does not depend on the order positions arrive in or on how often+the same one arrives, so a duplicated event, sources delivered out of step+with each other, and two processes reporting progress in either order all+leave the reader at the same position.+"""++from __future__ import annotations++import json+from typing import Any++#: The position key for the agent's own events, its rows in `agent_events`.+OWN_EVENTS = "s"++_ROOM_PREFIX = "r:"++Position = dict[str, int]+++def room_source(room_id: str) -> str:+ """Return the position key for a room's conversation, `r:<room_id>`."""+ return f"{_ROOM_PREFIX}{room_id}"+++def room_of(source: str) -> str | None:+ """Return the room id a position key names, or None for the own-events key."""+ return source[len(_ROOM_PREFIX) :] if source.startswith(_ROOM_PREFIX) else None+++def merged(current: Position, reported: Position) -> Position:+ """Return the join (least upper bound) of two positions in their+ join-semilattice: each source at the further of the two, never moving back.++ A source present in only one of them keeps that number. This matches+ `furthest` in console/packages/switch-agent-runtime/src/positions.ts.+ """+ out = dict(current)+ for source, seq in reported.items():+ if seq > out.get(source, -1):+ out[source] = seq+ return out+++def parse(raw: Any) -> Position:+ """Parse a position sent by a client, raising ValueError if it is invalid.++ A position is a JSON object, or a string holding one, that maps each source+ to a non-negative integer. A source must be the own-events key `s` or a+ room key `r:<room_id>`. An unknown key is refused rather than stored, so a client+ that misspells a key gets an error instead of an entry that never moves.+ """+ if isinstance(raw, str):+ try:+ raw = json.loads(raw)+ except ValueError as exc:+ raise ValueError("a position is a JSON object") from exc+ if not isinstance(raw, dict):+ raise ValueError("a position is an object of source to sequence number")+ position: Position = {}+ for source, seq in raw.items():+ if not isinstance(source, str) or not (+ source == OWN_EVENTS+ or (source.startswith(_ROOM_PREFIX) and room_of(source))+ ):+ raise ValueError(f"unknown position source {source!r}")+ if isinstance(seq, bool) or not isinstance(seq, int) or seq < 0:+ raise ValueError(f"position {source!r} must be a non-negative integer")+ position[source] = seq+ return positiondiff --git a/core/switch_core/bridges/agent/protocol/stream.py b/core/switch_core/bridges/agent/protocol/stream.pyindex 6ec4ee2f8..ef057952d 100644--- a/core/switch_core/bridges/agent/protocol/stream.py+++ b/core/switch_core/bridges/agent/protocol/stream.py@@ -6,10 +6,17 @@ never asks again; it opens once and reads. `api/handlers.py` sends them overthe WebSocket, or, for a client built before it, as a Server-Sent Eventsstream: both encode the same frames from the same loop, so they cannot drift.-Every event carries its sequence number, so a client that reconnects names the-last one it processed and resumes exactly where it stopped. Gaps are reported-as their own event rather than skipped: a client that has missed events must-never see a stream that looks complete.+Every event says where it sits, so a client that reconnects can say how far it+got and resume exactly where it stopped. A client on agent-protocol revision 9+or later receives `position` on each event: the event's source and its number+there. The source is `s` for the agent's own events in `agent_events` (the+events meant for the agent, not ones it sent) or `r:<room_id>` for a room's+messages. An older client holds a single number, sent as `sequence`. For a+client that receives only the agent's own events it is the event's number among+them. For a client that receives every room message it is a ticket, a number+the server maps back to a full position when the client resumes. Gaps are+reported as their own event rather than skipped: a client that has missed+events must never see a stream that looks complete."""from __future__ import annotations@@ -32,9 +39,15 @@ from switch_core.bridges.agent.protocol.agent_connections import (Closure,)from switch_core.bridges.agent.protocol.event_buffer import (+ BufferedEvent,CursorExpiredError,EventBuffer,)+from switch_core.bridges.agent.protocol.positions import (+ OWN_EVENTS,+ Position,+ room_source,+)from switch_core.observability.catalogue import BRIDGE_EVENTS_OUTfrom switch_core.observability.metrics import metricsfrom switch_core.tenant_context import current_tenant_id@@ -139,6 +152,7 @@ def _connection_state(conn: AgentConnection) -> dict[str, Any]:"spawn_capable": conn.spawn_capable,"rooms": sorted(conn.rooms),"cursor": conn.cursor,+ "position": dict(conn.position),"protocol": PROTOCOL_VERSION,"heartbeat_interval_seconds": 2.0,"server": server_declaration("agent-protocol"),@@ -194,6 +208,9 @@ async def _event_stream(last_rooms = set(conn.rooms)tenant_id = current_tenant_id()+ if tenant_id is None:+ raise RuntimeError("An agent stream runs inside its agent's tenant")+ tenant: str = tenant_id# Approval answers and expiries, for the agent's own stream only: the# watcher that routes work to its sessions. Owed ones are read on opening@@ -205,7 +222,6 @@ async def _event_stream(speaks = conn.declaration.speaksif (approvals is not None- and tenant_id is not Noneand conn.scope == "all"and speaks is not Noneand speaks >= APPROVAL_OUTCOME_PROTOCOL_REVISION@@ -219,104 +235,26 @@ async def _event_stream(resync[0] = Trueconn.wake.set()- unsubscribe_outcomes = approvals.subscribe(tenant_id, agent_id, owe, recheck)+ unsubscribe_outcomes = approvals.subscribe(tenant, agent_id, owe, recheck)resync[0] = True+ # Rooms this stream has already passed to `EventBuffer.ensure_counting`,+ # which gives the agent an unread-count baseline for the room in+ # `agent_room_reads`. Each pass of the loop calls it only for rooms not in+ # this set, so it does not write to the database for every room each time.+ counted: set[str] = set()+ last_keepalive = time.monotonic()try:+ if conn.reads_conversation:+ # The client learns its starting position from `connection_state`.+ # A client that reconnects before any room message arrives resumes+ # from that position, so each room must already be in it. A room+ # missing from it would start at the room's newest message on the+ # reconnect, and the messages sent in between would never arrive.+ await _place_in_conversation(conn, registry, buffer, tenant)yield _frame("connection_state", _connection_state(conn))- # A cursor ahead of everything we hold is a cursor from a previous- # life of this process: the buffer is in memory, so a restart resets- # the sequence. Say so. Staying quiet would leave the client believing- # it is caught up when its numbering no longer means anything.- head = buffer.head(agent_id)- floor = buffer.sequence_floor- if 0 < conn.cursor < floor - 1:- # Every boot numbers above the previous one, so a cursor below this- # boot's floor is one a restart left behind. The client keeps its- # sequence-based dedupe (nothing is reused); what it has lost is- # every event the old buffer held.- logger.warning(- "[STREAM] agent=%s connection=%s resumed from cursor %s of an "- "earlier server boot (this boot starts at %s)",- agent_id,- conn.id,- conn.cursor,- floor,- )- previous = conn.cursor- conn.cursor = floor - 1- buffer.mark_restarted(agent_id)- yield _frame(- "gap",- {- "from_sequence": previous,- "resumed_at": conn.cursor,- "rooms": sorted(conn.rooms),- "all_rooms": True,- "reason": "the server restarted since your last connection; "- "events from before the restart are gone in every room, "- "including any this connection has yet to claim — re-read "- "room context",- },- )- elif conn.cursor > head:- logger.warning(- "[STREAM] agent=%s connection=%s resumed from cursor %s but the "- "buffer only reaches %s — treating as a restart",- agent_id,- conn.id,- conn.cursor,- head,- )- conn.cursor = head- # Every room of this agent loses its baseline with the buffer that- # held it, not only the rooms this connection has named — it may- # have named none, and its sessions claim theirs later. Starting a- # fresh baseline for any of them would answer the next "how far- # behind am I in this room" with a zero the agent has no reason to- # doubt.- buffer.mark_restarted(agent_id)- yield _frame(- "gap",- {- "from_sequence": head,- "resumed_at": head,- "rooms": sorted(conn.rooms),- "all_rooms": True,- "reason": "the server restarted since your last connection; "- "sequence numbers have been reset and events from before "- "the restart are gone in every room, including any this "- "connection has yet to claim — re-read room context",- },- )-- # A cursor the buffer can no longer serve is reported, not silently- # moved to head. The client re-reads room context to recover.- lost = buffer.rooms_dropped_after(agent_id, conn.cursor)- if lost:- oldest = buffer.oldest_retained(agent_id)- logger.warning(- "[STREAM] agent=%s connection=%s resumed from expired cursor %s "- "(oldest retained %s, rooms %s)",- agent_id,- conn.id,- conn.cursor,- oldest,- ", ".join(lost),- )- resumed_at = max(oldest - 1, 0)- conn.cursor = resumed_at- yield _frame(- "gap",- {- "from_sequence": conn.cursor,- "resumed_at": resumed_at,- "rooms": list(lost),- "all_rooms": False,- "reason": "events older than the retention window were "- "dropped; re-read room context",- },- )+ for gap in await _opening_gaps(conn, buffer, tenant):+ yield _frame("gap", gap)while True:if conn.stream_generation != generation:@@ -378,8 +316,9 @@ async def _event_stream(if conn.scope == "single" and not conn.rooms:# A session connection that has not claimed a room yet must not# read. It would find every event uncovered — it covers nothing- # — and the skip path advances the cursor, so it would consume- # its way to the end of the buffer while waiting for its room.+ # — and the skip path advances the position, so it would consume+ # its way to the end of the agent's events while waiting for its+ # room.## That window is not an edge case: a session spawned to answer a# message opens its connection *before* the session boots and@@ -388,95 +327,119 @@ async def _event_stream(## Park until a room is claimed. `claim_room` sets `wake`, so the# loop resumes the moment there is something to cover, with the- # cursor still where it started.+ # position still where it started.conn.wake.clear()if not conn.rooms and not await _wait_for_wake(conn):yield KEEPALIVEcontinue- # Where counting starts for a room nothing is counting yet. It is- # the cursor rather than head because the backlog this connection- # is about to work through is backlog it genuinely has not seen; a- # room covered later starts from wherever the cursor has reached by- # then, which is the same rule. Covering is not taking: the room- # slot changes hands at the doors, not on every pass of this loop.- for room_id in conn.rooms:- buffer.ensure_counting(agent_id, conn.id, room_id, conn.cursor)+ # Give each room this connection covers an unread-count baseline at+ # the room's newest message if it has none yet. A room the+ # connection starts covering later gets its baseline when this loop+ # first sees it. This never takes the room's count from another+ # connection; that happens through `take_counting` when a connection+ # opens on a room or claims it, not on each pass here.+ for room_id in conn.rooms - counted:+ await buffer.ensure_counting(tenant, agent_id, conn.id, room_id)+ counted.add(room_id)++ conversation_rooms: set[str] = set()+ if conn.reads_conversation:+ conversation_rooms = await _place_in_conversation(+ conn, registry, buffer, tenant+ )try:- pending = buffer.read_from(+ pending, looked = await buffer.read(+ tenant,agent_id,- conn.cursor,- notifiable_only=conn.delivery_filter == "addressed",+ conn.position,+ conversation_rooms=conversation_rooms,+ notifiable_only=not conn.reads_conversation,limit=CATCH_UP_BATCH,)except CursorExpiredError as exc:+ conn.position[OWN_EVENTS] = exc.resume_afteryield _frame("gap",- {- "from_sequence": exc.requested,- "resumed_at": max(exc.oldest - 1, 0),- "rooms": list(exc.rooms),- "all_rooms": False,- "reason": str(exc),- },+ await _gap(+ conn,+ buffer,+ tenant,+ from_sequence=exc.requested,+ rooms=list(exc.rooms),+ all_rooms=False,+ reason=str(exc),+ ),)- conn.cursor = max(exc.oldest - 1, 0)continue- if not pending:- # Nothing above the cursor is for this connection: the filter- # excluded all of it. Advance past it anyway.- #- # `read_from` does not return filtered-out events, so the cursor- # cannot advance through them the way it does for events skipped- # by room coverage below. Leaving it behind them makes the- # "anything new?" re-check further down permanently true, and- # this loop spins at full speed instead of waiting — starving the- # event loop, so no heartbeat is processed, so every connection- # in the process is declared dead and reconnects, forever.- #- # Nothing is lost by moving past them: the cursor records what- # has been written out, not what the agent has caught up on.- # The events stay in the buffer and each room's watermark stays- # where it was, so what was skipped here is still countable.- #- # An empty result means the scan reached the end without hitting- # the batch limit, so head is exactly how far we have looked.- head = buffer.head(agent_id)- if head > conn.cursor:- conn.cursor = head-+ # Room coverage is evaluated per event rather than up front: a+ # sibling claiming a room must take effect immediately, without+ # tearing the stream down. One of the agent's own events for a room+ # this connection does not cover is not sent, but the position+ # still moves past it, in order: only once every event before it+ # has gone out, so the position never says the client was sent+ # an event that is still to come. Room messages need no check+ # here, because `_conversation_rooms` only returned rooms this+ # connection covers.+ covered = [+ item.source != OWN_EVENTS or registry.covers(conn, item.room_id)+ for item in pending+ ]+ tickets = await _tickets_for(conn, buffer, tenant, pending, covered)delivered = False- for item in pending:- # Room coverage is evaluated per event rather than up front: a- # sibling claiming a room must take effect immediately, without- # tearing the stream down.- if not registry.covers(conn, item.room_id):- conn.cursor = item.seq+ index = -1+ for item, send in zip(pending, covered, strict=True):+ if not send:+ if item.seq > conn.position.get(OWN_EVENTS, -1):+ conn.position[OWN_EVENTS] = item.seqcontinue+ index += 1payload = item.event.model_dump(mode="json")- payload["sequence"] = item.seq+ frame_seq = _number_for(conn, item, tickets, index)+ if frame_seq is not None:+ payload["sequence"] = frame_seq+ if conn.speaks_positions:+ payload["position"] = {item.source: item.seq}if item.notifiable:# Told on the way past, on the one event the agent is being# woken for anyway. A count of its own would be a wake# spent on "you may have missed something you may not care# about".- unread = buffer.unread(agent_id, item.room_id, item.seq)+ unread = await buffer.unread(+ tenant, agent_id, item.room_id, item.room_seq+ )payload["missed"] = {"count": unread.count,"reason": unread.reason,}- # Advance before yielding: the cursor tracks what the server has- # written out. What the client has actually processed comes back- # on its heartbeat, which is the value that governs resume.- conn.cursor = item.seq+ # Advance before yielding, because the position records what+ # the server has written out. Where the client resumes after a+ # drop is its own position, which it sends when it reopens.+ if item.seq > conn.position.get(item.source, -1):+ conn.position[item.source] = item.seq+ if tickets:+ conn.ticket = tickets[index]delivered = Truemetrics().increment(BRIDGE_EVENTS_OUT,{"bridge": "agent", "platform": "switch", "kind": item.event.type},)- yield _frame(item.event.type, payload, seq=item.seq)+ yield _frame(item.event.type, payload, seq=frame_seq)++ # Move the position past every row the read examined, including+ # rows it did not return: own events the `addressed` filter left+ # out, and room messages that are not conversation for this agent+ # (messages it sent, or ones already among its own events). Nothing+ # is lost, because the position records what the server has written+ # out, not what the agent has caught up on, and those rows still+ # count towards the agent's unread counts. If the position stayed+ # behind them, the "anything new?" check below would stay true and+ # the loop would spin instead of waiting.+ for source, seq in looked.items():+ if seq > conn.position.get(source, -1):+ conn.position[source] = seqif delivered:continue@@ -490,12 +453,29 @@ async def _event_stream(or conn.released_roomsor outcomesor resync[0]- or buffer.head(agent_id) > conn.cursor+ or await buffer.head(tenant, agent_id)+ > conn.position.get(OWN_EVENTS, 0)or conn.rooms != last_rooms):continue- if not await _wait_for_work(bell, conn):+ # New room messages do not ring the doorbell; only the agent's own+ # events do. A room message newer than the newest of the agent's+ # own events in that room is read only once it is `settle_seconds`+ # old, which gives the agent's consumer time to add it to the+ # agent's own events first if it is for the agent. A stream that+ # receives every room message therefore wakes every+ # `settle_seconds` to read messages that have settled, instead of+ # sleeping for the whole keepalive interval.+ timeout = (+ buffer.settle_seconds+ if conn.reads_conversation+ else KEEPALIVE_INTERVAL_SECONDS+ )+ if await _wait_for_work(bell, conn, timeout):+ continue+ if time.monotonic() - last_keepalive >= KEEPALIVE_INTERVAL_SECONDS:+ last_keepalive = time.monotonic()yield KEEPALIVEfinally:if unsubscribe_outcomes is not None:@@ -503,6 +483,279 @@ async def _event_stream(registry.detach_stream(conn, generation)+async def _gap(+ conn: AgentConnection,+ buffer: EventBuffer,+ tenant: str,+ *,+ from_sequence: int,+ rooms: list[str],+ all_rooms: bool,+ reason: str,+) -> dict[str, Any]:+ """Build a gap frame from the connection's current position.++ `resumed_position` is the position the stream continues from. `resumed_at`+ is the single number an older client adopts instead. For most clients it is+ the `s` entry, the place in the agent's own events. A client that receives+ every room message but holds a single number is sent a new ticket for the+ whole position. If that client were sent the `s` entry and later resumed+ from it, the server would treat the number as an own-events place only,+ start every room again at its newest message, and the client would never+ receive the room messages it had not read yet.+ """+ resumed_at = conn.position.get(OWN_EVENTS, 0)+ if conn.reads_conversation and not conn.speaks_positions:+ (resumed_at,) = await buffer.mint_tickets(+ tenant, conn.agent_id, [dict(conn.position)]+ )+ conn.ticket = resumed_at+ return {+ "from_sequence": from_sequence,+ "resumed_at": resumed_at,+ "resumed_position": dict(conn.position),+ "rooms": rooms,+ "all_rooms": all_rooms,+ "reason": reason,+ }+++async def _opening_gaps(+ conn: AgentConnection, buffer: EventBuffer, tenant: str+) -> list[dict[str, Any]]:+ """Check the position the client resumed from, and return the gap frames+ to send before any event.++ A gap is due when the client resumed from a ticket the server does not+ have, from an own-events number issued before this agent's current+ numbering started, from a number past the newest of the agent's own events,+ from a room place past that room's newest message, or from a point older+ than the events still retained. Each case is reported rather than corrected+ quietly. A client that believes it is caught up when its numbers no longer+ mean anything would never re-read what it lost.+ """+ agent_id = conn.agent_id+ gaps: list[dict[str, Any]] = []+ if conn.resume_lost:+ conn.resume_lost = False+ gaps.append(+ await _gap(+ conn,+ buffer,+ tenant,+ from_sequence=conn.resume_requested,+ rooms=sorted(conn.rooms),+ all_rooms=True,+ reason="where you left off is no longer known to the server; "+ "re-read room context",+ )+ )+ return gaps++ at = conn.position.get(OWN_EVENTS, 0)+ head = await buffer.head(tenant, agent_id)+ floor = await buffer.first_seq(tenant, agent_id)+ if 0 < at < floor - 1:+ # The number is below where the numbering of this agent's own events+ # starts (`first_seq`), so an earlier server issued it and those events+ # are gone. New numbering always starts above every earlier number, so+ # the client's dedupe by sequence number stays valid. The client has+ # lost every event from before.+ logger.warning(+ "[STREAM] agent=%s connection=%s resumed from cursor %s of an "+ "earlier server boot (this agent's events start at %s)",+ agent_id,+ conn.id,+ at,+ floor,+ )+ conn.position[OWN_EVENTS] = floor - 1+ gaps.append(+ await _gap(+ conn,+ buffer,+ tenant,+ from_sequence=at,+ rooms=sorted(conn.rooms),+ all_rooms=True,+ reason="the server restarted since your last connection; "+ "events from before the restart are gone in every room, "+ "including any this connection has yet to claim — re-read "+ "room context",+ )+ )+ at = floor - 1+ elif at > head:+ logger.warning(+ "[STREAM] agent=%s connection=%s resumed from cursor %s but the "+ "agent's events only reach %s — treating as a restart",+ agent_id,+ conn.id,+ at,+ head,+ )+ conn.position[OWN_EVENTS] = head+ gaps.append(+ await _gap(+ conn,+ buffer,+ tenant,+ from_sequence=head,+ rooms=sorted(conn.rooms),+ all_rooms=True,+ reason="the server restarted since your last connection; "+ "sequence numbers have been reset and events from before "+ "the restart are gone in every room, including any this "+ "connection has yet to claim — re-read room context",+ )+ )+ at = head++ # A room place past the room's newest message comes from a history the+ # room no longer has, for example after a database restore. Positions never+ # move back, so if it were kept the stream would skip that many of the+ # room's next messages without telling the client.+ within, past = await buffer.within_rooms(tenant, conn.position)+ if past:+ logger.warning(+ "[STREAM] agent=%s connection=%s resumed past the end of rooms %s",+ agent_id,+ conn.id,+ ", ".join(past),+ )+ conn.position.update(within)+ gaps.append(+ await _gap(+ conn,+ buffer,+ tenant,+ from_sequence=at,+ rooms=past,+ all_rooms=False,+ reason="these rooms no longer reach where you left off; "+ "re-read room context",+ )+ )++ # If retention has deleted any of the agent's own events after the client's+ # number, report a gap instead of quietly moving the client to the newest+ # event. The client recovers by re-reading room context.+ try:+ await buffer.check_cursor(tenant, agent_id, at)+ except CursorExpiredError as exc:+ logger.warning(+ "[STREAM] agent=%s connection=%s resumed from expired cursor %s "+ "(oldest retained %s, rooms %s)",+ agent_id,+ conn.id,+ at,+ exc.oldest,+ ", ".join(exc.rooms),+ )+ conn.position[OWN_EVENTS] = exc.resume_after+ gaps.append(+ await _gap(+ conn,+ buffer,+ tenant,+ from_sequence=at,+ rooms=list(exc.rooms),+ all_rooms=False,+ reason="events older than the retention window were "+ "dropped; re-read room context",+ )+ )+ return gaps+++async def _conversation_rooms(+ conn: AgentConnection,+ registry: AgentConnectionRegistry,+ buffer: EventBuffer,+ tenant: str,+) -> set[str]:+ """Return the rooms whose every message this connection receives.++ A session connection (scope `single`) receives the room it has claimed. A+ connection over all of the agent's rooms receives each room the agent is a+ member of, except rooms another connection of the same agent has claimed.+ """+ if conn.scope == "single":+ return set(conn.rooms)+ member = await buffer.member_rooms(tenant, conn.agent_id)+ return {room_id for room_id in member if registry.covers(conn, room_id)}+++async def _place_in_conversation(+ conn: AgentConnection,+ registry: AgentConnectionRegistry,+ buffer: EventBuffer,+ tenant: str,+) -> set[str]:+ """Return the rooms whose conversation this connection receives, after+ giving each room it has no place in yet a place at the room's newest+ message.++ A room with no entry in the connection's position has never been read by+ this connection. Its earlier messages are history the agent can fetch with+ `read_context`; sending them all as new events would bury the agent in a+ backlog.+ """+ rooms = await _conversation_rooms(conn, registry, buffer, tenant)+ fresh = {room_id for room_id in rooms if room_source(room_id) not in conn.position}+ for room_id, head in (await buffer.room_heads(tenant, fresh)).items():+ conn.position[room_source(room_id)] = head+ return rooms+++async def _tickets_for(+ conn: AgentConnection,+ buffer: EventBuffer,+ tenant: str,+ pending: list[BufferedEvent],+ covered: list[bool],+) -> list[int]:+ """Mint a ticket for each event about to be sent, for a client that+ receives every room message but holds a single number.++ `pending` is the batch in order and `covered` says which of its events+ are sent. Each ticket stands for the position just after its event,+ including the unsent events before it and none after it, so a client that+ reconnects with that number resumes after that event and misses nothing+ that comes later in the batch. Every other client gets an empty list.+ """+ if conn.speaks_positions or not conn.reads_conversation:+ return []+ positions: list[Position] = []+ position = dict(conn.position)+ for item, send in zip(pending, covered, strict=True):+ if item.seq > position.get(item.source, -1):+ position[item.source] = item.seq+ if send:+ positions.append(dict(position))+ if not positions:+ return []+ return await buffer.mint_tickets(tenant, conn.agent_id, positions)+++def _number_for(+ conn: AgentConnection, item: BufferedEvent, tickets: list[int], index: int+) -> int | None:+ """Return the `sequence` number to send with a delivered event.++ When the client is sent tickets, the number is the event's ticket.+ Otherwise one of the agent's own events carries its number in+ `agent_events`, and a room message carries none, because a client that+ receives room messages without tickets speaks positions and reads the+ message's place from `position`.+ """+ if tickets:+ return tickets[index]+ if item.source == OWN_EVENTS:+ return item.seq+ return None++async def _wait_for_wake(conn: AgentConnection) -> bool:"""Wait for the connection itself to change — a room claim, or a close.@@ -517,11 +770,15 @@ async def _wait_for_wake(conn: AgentConnection) -> bool:return False-async def _wait_for_work(bell: asyncio.Event, conn: AgentConnection) -> bool:+async def _wait_for_work(+ bell: asyncio.Event,+ conn: AgentConnection,+ timeout: float = KEEPALIVE_INTERVAL_SECONDS,+) -> bool:"""Wait for a new event or a change to the connection itself.- Returns False when neither happened before the keepalive interval, so the- caller can write a comment and keep the socket warm.+ Returns False when neither happened within `timeout`, so the caller can+ read again or send a keepalive."""waiters = [asyncio.ensure_future(bell.wait()),@@ -530,7 +787,7 @@ async def _wait_for_work(bell: asyncio.Event, conn: AgentConnection) -> bool:try:done, _ = await asyncio.wait(waiters,- timeout=KEEPALIVE_INTERVAL_SECONDS,+ timeout=timeout,return_when=asyncio.FIRST_COMPLETED,)return bool(done)diff --git a/core/switch_core/clients/agent_consumer.py b/core/switch_core/clients/agent_consumer.pyindex d0a58d848..0ac95941b 100644--- a/core/switch_core/clients/agent_consumer.py+++ b/core/switch_core/clients/agent_consumer.py@@ -18,6 +18,11 @@ from switch_core.bridges.agent.commands import ()from switch_core.bridges.agent.protocol.agent_connections import AgentConnectionRegistryfrom switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.message_events import (+ attachment_ref,+ message_event,+ room_join_event,+)from switch_core.bridges.agent.protocol.presence import (agents_present_in,rooms_occupied,@@ -26,8 +31,6 @@ from switch_core.bridges.agent.protocol.types import (AgentEvent,AttachmentRef,CommandPayload,- MessagePayload,- RoomJoinPayload,TaskAcceptPayload,TaskCancelPayload,TaskDelegatePayload,@@ -117,6 +120,10 @@ class _PendingAttachmentGroup:total: intparts: dict[int, AttachmentRef] = field(default_factory=dict)body: str = ""+ # The highest `messages.seq` among the parts received so far. The combined+ # message is written to the agent's own events with this as its `room_seq`,+ # the row of the part that completed the group.+ through_seq: int = 0# Whether any part of the group addressed this agent. Addressing is read off# the message text, and the text rides on part 0 alone — every other part's# body is its bare filename. Answering from whichever part completes the@@ -463,7 +470,7 @@ class AgentConsumer(Consumer[AgentActor]):meta = await self._resolve_room_meta(room.room_id)if meta is None:return- self._event_buffer.drop_room(self.agent.id, meta.room_id)+ await self._event_buffer.drop_room(self.tenant_id, self.agent.id, meta.room_id)self._connections.release_room_everywhere(self.agent.id, meta.room_id)self._connections.controllers.room_left(self.agent.id, meta.room_id)@@ -510,22 +517,27 @@ class AgentConsumer(Consumer[AgentActor]):listening = await self._room_store.get_receives_join_events(session, meta.room_id, self.agent.id)+ if not listening:+ # The agent does not listen for joins in this room, so the join+ # is not written to its own events. A reader that wants the+ # whole conversation still sees it, read from `messages`.+ returnmember_name = await self._member_name(session, event)- self._event_buffer.enqueue(+ await self._event_buffer.enqueue(+ self.tenant_id,self.agent.id,meta.room_id,- AgentEvent(- type="room_join",+ room_join_event(room_id=meta.room_id,bridge_id=meta.bridge_id,channel_type=meta.channel_type,- payload=RoomJoinPayload(- member=event.state_key,- member_name=member_name,- timestamp=event.timestamp,- listening=listening,- ),+ member=event.state_key,+ member_name=member_name,+ timestamp=event.timestamp,+ listening=listening,),+ room_seq=event.seq,+ message_key=event.event_id,)async def on_message(self, room: RoomRef, event: InboundMessage) -> None:@@ -578,33 +590,15 @@ class AgentConsumer(Consumer[AgentActor]):sender_name,)- sender_kind: str | None = None- on_behalf_of: str | None = None- if PLATFORM_MARKER in event.content:- sender_kind = "platform"- person = platform_on_behalf_of(event.content)- if person is not None:- # The agent answers the person the platform spoke for, not- # the admin client that carried the message.- on_behalf_of = person.name- sender_name = person.name-- agent_event = AgentEvent(- type="message",+ agent_event = message_event(room_id=meta.room_id,bridge_id=meta.bridge_id,channel_type=meta.channel_type,- payload=MessagePayload(- addressed=is_addressed,- sender=event.sender,- sender_name=sender_name,- sender_kind=sender_kind,- on_behalf_of=on_behalf_of,- message_id=event.event_id,- body=text,- timestamp=event.timestamp,- thread_id=thread_id,- ),+ event=event,+ addressed=is_addressed,+ sender_name=sender_name,+ body=text,+ thread_id=thread_id,)if is_addressed:@@ -636,13 +630,21 @@ class AgentConsumer(Consumer[AgentActor]):else reply_thread_root,)+ if not is_addressed:+ # An unaddressed message is not written to the agent's own events.+ # A reader that wants the whole conversation reads it from+ # `messages`.+ return# Serialising runs once per agent per message, so only when it will be seen.if logger.isEnabledFor(logging.DEBUG):logger.debug("Enqueuing event %s", agent_event.model_dump_json(indent=2))- self._event_buffer.enqueue(+ await self._event_buffer.enqueue(+ self.tenant_id,self.agent.id,meta.room_id,agent_event,+ room_seq=event.seq,+ message_key=event.event_id,)async def on_media(self, room: RoomRef, event: InboundMedia) -> None:@@ -652,15 +654,7 @@ class AgentConsumer(Consumer[AgentActor]):is_addressed = await self._addressed(event, meta)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.- attachment = AttachmentRef(- filename=event.filename or event.body,- mimetype=event.mimetype or "",- size=event.size or 0,- mxc=event.uri,- msgtype=event.msgtype,- )+ attachment = attachment_ref(event)sender_name = event.sender_nameif not sender_name:@@ -688,6 +682,8 @@ class AgentConsumer(Consumer[AgentActor]):thread_id,[attachment],event.body,+ room_seq=event.seq,+ message_key=event.event_id,)return@@ -697,6 +693,7 @@ class AgentConsumer(Consumer[AgentActor]):)pending.parts[index] = attachmentpending.addressed = pending.addressed or is_addressed+ pending.through_seq = max(pending.through_seq, event.seq)if index == 0:pending.body = event.bodypending.first_event = event@@ -719,6 +716,8 @@ class AgentConsumer(Consumer[AgentActor]):thread_id,[pending.parts[i] for i in sorted(pending.parts)],pending.body or event.body,+ room_seq=pending.through_seq,+ message_key=group_id,)def _schedule_attachment_group_flush(@@ -796,6 +795,8 @@ class AgentConsumer(Consumer[AgentActor]):thread_id,[pending.parts[i] for i in sorted(pending.parts)],f"{body}\n{notice}" if body else notice,+ room_seq=pending.through_seq,+ message_key=group_id,)async def _emit_media(@@ -808,6 +809,9 @@ class AgentConsumer(Consumer[AgentActor]):thread_id: str | None,attachments: list[AttachmentRef],body: str,+ *,+ room_seq: int,+ message_key: str,) -> None:reply_thread_root = thread_id if thread_id is not None else event.event_idagent_live = False@@ -828,34 +832,16 @@ class AgentConsumer(Consumer[AgentActor]):await self._post_auto_reply(room.room_id, event, gate.refusal, reply_thread_root)- sender_kind: str | None = None- on_behalf_of: str | None = None- if PLATFORM_MARKER in event.content:- sender_kind = "platform"- person = platform_on_behalf_of(event.content)- if person is not None:- # The agent answers the person the platform spoke for, not- # the admin client that carried the message.- on_behalf_of = person.name- sender_name = person.name-- agent_event = AgentEvent(- type="message",+ agent_event = message_event(room_id=meta.room_id,bridge_id=meta.bridge_id,channel_type=meta.channel_type,- payload=MessagePayload(- addressed=is_addressed,- sender=event.sender,- sender_name=sender_name,- sender_kind=sender_kind,- on_behalf_of=on_behalf_of,- message_id=event.event_id,- body=body,- timestamp=event.timestamp,- thread_id=thread_id,- attachments=attachments,- ),+ event=event,+ addressed=is_addressed,+ sender_name=sender_name,+ body=body,+ thread_id=thread_id,+ attachments=attachments,)if is_addressed:@@ -863,14 +849,19 @@ class AgentConsumer(Consumer[AgentActor]):meta, event, agent_live=agent_live, has_attachment=True)+ if not is_addressed:+ returnif logger.isEnabledFor(logging.DEBUG):logger.debug("Enqueuing media event %s", agent_event.model_dump_json(indent=2))- self._event_buffer.enqueue(+ await self._event_buffer.enqueue(+ self.tenant_id,self.agent.id,meta.room_id,agent_event,+ room_seq=room_seq,+ message_key=message_key,)async def on_command(self, room: RoomRef, event: CommandEvent) -> None:@@ -898,7 +889,8 @@ class AgentConsumer(Consumer[AgentActor]):if handled:return- self._event_buffer.enqueue(+ await self._event_buffer.enqueue(+ self.tenant_id,self.agent.id,meta.room_id,AgentEvent(@@ -913,6 +905,8 @@ class AgentConsumer(Consumer[AgentActor]):user_name=event.user_name,),),+ room_seq=event.room_seq,+ message_key=event.message_id,)async def _command_targets_me_explicitly(@@ -1358,7 +1352,14 @@ class AgentConsumer(Consumer[AgentActor]):)if meta is None or agent_event is None:return- self._event_buffer.enqueue(self.agent.id, meta.room_id, agent_event)+ await self._event_buffer.enqueue(+ self.tenant_id,+ self.agent.id,+ meta.room_id,+ agent_event,+ room_seq=event.room_seq,+ message_key=event.source_event_id,+ )async def on_task_accept(self, room: RoomRef, event: TaskAccept) -> None:if event.requester_agent_id != self.agent.id:@@ -1366,7 +1367,8 @@ class AgentConsumer(Consumer[AgentActor]):meta = await self._resolve_room_meta(room.room_id)if meta is None:return- self._event_buffer.enqueue(+ await self._event_buffer.enqueue(+ self.tenant_id,self.agent.id,meta.room_id,AgentEvent(@@ -1380,6 +1382,8 @@ class AgentConsumer(Consumer[AgentActor]):performer_agent_id=event.performer_agent_id,),),+ room_seq=event.room_seq,+ message_key=event.source_event_id,)async def on_task_update(self, room: RoomRef, event: TaskUpdate) -> None:@@ -1388,7 +1392,8 @@ class AgentConsumer(Consumer[AgentActor]):meta = await self._resolve_room_meta(room.room_id)if meta is None:return- self._event_buffer.enqueue(+ await self._event_buffer.enqueue(+ self.tenant_id,self.agent.id,meta.room_id,AgentEvent(@@ -1403,6 +1408,8 @@ class AgentConsumer(Consumer[AgentActor]):update=event.update,),),+ room_seq=event.room_seq,+ message_key=event.source_event_id,)async def on_task_finalise(self, room: RoomRef, event: TaskFinalise) -> None:@@ -1411,7 +1418,8 @@ class AgentConsumer(Consumer[AgentActor]):meta = await self._resolve_room_meta(room.room_id)if meta is None:return- self._event_buffer.enqueue(+ await self._event_buffer.enqueue(+ self.tenant_id,self.agent.id,meta.room_id,AgentEvent(@@ -1426,6 +1434,8 @@ class AgentConsumer(Consumer[AgentActor]):outcome=event.outcome,),),+ room_seq=event.room_seq,+ message_key=event.source_event_id,)async def on_task_cancel(self, room: RoomRef, event: TaskCancel) -> None:@@ -1434,7 +1444,8 @@ class AgentConsumer(Consumer[AgentActor]):meta = await self._resolve_room_meta(room.room_id)if meta is None:return- self._event_buffer.enqueue(+ await self._event_buffer.enqueue(+ self.tenant_id,self.agent.id,meta.room_id,AgentEvent(@@ -1449,6 +1460,8 @@ class AgentConsumer(Consumer[AgentActor]):reason=event.reason,),),+ room_seq=event.room_seq,+ message_key=event.source_event_id,)# ── Mention detection ─────────────────────────────────────────────────────diff --git a/core/switch_core/clients/consumer.py b/core/switch_core/clients/consumer.pyindex b85d9a030..a58569f74 100644--- a/core/switch_core/clients/consumer.py+++ b/core/switch_core/clients/consumer.py@@ -308,6 +308,8 @@ class Consumer[ActorT: Actor[Any]]:if isinstance(typed_event, CommandEvent):typed_event.message_id = event.event_idtyped_event.thread_id = event.thread_root_id or event.event_id+ typed_event.room_seq = event.seq+ typed_event.source_event_id = event.event_idtry:await getattr(self, method_name)(room, typed_event)diff --git a/core/switch_core/config.py b/core/switch_core/config.pyindex 13b8ee85e..a581945b7 100644--- a/core/switch_core/config.py+++ b/core/switch_core/config.py@@ -663,6 +663,11 @@ class SwitchConfig(BaseSettings):# controller access token's reads (its controller row, and the agent row# it acts as), which a revocation or binding change also drops at once.agent_auth_cache_ttl_seconds: float = 5.0+ # How long a row in `agent_events` (one of an agent's own events) is kept+ # before the retention loop deletes it. An agent that reconnects within+ # this window resumes without a gap; one away for longer is told it missed+ # events.+ agent_event_retention_seconds: float = Field(default=24 * 60 * 60, gt=0)# Bound on the memo. One entry per distinct live token; the oldest is# evicted past this, so a flood of tokens cannot grow the process.agent_auth_cache_max_entries: int = 4096diff --git a/core/switch_core/db/agent_event_notify_ddl.py b/core/switch_core/db/agent_event_notify_ddl.pynew file mode 100644index 000000000..1e70c65d0--- /dev/null+++ b/core/switch_core/db/agent_event_notify_ddl.py@@ -0,0 +1,40 @@+"""The trigger that sends a Postgres `NOTIFY` for each new row in `agent_events`.++It follows the design `notify_ddl.py` describes for `messages`. The payload+carries only the agent id and the new row's `seq`, never the event itself.+The notification wakes the server process that holds the agent's+connection, and that process reads the new rows from the table, so a lost+notification delays delivery but loses nothing.+`bridges/agent/protocol/agent_event_listener.py` is the process side that+listens on the channel.+"""++AGENT_EVENT_CHANNEL = "switch_agent_event"++AGENT_EVENT_NOTIFY_FUNCTION_NAME = "switch_notify_agent_event"+AGENT_EVENT_NOTIFY_TRIGGER_NAME = "agent_events_notify"++CREATE_AGENT_EVENT_NOTIFY_FUNCTION = f"""+CREATE OR REPLACE FUNCTION {AGENT_EVENT_NOTIFY_FUNCTION_NAME}() RETURNS trigger AS $$+BEGIN+ PERFORM pg_notify(+ '{AGENT_EVENT_CHANNEL}',+ json_build_object('agent_id', NEW.agent_id, 'seq', NEW.seq)::text+ );+ RETURN NULL;+END;+$$ LANGUAGE plpgsql+"""++CREATE_AGENT_EVENT_NOTIFY_TRIGGER = f"""+CREATE TRIGGER {AGENT_EVENT_NOTIFY_TRIGGER_NAME}+ AFTER INSERT ON agent_events+ FOR EACH ROW EXECUTE FUNCTION {AGENT_EVENT_NOTIFY_FUNCTION_NAME}()+"""++DROP_AGENT_EVENT_NOTIFY_TRIGGER = (+ f"DROP TRIGGER IF EXISTS {AGENT_EVENT_NOTIFY_TRIGGER_NAME} ON agent_events"+)+DROP_AGENT_EVENT_NOTIFY_FUNCTION = (+ f"DROP FUNCTION IF EXISTS {AGENT_EVENT_NOTIFY_FUNCTION_NAME}()"+)diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.pyindex 55cb3121a..f83e7fba3 100644--- a/core/switch_core/db/models.py+++ b/core/switch_core/db/models.py@@ -27,6 +27,11 @@ from sqlalchemy import (from sqlalchemy.dialects.postgresql import JSONBfrom sqlalchemy.orm import Mapped, declared_attr, mapped_column+from switch_core.db.agent_event_notify_ddl import (+ CREATE_AGENT_EVENT_NOTIFY_FUNCTION,+ CREATE_AGENT_EVENT_NOTIFY_TRIGGER,+ DROP_AGENT_EVENT_NOTIFY_TRIGGER,+)from switch_core.db.base import Basefrom switch_core.db.encrypted_json import EncryptedJSONBfrom switch_core.db.notify_ddl import (@@ -44,8 +49,22 @@ from switch_core.db.session_activity_notify_ddl import (from switch_core.db.tenant_lookup import attach_tenant_lookupsfrom switch_core.tenant_context import current_tenant_id+#: The highest boot number `agent_event_boot` hands out. An agent's own event+#: numbers start at the boot number shifted left 32 bits, so they stay below+#: `(AGENT_EVENT_BOOT_MAX + 1) << 32`, the first ticket id (`TICKET_FLOOR`).+AGENT_EVENT_BOOT_MAX = 2097150++#: The first id of `agent_position_tickets`. Every own event number is below it+#: (see `AGENT_EVENT_BOOT_MAX`), and every ticket id from here to+#: `TICKET_CEILING` is an integer a JavaScript client holds exactly.+TICKET_FLOOR = (AGENT_EVENT_BOOT_MAX + 1) << 32+TICKET_CEILING = 2**53 - 1+agent_event_boot_sequence = Sequence(- "agent_event_boot", metadata=Base.metadata, maxvalue=2097150, cycle=False+ "agent_event_boot",+ metadata=Base.metadata,+ maxvalue=AGENT_EVENT_BOOT_MAX,+ cycle=False,)@@ -2336,6 +2355,269 @@ class DeliveryCursor(TenantScoped, Base):)+class AgentEventRow(TenantScoped, Base):+ """One of an agent's own events: an event meant for that agent, not one it+ sent.++ The agent's consumer (`AgentConsumer`) writes a row when a room row it is+ handed turns out to be for the agent: a message addressed to it, a join it+ is set to listen for, a task event it is part of, or a command sent to it.+ Whether a row is for the agent depends on the room's state at the moment+ it is delivered, so the consumer records the decision here instead of+ leaving it to be worked out again at read time. The rest of a room's+ conversation is not copied here; a reader that wants it reads `messages`.++ `seq` numbers the own events of one agent. The numbers are contiguous+ and never reused (`AgentEventHead` hands them out). `payload` is the event+ exactly as it is sent to the agent. `notifiable` is false only for+ commands, and a connection that asked for addressed events only reads the+ rows where it is true.++ `room_seq` is the `messages.seq` of the room row the event came from. When+ several files are posted as one message, it is the row of the last part to+ arrive. `message_key` is the attachment group id for such a message and the+ row's own event id otherwise. A reader that combines these own events with+ the room's conversation uses the pair to leave out the rows of `messages`+ it has already received from here.++ The retention loop in `main.py` deletes rows older than+ `agent_event_retention_seconds`. It never deletes from `messages`.+ """++ __tablename__ = "agent_events"+ __table_args__ = (+ Index("ix_agent_events_tenant_id", "tenant_id"),+ Index("ix_agent_events_created_at", "created_at"),+ Index(+ "ix_agent_events_agent_room_seq",+ "tenant_id",+ "agent_id",+ "room_id",+ "room_seq",+ ),+ Index("ix_agent_events_agent_message_key", "agent_id", "message_key"),+ ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name="fk_agent_events_agent",+ ondelete="CASCADE",+ ),+ )++ agent_id: Mapped[str] = mapped_column(Text, primary_key=True)+ seq: Mapped[int] = mapped_column(BigInteger, primary_key=True)+ room_id: Mapped[str] = mapped_column(Text, nullable=False)+ room_seq: Mapped[int] = mapped_column(BigInteger, nullable=False)+ message_key: Mapped[str | None] = mapped_column(Text, nullable=True)+ type: Mapped[str] = mapped_column(Text, nullable=False)+ payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False)+ notifiable: Mapped[bool] = mapped_column(Boolean, nullable=False)+ created_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), server_default=func.now(), nullable=False+ )+++class AgentEventHead(TenantScoped, Base):+ """The first and the latest `agent_events.seq` given out for one agent.++ `EventBuffer.enqueue` takes the next number from `last_seq` here rather+ than from the highest row in `agent_events`, because the retention loop+ deletes old rows. If the newest rows were deleted and their numbers handed+ out again, a client that had already read up to one of those numbers+ would treat the new event carrying it as one it had seen, and never+ receive it.++ `first_seq` is the number of the agent's first event. It is derived from+ the boot number (`agent_event_boot`, shifted left 32 bits) of the process+ that first read the agent's head or wrote its first event, whichever came+ first, which puts it above every number an earlier server process could+ have given a client. A client resuming from such a number is therefore+ below everything stored here and is told it has a gap. The row is written+ on that first read so that every process numbers the agent alike: before+ it exists, processes of different boots would each answer from their own+ boot number.+ """++ __tablename__ = "agent_event_heads"+ __table_args__ = (+ Index("ix_agent_event_heads_tenant_id", "tenant_id"),+ ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name="fk_agent_event_heads_agent",+ ondelete="CASCADE",+ ),+ )++ agent_id: Mapped[str] = mapped_column(Text, primary_key=True)+ first_seq: Mapped[int] = mapped_column(BigInteger, nullable=False)+ last_seq: Mapped[int] = mapped_column(BigInteger, nullable=False)+++class AgentEventDrop(TenantScoped, Base):+ """The newest `agent_events.seq` that retention deleted, per agent and room.++ `EventBuffer.expire` writes `dropped_through` when it deletes an agent's+ rows. A client that resumes from a number below it has missed events in+ that room. The stream then opens with a gap that names the room, instead+ of carrying on as if nothing were missing.+ """++ __tablename__ = "agent_event_drops"+ __table_args__ = (+ Index("ix_agent_event_drops_tenant_id", "tenant_id"),+ ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name="fk_agent_event_drops_agent",+ ondelete="CASCADE",+ ),+ )++ agent_id: Mapped[str] = mapped_column(Text, primary_key=True)+ room_id: Mapped[str] = mapped_column(Text, primary_key=True)+ dropped_through: Mapped[int] = mapped_column(BigInteger, nullable=False)+++class AgentRoomRead(TenantScoped, Base):+ """The baseline for an agent's unread count in one room, and who owns it.++ `caught_up_seq` is the `messages.seq` the agent had read through the last+ time it caught up on the room with `read_context`. The unaddressed+ messages after it are the `missed_count` the agent is shown.++ `occupant_id` is whoever is in the room for this agent now: a session id+ when `occupant_is_session` is true, a connection id otherwise. Only a+ catch-up by that occupant moves `caught_up_seq`, so a session that has+ left the room cannot clear the count of the one that replaced it.++ The row lives in Postgres so the count survives a restart and every+ server process reports the same number.+ """++ __tablename__ = "agent_room_reads"+ __table_args__ = (+ Index("ix_agent_room_reads_tenant_id", "tenant_id"),+ ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name="fk_agent_room_reads_agent",+ ondelete="CASCADE",+ ),+ ForeignKeyConstraint(+ ["tenant_id", "room_id"],+ ["rooms.tenant_id", "rooms.id"],+ name="fk_agent_room_reads_room",+ ondelete="CASCADE",+ ),+ )++ agent_id: Mapped[str] = mapped_column(Text, primary_key=True)+ room_id: Mapped[str] = mapped_column(Text, primary_key=True)+ caught_up_seq: Mapped[int] = mapped_column(BigInteger, nullable=False)+ occupant_id: Mapped[str] = mapped_column(Text, nullable=False)+ occupant_is_session: Mapped[bool] = mapped_column(Boolean, nullable=False)+ updated_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True),+ server_default=func.now(),+ onupdate=func.now(),+ nullable=False,+ )+++class AgentPollPosition(TenantScoped, Base):+ """How far a long-polling client has read, stored on its behalf.++ The long-poll endpoints take no position from the client, so the server+ remembers one for each kind of poll. `reader_id` names the poll:+ `legacy:all` for the agent-wide poll, `legacy:notifications` for the+ notifications poll, and `legacy:room:<room_id>` for a single room's poll.+ `position` is the state vector the next poll resumes from: `s` for the+ agent's own events and `r:<room_id>` for each room's conversation.+ """++ __tablename__ = "agent_poll_positions"+ __table_args__ = (+ Index("ix_agent_poll_positions_tenant_id", "tenant_id"),+ ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name="fk_agent_poll_positions_agent",+ ondelete="CASCADE",+ ),+ )++ agent_id: Mapped[str] = mapped_column(Text, primary_key=True)+ reader_id: Mapped[str] = mapped_column(Text, primary_key=True)+ position: Mapped[dict[str, int]] = mapped_column(JSONB, nullable=False)+ updated_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True),+ server_default=func.now(),+ onupdate=func.now(),+ nullable=False,+ )+++agent_position_ticket_sequence = Sequence(+ "agent_position_ticket",+ metadata=Base.metadata,+ # Ticket ids run from `TICKET_FLOOR` to `TICKET_CEILING`, above every own+ # event number (`agent_events.seq`) a client may also hold. The server+ # tells a ticket id from an own event number by size alone, and a client+ # that keeps the highest number it has seen never discards a ticket as+ # older. The range holds about four billion ids. The sequence starts again+ # at the floor when it runs out, which reuses only ids whose tickets the+ # retention loop deleted long before, since tickets last a day.+ start=TICKET_FLOOR,+ minvalue=TICKET_FLOOR,+ maxvalue=TICKET_CEILING,+ cycle=True,+)+++class AgentPositionTicket(TenantScoped, Base):+ """A stored position, identified by a single number, for older clients.++ A reader's position is a state vector: `s` for how far it has read the+ agent's own events (`agent_events`) and `r:<room_id>` for how far it has+ read each room's conversation (`messages`). Clients on agent-protocol+ revision 8 or older can hold only one integer. When such a client reads the+ whole conversation, the server stores the position after each event it+ sends as a row here and sends the row's `id` as the event id. When the+ client resumes or beats with that id, the server looks the position up+ here.++ Clients on revision 9 send the position itself and never cause a row to+ be written. The retention loop deletes tickets older than+ `agent_event_retention_seconds`, the same window as the events they+ point into.+ """++ __tablename__ = "agent_position_tickets"+ __table_args__ = (+ Index("ix_agent_position_tickets_tenant_id", "tenant_id"),+ Index("ix_agent_position_tickets_created_at", "created_at"),+ ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name="fk_agent_position_tickets_agent",+ ondelete="CASCADE",+ ),+ )++ id: Mapped[int] = mapped_column(+ BigInteger,+ agent_position_ticket_sequence,+ primary_key=True,+ server_default=agent_position_ticket_sequence.next_value(),+ )+ agent_id: Mapped[str] = mapped_column(Text, nullable=False)+ position: Mapped[dict[str, int]] = mapped_column(JSONB, nullable=False)+ created_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), server_default=func.now(), nullable=False+ )++class MediaBlob(TenantScoped, Base):"""The bytes behind an attachment.@@ -2398,6 +2680,27 @@ event.listen(DDL(DROP_NOTIFY_TRIGGER).execute_if(dialect="postgresql"),)+# These attach the trigger that sends a Postgres `NOTIFY` on channel+# `switch_agent_event` for every new `agent_events` row, so the server process+# waiting to deliver that agent's events wakes up. They run only when+# `metadata.create_all` builds the schema, which the tests do. Real databases+# get the same trigger from migration a7e3c1d9f204. The SQL lives in+# `db/agent_event_notify_ddl.py`.+event.listen(+ AgentEventRow.__table__,+ "after_create",+ DDL(CREATE_AGENT_EVENT_NOTIFY_FUNCTION).execute_if(dialect="postgresql"),+)+event.listen(+ AgentEventRow.__table__,+ "after_create",+ DDL(CREATE_AGENT_EVENT_NOTIFY_TRIGGER).execute_if(dialect="postgresql"),+)+event.listen(+ AgentEventRow.__table__,+ "before_drop",+ DDL(DROP_AGENT_EVENT_NOTIFY_TRIGGER).execute_if(dialect="postgresql"),+)# ── Session activity ──────────────────────────────────────────────────────────#diff --git a/core/switch_core/events.py b/core/switch_core/events.pyindex 291446caa..fc652c7e8 100644--- a/core/switch_core/events.py+++ b/core/switch_core/events.py@@ -6,6 +6,15 @@ from pydantic import BaseModel, ConfigDictclass SwitchEvent(BaseModel):model_config = ConfigDict(extra="allow")+ # The `messages` row this event was parsed from: its `seq` in the room and+ # its event id. `Consumer` fills both when it dispatches the event, and+ # `AgentConsumer` stores them on the row in the agent's own events so a+ # reader can match that row to the room row. They are not part of the+ # event's content, and stay 0 and None for an event that did not come from+ # a `messages` row.+ room_seq: int = 0+ source_event_id: str | None = None+# ── Command ───────────────────────────────────────────────────────────────────diff --git a/core/switch_core/main.py b/core/switch_core/main.pyindex 934afc605..34ce0b4cf 100644--- a/core/switch_core/main.py+++ b/core/switch_core/main.py@@ -32,6 +32,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,)from switch_core.bridges.agent.protocol.agent_core import AgentCore+from switch_core.bridges.agent.protocol.agent_event_listener import AgentEventListenerfrom switch_core.bridges.agent.protocol.controller_presence import ControllerPresencefrom switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.registration_bootstrap import (@@ -199,6 +200,9 @@ logger = logging.getLogger(__name__)# seconds keeps a stuck "working"/"awaiting-input" surface from lingering long# after a session crashes, while staying well above the per-pass DB cost._RUNTIME_STATE_SWEEP_INTERVAL = 5.0+# How often the retention loop deletes expired agent events. The retention+# window is measured in hours, so running once a minute is precise enough.+_AGENT_EVENT_RETENTION_INTERVAL = 60.0# How often to close connections whose heartbeat has lapsed. Kept well under# the heartbeat TTL so a dead connection's room slot and role lease are freed@@ -211,6 +215,21 @@ _CONNECTION_SWEEP_INTERVAL = 2.0_FORCED_EXIT_GRACE_SECONDS = 3.0+async def _agent_event_retention_loop(+ session_factory: async_sessionmaker[AsyncSession], buffer: EventBuffer+) -> None:+ """Once a minute, delete agent events and position tickets older than the+ retention window, one tenant at a time."""+ with no_tenant():+ while True:+ await asyncio.sleep(_AGENT_EVENT_RETENTION_INTERVAL)+ try:+ for tenant_id in await all_tenant_ids(session_factory):+ await buffer.expire(tenant_id)+ except Exception:+ logger.exception("Agent event retention pass failed")++async def _runtime_state_sweep_loop(protocol: AgentCore) -> None:# `no_tenant` for the reason every other long-lived task does it: a task# keeps the context of whoever created it, and nothing in here may depend@@ -541,7 +560,16 @@ async def run(config: SwitchConfig) -> None:)# ── Event queue + request trackers ───────────────────────────────────────- event_buffer = EventBuffer(sequence_base=event_boot << 32)+ event_buffer = EventBuffer(+ session_factory,+ sequence_base=event_boot << 32,+ retention_seconds=config.agent_event_retention_seconds,+ )+ # Listens for the `NOTIFY` that each insert into `agent_events` sends, and+ # wakes this process's streams for that agent, whichever process wrote it.+ agent_event_listener = AgentEventListener(+ lambda: create_unpooled_engine(config), event_buffer+ )connector_store = ServerConnectorStore()# ── Product telemetry ────────────────────────────────────────────────────@@ -1009,6 +1037,9 @@ async def run(config: SwitchConfig) -> None:)asyncio.create_task(connector_lifecycle.start_all())sweep_task = asyncio.create_task(_runtime_state_sweep_loop(protocol))+ retention_task = asyncio.create_task(+ _agent_event_retention_loop(session_factory, event_buffer)+ )session_activity_task = asyncio.create_task(session_activity_maintenance_loop(session_factory))@@ -1032,10 +1063,12 @@ async def run(config: SwitchConfig) -> None:)await message_listener.start()await session_activity_listener.start()+ await agent_event_listener.start()try:yieldfinally:sweep_task.cancel()+ retention_task.cancel()session_activity_task.cancel()connection_sweep_task.cancel()service_token_task.cancel()@@ -1047,6 +1080,7 @@ async def run(config: SwitchConfig) -> None:await _stop_management(management)await message_listener.stop()await session_activity_listener.stop()+ await agent_event_listener.stop()# Before the operational flush, and bounded: the whole# teardown runs inside `_FORCED_EXIT_GRACE_SECONDS` and a# product event is the least valuable thing in it.diff --git a/core/switch_core/management/controller_routes.py b/core/switch_core/management/controller_routes.pyindex c8e7987cb..e0689c2ff 100644--- a/core/switch_core/management/controller_routes.py+++ b/core/switch_core/management/controller_routes.py@@ -430,7 +430,7 @@ async def attach_stream()-def record_beat(+async def record_beat(*,principal: ControllerPrincipal,protocol: AgentCore,@@ -454,11 +454,16 @@ def record_beat(binding = presence.binding(agent_id)if agent_id not in agents or binding is None:continue- # Clamped to the head, as an agent's own beat is: a higher number- # belongs to a previous life of this process.- confirmed = min(cursor, protocol.event_buffer.head(agent_id))- protocol.event_buffer.confirm(agent_id, presence.holder_id(binding), confirmed)- presence.resume_from(conn, agent_id, confirmed)+ sent = conn.sent_cursors.get(agent_id)+ if sent is None:+ continue+ # The controller reports how far it has read each agent's own events.+ # It cannot have read further than this connection has sent it. A+ # larger number comes from another history, a database restored from a+ # backup or another server, and keeping it would make the next stream+ # on this connection resume past events the agent never received. The+ # bound is kept in memory, so a beat costs no database query.+ presence.resume_from(conn, agent_id, min(cursor, sent))return sorted(agents)@@ -627,7 +632,7 @@ async def _receive_pongs(if not isinstance(message, dict) or message.get("type") != "pong":continuetry:- record_beat(+ await record_beat(principal=principal,protocol=protocol,connection_id=connection_id,diff --git a/core/switch_core/migrations/versions/a7e3c1d9f204_agent_events_outbox.py b/core/switch_core/migrations/versions/a7e3c1d9f204_agent_events_outbox.pynew file mode 100644index 000000000..20d609b84--- /dev/null+++ b/core/switch_core/migrations/versions/a7e3c1d9f204_agent_events_outbox.py@@ -0,0 +1,237 @@+"""Agent events in Postgres: each agent's own events and each reader's position++Revision ID: a7e3c1d9f204+Revises: 7c3e91a4d5b2+Create Date: 2026-10-12++Creates the tables that hold each agent's queued events and each reader's+place in them, so they survive a restart and every server process sees the+same data:++- `agent_events`: each agent's own events. A row is an event meant for the+ agent, not one it sent (an addressed message, a join it listens for, a task+ event, a command), numbered per agent in `seq`, with `room_seq` and+ `message_key` naming the room row it came from. The rest of a room's conversation stays in+ `messages` and is not copied.+- `agent_event_heads`: the first and latest `seq` given out per agent, so a+ number is never given out twice after old rows are deleted.+- `agent_event_drops`: per agent and room, the newest `seq` that retention+ deleted, so a client resuming from below it is told it has a gap.+- `agent_room_reads`: per agent and room, the `messages.seq` the agent last+ caught up through and who is in the room, the baseline for the unread+ count.+- `agent_poll_positions`: the position the server keeps for each long-poll+ endpoint, since long-polling clients send none.+- `agent_position_tickets`: positions stored under a single number for+ clients that can hold only one integer.++It also creates a trigger that sends a `NOTIFY` on `switch_agent_event` for+each insert into `agent_events`, which wakes the process holding the agent's+connection so it reads the new rows.+"""++import sqlalchemy as sa+from alembic import op+from sqlalchemy.dialects import postgresql++revision = "a7e3c1d9f204"+down_revision = "7c3e91a4d5b2"+branch_labels = None+depends_on = None++# Copies of the DDL in `db/agent_event_notify_ddl.py`, written out here so+# this migration keeps creating the same objects if that module changes.+CREATE_NOTIFY_FUNCTION = """+CREATE OR REPLACE FUNCTION switch_notify_agent_event() RETURNS trigger AS $$+BEGIN+ PERFORM pg_notify(+ 'switch_agent_event',+ json_build_object('agent_id', NEW.agent_id, 'seq', NEW.seq)::text+ );+ RETURN NULL;+END;+$$ LANGUAGE plpgsql+"""++CREATE_NOTIFY_TRIGGER = """+CREATE TRIGGER agent_events_notify+ AFTER INSERT ON agent_events+ FOR EACH ROW EXECUTE FUNCTION switch_notify_agent_event()+"""++_POLICY = (+ "CREATE POLICY tenant_isolation ON {table} FOR ALL "+ "USING (tenant_id = (SELECT require_tenant_id())) "+ "WITH CHECK (tenant_id = (SELECT require_tenant_id()))"+)+++def _tenant(table: str) -> sa.Column: # type: ignore[type-arg]+ return sa.Column(+ "tenant_id",+ sa.Text(),+ sa.ForeignKey("tenants.id", name=f"fk_{table}_tenant"),+ nullable=False,+ )+++def _agent_fk(table: str) -> sa.ForeignKeyConstraint:+ return sa.ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name=f"fk_{table}_agent",+ ondelete="CASCADE",+ )+++def upgrade() -> None:+ op.create_table(+ "agent_events",+ _tenant("agent_events"),+ sa.Column("agent_id", sa.Text(), nullable=False),+ sa.Column("seq", sa.BigInteger(), nullable=False),+ sa.Column("room_id", sa.Text(), nullable=False),+ sa.Column("room_seq", sa.BigInteger(), nullable=False),+ sa.Column("message_key", sa.Text(), nullable=True),+ sa.Column("type", sa.Text(), nullable=False),+ sa.Column("payload", postgresql.JSONB(), nullable=False),+ sa.Column("notifiable", sa.Boolean(), nullable=False),+ sa.Column(+ "created_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ sa.PrimaryKeyConstraint("agent_id", "seq"),+ _agent_fk("agent_events"),+ )+ op.create_index("ix_agent_events_created_at", "agent_events", ["created_at"])+ op.create_index(+ "ix_agent_events_agent_room_seq",+ "agent_events",+ ["tenant_id", "agent_id", "room_id", "room_seq"],+ )+ op.create_index(+ "ix_agent_events_agent_message_key",+ "agent_events",+ ["agent_id", "message_key"],+ )+ op.create_table(+ "agent_event_heads",+ _tenant("agent_event_heads"),+ sa.Column("agent_id", sa.Text(), nullable=False),+ sa.Column("first_seq", sa.BigInteger(), nullable=False),+ sa.Column("last_seq", sa.BigInteger(), nullable=False),+ sa.PrimaryKeyConstraint("agent_id"),+ _agent_fk("agent_event_heads"),+ )+ op.create_table(+ "agent_event_drops",+ _tenant("agent_event_drops"),+ sa.Column("agent_id", sa.Text(), nullable=False),+ sa.Column("room_id", sa.Text(), nullable=False),+ sa.Column("dropped_through", sa.BigInteger(), nullable=False),+ sa.PrimaryKeyConstraint("agent_id", "room_id"),+ _agent_fk("agent_event_drops"),+ )+ op.create_table(+ "agent_room_reads",+ _tenant("agent_room_reads"),+ sa.Column("agent_id", sa.Text(), nullable=False),+ sa.Column("room_id", sa.Text(), nullable=False),+ sa.Column("caught_up_seq", sa.BigInteger(), nullable=False),+ sa.Column("occupant_id", sa.Text(), nullable=False),+ sa.Column("occupant_is_session", sa.Boolean(), nullable=False),+ sa.Column(+ "updated_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ sa.PrimaryKeyConstraint("agent_id", "room_id"),+ _agent_fk("agent_room_reads"),+ sa.ForeignKeyConstraint(+ ["tenant_id", "room_id"],+ ["rooms.tenant_id", "rooms.id"],+ name="fk_agent_room_reads_room",+ ondelete="CASCADE",+ ),+ )+ op.create_table(+ "agent_poll_positions",+ _tenant("agent_poll_positions"),+ sa.Column("agent_id", sa.Text(), nullable=False),+ sa.Column("reader_id", sa.Text(), nullable=False),+ sa.Column("position", postgresql.JSONB(), nullable=False),+ sa.Column(+ "updated_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ sa.PrimaryKeyConstraint("agent_id", "reader_id"),+ _agent_fk("agent_poll_positions"),+ )+ # Ticket ids run from (2097150 + 1) << 32, above every agent event number+ # (an agent's numbers start at its boot number, at most 2097150 by the+ # `agent_event_boot` sequence, shifted left 32 bits), to 2**53 - 1, the+ # largest integer a JavaScript client holds exactly. The server tells a+ # ticket id from an event number by size. Values are written out because a+ # migration must not change when the code's constants do.+ op.execute(+ "CREATE SEQUENCE agent_position_ticket"+ " START WITH 9007194959773696"+ " MINVALUE 9007194959773696"+ " MAXVALUE 9007199254740991"+ " CYCLE"+ )+ op.create_table(+ "agent_position_tickets",+ _tenant("agent_position_tickets"),+ sa.Column(+ "id",+ sa.BigInteger(),+ server_default=sa.text("nextval('agent_position_ticket')"),+ nullable=False,+ ),+ sa.Column("agent_id", sa.Text(), nullable=False),+ sa.Column("position", postgresql.JSONB(), nullable=False),+ sa.Column(+ "created_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ sa.PrimaryKeyConstraint("id"),+ _agent_fk("agent_position_tickets"),+ )+ op.create_index(+ "ix_agent_position_tickets_created_at",+ "agent_position_tickets",+ ["created_at"],+ )+ for table in (+ "agent_events",+ "agent_event_heads",+ "agent_event_drops",+ "agent_room_reads",+ "agent_poll_positions",+ "agent_position_tickets",+ ):+ op.create_index(f"ix_{table}_tenant_id", table, ["tenant_id"])+ op.execute(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY")+ op.execute(_POLICY.format(table=table))+ op.execute(CREATE_NOTIFY_FUNCTION)+ op.execute(CREATE_NOTIFY_TRIGGER)+++def downgrade() -> None:+ op.execute("DROP TRIGGER IF EXISTS agent_events_notify ON agent_events")+ op.execute("DROP FUNCTION IF EXISTS switch_notify_agent_event()")+ op.drop_table("agent_position_tickets")+ op.execute("DROP SEQUENCE IF EXISTS agent_position_ticket")+ op.drop_table("agent_poll_positions")+ op.drop_table("agent_room_reads")+ op.drop_table("agent_event_drops")+ op.drop_table("agent_event_heads")+ op.drop_table("agent_events")diff --git a/core/switch_core/observability/catalogue.py b/core/switch_core/observability/catalogue.pyindex 08aa3f2ed..1930e03aa 100644--- a/core/switch_core/observability/catalogue.py+++ b/core/switch_core/observability/catalogue.py@@ -410,20 +410,20 @@ AGENT_EVENTS_DROPPED = _spec("switch.agent.events_dropped","sum","{event}",- "Buffered events discarded before an agent read them. `reason` separates "- "an agent that cannot keep up (overflow) from one away too long "- "(retention).",+ "Agents' own events (`agent_events` rows) deleted once older than the "+ 'retention window. `reason` is always "retention". A client that resumes '+ "from before a deleted event is told it missed events in that room.","reason",)-# The buffer answers a read and an unread count by walking the agent's retained-# events from the oldest. These say what that walk costs, so whether to index-# the buffer is decided from data. `operation` is "read" or "unread".+# This histogram records how many events one read of an agent's events+# returned, or how many unaddressed messages one unread count found.+# `operation` is "read" or "unread".AGENT_BUFFER_SCANNED = _spec("switch.agent.buffer.scanned","histogram","{event}",- "Retained events walked to answer one buffer read or unread count. Bounded "- "by the per-agent cap, so a p95 near it means every read walks a full buffer.",+ "Events one read of an agent's events returned, or unaddressed messages one "+ "unread count found. A read never returns more than its limit.","operation",bounds=(0.0, 10.0, 50.0, 100.0, 250.0, 500.0, 1000.0, 1500.0, 2000.0),)diff --git a/core/switch_core/transport/stored.py b/core/switch_core/transport/stored.pyindex 6c9aaf528..cb231001c 100644--- a/core/switch_core/transport/stored.py+++ b/core/switch_core/transport/stored.py@@ -55,6 +55,7 @@ def to_inbound(sender=sender,timestamp=timestamp,content=content,+ seq=row.seq,state_key=row.sender_id,membership=text_field(content.get("membership")) or "join",# Only an arrival is ever written, so there is no previous state@@ -71,6 +72,7 @@ def to_inbound(sender=sender,timestamp=timestamp,content=content,+ seq=row.seq,event_type=row.event_type,thread_root_id=row.thread_root_event_id,)@@ -82,6 +84,7 @@ def to_inbound(sender=sender,timestamp=timestamp,content=content,+ seq=row.seq,body=row.body or "",sender_name=row.sender_name,formatted_body=row.formatted_body,@@ -97,6 +100,7 @@ def to_inbound(sender=sender,timestamp=timestamp,content=content,+ seq=row.seq,body=row.body or "",sender_name=row.sender_name,formatted_body=row.formatted_body,diff --git a/core/switch_core/transport/types.py b/core/switch_core/transport/types.pyindex 1e934f332..6d46d8d9e 100644--- a/core/switch_core/transport/types.py+++ b/core/switch_core/transport/types.py@@ -83,6 +83,10 @@ class InboundEvent:sender: strtimestamp: intcontent: dict[str, object] = field(default_factory=dict)+ #: The `messages.seq` of the row this event was read from, so an agent+ #: event built from it can record which room row it came from. It is 0+ #: when the event did not come from a `messages` row.+ seq: int = 0@dataclass(frozen=True)diff --git a/core/tests/benchmarks/server.py b/core/tests/benchmarks/server.pyindex 085e84caf..74caf5276 100644--- a/core/tests/benchmarks/server.py+++ b/core/tests/benchmarks/server.py@@ -35,6 +35,7 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.app import create_agent_bridge_appfrom switch_core.bridges.agent.protocol.agent_connections import AgentConnectionRegistryfrom switch_core.bridges.agent.protocol.agent_core import AgentCore+from switch_core.bridges.agent.protocol.agent_event_listener import AgentEventListenerfrom switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.protocol.types import (IntegrationProfile,@@ -52,10 +53,13 @@ from switch_core.db.models import (ApprovalRequest,Message,User,+ agent_event_boot_sequence,)from switch_core.db.session_scope import tenant_sessionfrom switch_core.db.stores.tenant_store import TenantStore+from switch_core.db.stores.usage_store import UsageStorefrom switch_core.main import (+ _agent_event_retention_loop,_connection_sweep_loop,_runtime_state_sweep_loop,_seed_agent_registration_bootstrap_key,@@ -447,12 +451,26 @@ async def _serve(# and left from different asyncio contexts, where resetting the token# raises instead of unbinding.bind_tenant_id(TENANT_ZERO_ID)- event_buffer = EventBuffer(sequence_base=0)+ # Numbered from this boot's base as `main` numbers it, so a Core that+ # replaces another starts above every number the last one handed out and+ # a host's cursor from before the restart reads as older, as it would in+ # production. The events themselves are rows and outlive the restart.+ async with session_env.engine.begin() as connection:+ event_boot = await connection.scalar(agent_event_boot_sequence.next_value())+ event_buffer = EventBuffer(+ session_factory,+ sequence_base=event_boot << 32,+ retention_seconds=config.agent_event_retention_seconds,+ )+ agent_event_listener = AgentEventListener(+ lambda: create_unpooled_engine(config), event_buffer+ )connections = AgentConnectionRegistry()collab_lifecycle = _NoBridges()message_listener = MessageListener(lambda: create_unpooled_engine(config))await message_listener.start()+ await agent_event_listener.start()activity_listener = AgentSessionActivityListener(lambda: create_unpooled_engine(config))@@ -509,6 +527,7 @@ async def _serve(config=config,room_store=session_env.room_store,message_store=session_env.message_store,+ usage_store=UsageStore(),media_store=session_env.media_store,listener=message_listener,invites=invites,@@ -618,6 +637,7 @@ async def _serve(sweeps = [asyncio.create_task(_connection_sweep_loop(protocol, EventLoopLag())),asyncio.create_task(_runtime_state_sweep_loop(protocol)),+ asyncio.create_task(_agent_event_retention_loop(session_factory, event_buffer)),]bench = BenchServer(@@ -648,6 +668,7 @@ async def _serve(detach_statements()await client_lifecycle.stop_all()await activity_listener.stop()+ await agent_event_listener.stop()await message_listener.stop()await provisioning.close()diff --git a/core/tests/conftest.py b/core/tests/conftest.pyindex 98d59b900..052c4c9d9 100644--- a/core/tests/conftest.py+++ b/core/tests/conftest.py@@ -23,6 +23,7 @@ from testcontainers.postgres import PostgresContainer# create_all provisions the full schema (rooms, room_groups, FKs, …).import switch_core.db.models # noqa: F401from switch_core import messaging_platforms+from switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.collaboration.platforms import PLATFORMSfrom switch_core.db import encrypted_jsonfrom switch_core.db.base import Base@@ -31,6 +32,7 @@ from switch_core.db.models import TENANT_ZERO_ID, Tenantfrom switch_core.db.runtime_role import grant_runtime_rolefrom switch_core.keys import Keyringfrom switch_core.tenant_context import tenant_scope+from tests.db_buffer import db_buffer_onfrom tests.switch_core.pool_checkouts import PoolCheckoutsfrom tests.switch_core.statement_counts import StatementCounts@@ -372,3 +374,10 @@ async def rls_harness(postgres_schema: str) -> AsyncIterator[RLSHarness]:text("GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO PUBLIC"))await owner_engine.dispose()+++def db_buffer(session_factory: async_sessionmaker[AsyncSession]) -> EventBuffer:+ """The db-buffer on this test's database. Seed the agents it queues for+ with `tests.db_buffer.seed_agent`."""+ return db_buffer_on(session_factory)diff --git a/core/tests/db_buffer.py b/core/tests/db_buffer.pynew file mode 100644index 000000000..d016f3923--- /dev/null+++ b/core/tests/db_buffer.py@@ -0,0 +1,232 @@+"""The db-buffer on the test database, and the agent rows its events point at.++Agent events are rows in Postgres now, so a test of anything that queues or+reads them runs against the real tables: offsets, tenant isolation, cascades+and retention are SQL, and a stand-in would test the stand-in.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime, timedelta+from typing import TYPE_CHECKING, Any++from sqlalchemy import func, select, update++from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.db.models import (+ TENANT_ZERO_ID,+ Agent,+ AgentEventRow,+ ApiKey,+ Client,+ ClientRoom,+ Message,+ Room,+ User,+)+from switch_core.db.session_scope import tenant_session+from switch_core.db.stores.message_store import MessageStore++if TYPE_CHECKING:+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+++def db_buffer_on(+ session_factory: async_sessionmaker[AsyncSession],+ *,+ sequence_base: int = 0,+ retention_seconds: float = 3600,+ settle_seconds: float = 0.2,+) -> EventBuffer:+ """The db-buffer, settling conversation for a fraction of the real time:+ a test has no consumer to race, and `say` writes rows already settled."""+ return EventBuffer(+ session_factory,+ sequence_base=sequence_base,+ retention_seconds=retention_seconds,+ settle_seconds=settle_seconds,+ )+++async def seed_agent(+ session_factory: async_sessionmaker[AsyncSession],+ agent_id: str,+ *,+ tenant_id: str = TENANT_ZERO_ID,+) -> str:+ """An agent row with this id, and the client, key and owner it needs.++ Idempotent, so a test can name the agents it uses without tracking which+ it has made.+ """+ async with tenant_session(session_factory, tenant_id) as session:+ if await session.scalar(select(Agent.id).where(Agent.id == agent_id)):+ return agent_id+ suffix = uuid.uuid4().hex[:12]+ user = User(name=f"owner-{suffix}", email=f"{suffix}@test.local", role="user")+ session.add(user)+ await session.flush()+ api_key = ApiKey(+ user_id=user.id,+ key_hash=f"hash-{suffix}",+ encrypted_key="enc",+ label=agent_id,+ type="agent",+ )+ client = Client(+ transport_user_id=f"@{suffix}:test.local",+ display_name=agent_id,+ type="agent",+ )+ session.add_all([api_key, client])+ await session.flush()+ session.add(+ Agent(+ id=agent_id,+ name=f"{agent_id}-{suffix}",+ 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,+ )+ )+ await session.commit()+ return agent_id+++async def age_events(+ session_factory: async_sessionmaker[AsyncSession],+ agent_id: str,+ *,+ seconds: float,+ tenant_id: str = TENANT_ZERO_ID,+) -> None:+ """Make every event queued so far for `agent_id` older by `seconds`, so a+ test can put some past the retention window without waiting for it."""+ async with tenant_session(session_factory, tenant_id) as session:+ await session.execute(+ update(AgentEventRow)+ .where(AgentEventRow.agent_id == agent_id)+ .values(created_at=AgentEventRow.created_at - timedelta(seconds=seconds))+ )+ await session.commit()+++async def seed_room(+ session_factory: async_sessionmaker[AsyncSession],+ room_id: str,+ *,+ tenant_id: str = TENANT_ZERO_ID,+ bridge_id: str | None = None,+ channel_type: str | None = None,+) -> str:+ """A room row with this id. Idempotent, like `seed_agent`."""+ async with tenant_session(session_factory, tenant_id) as session:+ if await session.scalar(select(Room.id).where(Room.id == room_id)):+ return room_id+ session.add(+ Room(+ id=room_id,+ transport_room_id=f"!{room_id}-{uuid.uuid4().hex[:8]}:test",+ name=room_id,+ description="",+ bridge_id=bridge_id,+ channel_type=channel_type,+ )+ )+ await session.commit()+ return room_id+++async def seed_member(+ session_factory: async_sessionmaker[AsyncSession],+ agent_id: str,+ room_id: str,+ *,+ tenant_id: str = TENANT_ZERO_ID,+ joined_at: datetime | None = None,+) -> None:+ """The agent and the room, and the agent in the room since `joined_at`+ (an hour ago by default, before anything a test says there)."""+ await seed_agent(session_factory, agent_id, tenant_id=tenant_id)+ await seed_room(session_factory, room_id, tenant_id=tenant_id)+ async with tenant_session(session_factory, tenant_id) as session:+ client_id = await session.scalar(+ select(Agent.client_id).where(Agent.id == agent_id)+ )+ if await session.scalar(+ select(ClientRoom.room_id).where(+ ClientRoom.client_id == client_id, ClientRoom.room_id == room_id+ )+ ):+ return+ session.add(+ ClientRoom(+ client_id=client_id,+ room_id=room_id,+ joined_at=joined_at or datetime.now(UTC) - timedelta(hours=1),+ )+ )+ await session.commit()+++async def sender_of(+ session_factory: async_sessionmaker[AsyncSession],+ agent_id: str,+ *,+ tenant_id: str = TENANT_ZERO_ID,+) -> str:+ """The id an agent's own messages are sent under."""+ async with tenant_session(session_factory, tenant_id) as session:+ sender = await session.scalar(+ select(Client.transport_user_id)+ .join(Agent, Agent.client_id == Client.id)+ .where(Agent.id == agent_id)+ )+ assert sender is not None, f"no agent {agent_id}; seed it first"+ return sender+++async def say(+ session_factory: async_sessionmaker[AsyncSession],+ room_id: str,+ body: str = "hello",+ *,+ sender: str = "@alice:test",+ sender_name: str | None = "Alice",+ event_id: str | None = None,+ tenant_id: str = TENANT_ZERO_ID,+ sent_at: datetime | None = None,+ event_type: str = "m.room.message",+ content: dict[str, Any] | None = None,+) -> Message:+ """Write one row to a room's log, as the transport does, and return it+ (its `seq` is its place in the room). The room must exist.++ Stamped a second ago by the database's clock, the one conversation is+ settled by, so it reads as conversation straight away."""+ async with tenant_session(session_factory, tenant_id) as session:+ if sent_at is None:+ sent_at = await session.scalar(select(func.now() - timedelta(seconds=1)))+ message = await MessageStore().create(+ session,+ Message(+ room_id=room_id,+ transport_event_id=event_id or f"${uuid.uuid4().hex}",+ sender_id=sender,+ sender_name=sender_name,+ event_type=event_type,+ msgtype="m.text" if event_type == "m.room.message" else None,+ body=body,+ formatted_body=None,+ content=content if content is not None else {"body": body},+ sent_at=sent_at,+ ),+ [],+ )+ await session.commit()+ await session.refresh(message)+ return messagediff --git a/core/tests/integration/conftest.py b/core/tests/integration/conftest.pyindex 2f0eaf534..ec1937221 100644--- a/core/tests/integration/conftest.py+++ b/core/tests/integration/conftest.py@@ -4,7 +4,7 @@ Unlike the unit suite (which fakes the transport), these fixtures boot a realdatabase and wire up the subset of `switch_core.main:run()` the feature undertest needs, in-process. Messaging, membership and provisioning all run againstthat database, so a test drives the genuine path RoomService → provisioning →-AgentConsumer receive loop → EventBuffer.+AgentConsumer receive loop → EventBuffer (the agent_events tables).The container mirrors the `postgres` service in`deploy/local/docker-compose.yml` (see constants below — keep in sync). It gets@@ -547,9 +547,16 @@ async def harness(config,)- # Per-test in-memory wiring: a fresh EventBuffer / client registry so queued- # events and client registrations never leak across tests.- event_buffer = EventBuffer(sequence_base=0)+ # Per-test wiring: a fresh EventBuffer / client registry so the readers'+ # bookkeeping and client registrations never leak across tests. The+ # queued events themselves are rows, cleared by the truncation above.+ # No `AgentEventListener`: it wakes readers for rows another process+ # wrote, and everything here runs in this one.+ event_buffer = EventBuffer(+ session_factory, # type: ignore[arg-type]+ sequence_base=0,+ retention_seconds=config.agent_event_retention_seconds,+ )connections = AgentConnectionRegistry()collab_lifecycle: object = _NoBridges()real_bridges = (diff --git a/core/tests/integration/test_removal_stops_delivery_e2e.py b/core/tests/integration/test_removal_stops_delivery_e2e.pyindex 73287d2dc..33e9498ce 100644--- a/core/tests/integration/test_removal_stops_delivery_e2e.py+++ b/core/tests/integration/test_removal_stops_delivery_e2e.py@@ -24,6 +24,7 @@ import asyncioimport pytest+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.room_service import RoomCreateConfigfrom tests.integration.conftest import Harness@@ -51,7 +52,7 @@ async def _wait_buffered("""deadline = asyncio.get_event_loop().time() + timeoutwhile asyncio.get_event_loop().time() < deadline:- for item in harness.event_buffer.read_from(agent_id, 0):+ for item in await harness.event_buffer.read_from(TENANT_ZERO_ID, agent_id, 0):if (item.room_id == room_idand getattr(item.event.payload, "body", None) == body@@ -65,8 +66,11 @@ async def _wait_buffered(raise AssertionError(f"{body!r} never reached the buffer for room {room_id}")-def _rooms_in_buffer(harness: Harness, agent_id: str) -> set[str]:- return {item.room_id for item in harness.event_buffer.read_from(agent_id, 0)}+async def _rooms_in_buffer(harness: Harness, agent_id: str) -> set[str]:+ return {+ item.room_id+ for item in await harness.event_buffer.read_from(TENANT_ZERO_ID, agent_id, 0)+ }async def test_removal_stops_every_reader_serving_the_room(harness: Harness) -> None:@@ -100,7 +104,7 @@ async def test_removal_stops_every_reader_serving_the_room(harness: Harness) -># Both rooms are in the buffer and addressed, so every assertion after the# removal is about the removal rather than about nothing being there.- assert _rooms_in_buffer(harness, watcher.agent_id) == {+ assert await _rooms_in_buffer(harness, watcher.agent_id) == {rooms["left"].id,rooms["kept"].id,}@@ -113,10 +117,10 @@ async def test_removal_stops_every_reader_serving_the_room(harness: Harness) -># own to apply — this is the whole of its defence.deadline = asyncio.get_event_loop().time() + 15while asyncio.get_event_loop().time() < deadline:- if rooms["left"].id not in _rooms_in_buffer(harness, watcher.agent_id):+ if rooms["left"].id not in await _rooms_in_buffer(harness, watcher.agent_id):breakawait asyncio.sleep(0.25)- assert _rooms_in_buffer(harness, watcher.agent_id) == {rooms["kept"].id}, (+ assert await _rooms_in_buffer(harness, watcher.agent_id) == {rooms["kept"].id}, ("the removed room's events are still retained for the agent, so an SSE ""reader resuming from an older cursor would be handed them")diff --git a/core/tests/integration/test_room_join_e2e.py b/core/tests/integration/test_room_join_e2e.pyindex a645b85fe..226f4567a 100644--- a/core/tests/integration/test_room_join_e2e.py+++ b/core/tests/integration/test_room_join_e2e.py@@ -12,6 +12,7 @@ import asyncioimport pytest+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.room_service import RoomCreateConfigfrom tests.integration.conftest import Harness@@ -41,7 +42,7 @@ async def _drain_room_join(while asyncio.get_event_loop().time() < deadline:remaining = deadline - asyncio.get_event_loop().time()events = await harness.event_buffer.poll_room(- agent_id, room_id, timeout=min(5, max(0.1, remaining))+ TENANT_ZERO_ID, agent_id, room_id, timeout=min(5, max(0.1, remaining)))for ev in events:if ev.type == "room_join":diff --git a/core/tests/switch_core/bridges/agent/api/test_beat_carries_no_position.py b/core/tests/switch_core/bridges/agent/api/test_beat_carries_no_position.pynew file mode 100644index 000000000..694f21776--- /dev/null+++ b/core/tests/switch_core/bridges/agent/api/test_beat_carries_no_position.py@@ -0,0 +1,154 @@+"""A heartbeat says the client is still there, and nothing more.++Clients report how far they have read on every beat: a position from clients+on agent-protocol revision 9, one number from older ones, a ticket from older+ones reading the room conversation. The server does not read it. The+connection's position is moved only by the stream, as it sends, and a client+that drops resumes from the position it sends when it reopens, which is+checked against the database then.++So a beat cannot move the server past events it never sent, whatever number it+carries, and it costs no database query. Beats arrive every two seconds from+every client, and a burst of them follows any restart.+"""++from __future__ import annotations++from types import SimpleNamespace+from typing import Any++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.agent.api.handlers import connection_beat+from switch_core.bridges.agent.api.schemas import ConnectionBeatRequest+from switch_core.bridges.agent.protocol.agent_connections import (+ PROTOCOL_VERSION,+ AgentConnection,+ AgentConnectionRegistry,+ ClientDeclaration,+)+from switch_core.bridges.agent.protocol.event_buffer import TICKET_FLOOR, EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS, room_source+from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.db.models import TENANT_ZERO_ID+from tests.db_buffer import seed_agent++AGENT_ID = "agent-1"+CONN_ID = "conn-1"+ROOM_ID = "room-1"+++class _Protocol:+ def __init__(self, event_buffer: EventBuffer | None) -> None:+ self.event_buffer = event_buffer+ self.connections = AgentConnectionRegistry()+++def _connect(protocol: _Protocol) -> AgentConnection:+ conn = protocol.connections.open(+ agent_id=AGENT_ID,+ connection_id=CONN_ID,+ scope="single",+ delivery_filter="all",+ spawn_capable=False,+ position={OWN_EVENTS: 4, room_source(ROOM_ID): 7},+ declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),+ expected_generation=None,+ )+ conn.stream_attached = True+ return conn+++async def _beat(protocol: _Protocol, conn: AgentConnection, **body: Any) -> Any:+ return await connection_beat(+ AGENT_ID,+ ConnectionBeatRequest.model_validate(+ {"connection_id": CONN_ID, "generation": conn.stream_generation, **body}+ ),+ agent=SimpleNamespace(id=AGENT_ID, tenant_id=TENANT_ZERO_ID), # type: ignore[arg-type]+ protocol=protocol, # type: ignore[arg-type]+ )+++async def test_a_beat_counts_and_reads_nothing_from_the_database() -> None:+ protocol = _Protocol(event_buffer=None)+ conn = _connect(protocol)++ await _beat(protocol, conn, cursor=9)++ assert conn.beats == 1+++ "report",+ [+ {"position": {OWN_EVENTS: 500, room_source(ROOM_ID): 90}},+ {"position": {room_source("elsewhere"): 3}},+ {"position": {"not a source": 1}},+ {"cursor": 500},+ {"cursor": TICKET_FLOOR + 1},+ ],+ ids=["ahead", "another room", "not a position", "one number", "ticket"],+)+async def test_whatever_a_beat_reports_the_position_stays_where_the_stream_put_it(+ report: dict[str, Any],+) -> None:+ """Ahead of what was sent, as from another history (a database restored+ from a backup, another server); a room the connection has no place in;+ something that is not a position at all. The beat counts, and the position+ is untouched."""+ protocol = _Protocol(event_buffer=None)+ conn = _connect(protocol)++ await _beat(protocol, conn, **report)++ assert conn.beats == 1+ assert conn.position == {OWN_EVENTS: 4, room_source(ROOM_ID): 7}+++async def test_the_next_event_after_a_beat_from_another_history_is_delivered(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """The loss a beat could once cause: had the server adopted 500, the+ connection would sit past the agent's next event and skip it silently."""+ await seed_agent(session_factory, AGENT_ID)+ protocol = _Protocol(db_buffer)+ conn = protocol.connections.open(+ agent_id=AGENT_ID,+ connection_id=CONN_ID,+ scope="single",+ delivery_filter="addressed",+ spawn_capable=False,+ position={OWN_EVENTS: 0},+ declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),+ expected_generation=None,+ )+ conn.stream_attached = True+ protocol.connections.claim_room(conn, ROOM_ID, takeover=True)++ await _beat(protocol, conn, position={OWN_EVENTS: 500})+ sequence = await db_buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT_ID,+ ROOM_ID,+ AgentEvent(+ type="message",+ room_id=ROOM_ID,+ payload=MessagePayload(+ addressed=True,+ sender="@u:s",+ sender_name="u",+ message_id="$m",+ body="hi",+ timestamp=0,+ ),+ ),+ room_seq=1,+ message_key="$m",+ )++ delivered = await db_buffer.read_from(+ TENANT_ZERO_ID, AGENT_ID, conn.position[OWN_EVENTS], rooms={ROOM_ID}+ )+ assert [item.seq for item in delivered] == [sequence]diff --git a/core/tests/switch_core/bridges/agent/api/test_beat_cursor_clamp.py b/core/tests/switch_core/bridges/agent/api/test_beat_cursor_clamp.pydeleted file mode 100644index bb5194604..000000000--- a/core/tests/switch_core/bridges/agent/api/test_beat_cursor_clamp.py+++ /dev/null@@ -1,135 +0,0 @@-"""A heartbeat's cursor is clamped to the buffer head before anything adopts it.--The event buffer is in memory, so restarting switch-core resets the sequence to-zero while clients keep beating the number they had reached. Nothing downstream-can undo that: `beat()` and `confirm()` both refuse to move a cursor backwards,-and the stream's own rewind on resume is re-poisoned by the next heartbeat.--The result is silent. The connection is claimed, heartbeats succeed and posting-works, so the session looks healthy while every event up to the stale cursor is-skipped — and `confirm()` marks those events consumed on the way past.-"""--from __future__ import annotations--from typing import Any--from switch_core.bridges.agent.api.handlers import _record_beat-from switch_core.bridges.agent.protocol.agent_connections import (- PROTOCOL_VERSION,- AgentConnectionRegistry,- ClientDeclaration,-)-from switch_core.bridges.agent.protocol.event_buffer import EventBuffer-from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload--AGENT_ID = "agent-1"-CONN_ID = "conn-1"-ROOM_ID = "room-1"---class _Protocol:- def __init__(self) -> None:- self.event_buffer = EventBuffer(sequence_base=0)- self.connections = AgentConnectionRegistry()---def _message() -> AgentEvent:- return AgentEvent(- type="message",- room_id=ROOM_ID,- payload=MessagePayload(- addressed=True,- sender="@u:s",- sender_name="u",- message_id="$m",- body="hi",- timestamp=0,- ),- )---def _connect(protocol: _Protocol, cursor: int = 0) -> Any:- conn = protocol.connections.open(- agent_id=AGENT_ID,- connection_id=CONN_ID,- scope="single",- delivery_filter="all",- spawn_capable=False,- cursor=cursor,- declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),- expected_generation=None,- )- conn.stream_attached = True- return conn---def _beat(protocol: _Protocol, cursor: int) -> Any:- # Fenced with the only incarnation these tests ever open, as the socket- # does with the incarnation it opened.- current = protocol.connections.require(AGENT_ID, CONN_ID).stream_generation- return _record_beat(protocol, AGENT_ID, CONN_ID, cursor, current) # type: ignore[arg-type]---async def test_a_cursor_past_the_head_is_pulled_back_to_it() -> None:- # The restart case: the buffer is empty (head 0) and the client is still- # beating the sequence it reached before the process died.- protocol = _Protocol()- conn = _connect(protocol)-- beaten = _beat(protocol, cursor=9)-- assert protocol.event_buffer.head(AGENT_ID) == 0- assert conn.cursor == 0- assert beaten.cursor == 0---async def test_the_first_event_after_a_restart_is_still_delivered() -> None:- # The symptom the clamp exists to prevent: without it the connection sits at- # cursor 9, and sequences 1..9 — including the message that arrives next —- # are skipped with no error anywhere.- protocol = _Protocol()- conn = _connect(protocol)- protocol.connections.claim_room(conn, ROOM_ID, takeover=True)-- _beat(protocol, cursor=9)- protocol.event_buffer.enqueue(AGENT_ID, ROOM_ID, _message())-- delivered = protocol.event_buffer.read_from(AGENT_ID, conn.cursor, rooms={ROOM_ID})- assert [item.seq for item in delivered] == [1]---async def test_a_cursor_within_the_buffer_is_left_alone() -> None:- protocol = _Protocol()- conn = _connect(protocol)- for _ in range(3):- protocol.event_buffer.enqueue(AGENT_ID, ROOM_ID, _message())-- _beat(protocol, cursor=2)-- assert conn.cursor == 2---async def test_the_clamped_value_is_what_gets_confirmed() -> None:- # confirm() drives retention. Handing it the stale cursor would mark events- # consumed that were never delivered, so the clamp has to reach it too.- protocol = _Protocol()- _connect(protocol)- confirmed: list[int] = []- protocol.event_buffer.confirm = ( # type: ignore[method-assign]- lambda agent_id, connection_id, cursor: confirmed.append(cursor)- )-- _beat(protocol, cursor=9)-- assert confirmed == [0]---async def test_a_heartbeat_from_the_old_boot_cannot_undo_the_gap_position():- protocol = _Protocol()- protocol.event_buffer = EventBuffer(sequence_base=2 << 32)- sequence = protocol.event_buffer.enqueue(AGENT_ID, ROOM_ID, _message())- conn = _connect(protocol, cursor=2 << 32)- _beat(protocol, cursor=(1 << 32) + 2)- assert conn.cursor == 2 << 32- assert protocol.event_buffer.read_from(AGENT_ID, conn.cursor)[0].seq == sequencediff --git a/core/tests/switch_core/bridges/agent/api/test_beat_refusal_codes.py b/core/tests/switch_core/bridges/agent/api/test_beat_refusal_codes.pyindex ddf493796..6cd7a3155 100644--- a/core/tests/switch_core/bridges/agent/api/test_beat_refusal_codes.py+++ b/core/tests/switch_core/bridges/agent/api/test_beat_refusal_codes.py@@ -5,8 +5,8 @@ only act on the status: every refusal meant reopen. One of the three must neverbe answered that way. Being superseded means another client holds theconnection, and reopening is itself a takeover — so the client that was fencedout reopens, takes it straight back off the winner, and the pair trade it for-as long as both run. The fence stops the loser's cursor from moving the-winner's; it did not stop the loser from coming back.+as long as both run. The fence stops the loser's beats from counting for the+winner; it did not stop the loser from coming back."""from __future__ import annotations@@ -27,14 +27,15 @@ from switch_core.bridges.agent.protocol.agent_connections import (SupersededConnectionError,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSAGENT_ID = "agent-1"CONN_ID = "conn-1"class _Protocol:- def __init__(self) -> None:- self.event_buffer = EventBuffer(sequence_base=0)+ def __init__(self, event_buffer: EventBuffer) -> None:+ self.event_buffer = event_bufferself.connections = AgentConnectionRegistry()@@ -45,23 +46,25 @@ def _open(protocol: _Protocol, *, speaks: int | None = PROTOCOL_VERSION) -> Any:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=speaks),expected_generation=None,)-def _beat(protocol: _Protocol, generation: int | None) -> Any:- return _record_beat(protocol, AGENT_ID, CONN_ID, 0, generation) # type: ignore[arg-type]+async def _beat(protocol: _Protocol, generation: int | None) -> Any:+ return _record_beat(protocol, AGENT_ID, CONN_ID, generation) # type: ignore[arg-type]-def test_a_superseded_tick_is_refused_as_a_takeover() -> None:- protocol = _Protocol()+async def test_a_superseded_tick_is_refused_as_a_takeover(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)displaced = _open(protocol).stream_generation_open(protocol) # the winner attaches; the incarnation bumpswith pytest.raises(SupersededConnectionError) as caught:- _beat(protocol, displaced)+ await _beat(protocol, displaced)# The same code the displaced stream is evicted with: one ending reaching# the client by whichever door is still open to it.@@ -71,13 +74,15 @@ def test_a_superseded_tick_is_refused_as_a_takeover() -> None:assert str(displaced + 1) in str(caught.value)-def test_a_tick_with_no_stream_is_refused_as_something_to_reopen() -> None:- protocol = _Protocol()+async def test_a_tick_with_no_stream_is_refused_as_something_to_reopen(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)conn = _open(protocol)protocol.connections.detach_stream(conn, conn.stream_generation)with pytest.raises(NoStreamAttachedError) as caught:- _beat(protocol, conn.stream_generation)+ await _beat(protocol, conn.stream_generation)# Recoverable, and distinct from the takeover: this client still holds the# connection and only has to reconnect.@@ -94,14 +99,16 @@ def test_a_tick_with_no_stream_is_refused_as_something_to_reopen() -> None:async def _post_beat(protocol: _Protocol, generation: int | None) -> Any:return await connection_beat(AGENT_ID,- ConnectionBeatRequest(connection_id=CONN_ID, cursor=0, generation=generation),+ ConnectionBeatRequest(connection_id=CONN_ID, generation=generation),SimpleNamespace(id=AGENT_ID), # type: ignore[arg-type]protocol, # type: ignore[arg-type])-async def test_a_superseded_beat_is_answered_409_taken_over() -> None:- protocol = _Protocol()+async def test_a_superseded_beat_is_answered_409_taken_over(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)displaced = _open(protocol).stream_generation_open(protocol)@@ -114,8 +121,10 @@ async def test_a_superseded_beat_is_answered_409_taken_over() -> None:assert str(displaced) in message and str(displaced + 1) in message-async def test_a_beat_with_no_stream_is_answered_409_no_stream() -> None:- protocol = _Protocol()+async def test_a_beat_with_no_stream_is_answered_409_no_stream(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)conn = _open(protocol)protocol.connections.detach_stream(conn, conn.stream_generation)@@ -126,10 +135,10 @@ async def test_a_beat_with_no_stream_is_answered_409_no_stream() -> None:assert caught.value.detail["code"] == "no_stream" # type: ignore[index]-async def test_an_unfenced_beat_from_a_fenced_holder_is_refused_on_its_own_code() -> (- None-):- protocol = _Protocol()+async def test_an_unfenced_beat_from_a_fenced_holder_is_refused_on_its_own_code(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)_open(protocol)with pytest.raises(HTTPException) as caught:@@ -139,8 +148,10 @@ async def test_an_unfenced_beat_from_a_fenced_holder_is_refused_on_its_own_code(assert caught.value.detail["code"] == "unfenced" # type: ignore[index]-async def test_a_beat_for_an_unknown_connection_is_answered_404() -> None:- protocol = _Protocol()+async def test_a_beat_for_an_unknown_connection_is_answered_404(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)with pytest.raises(HTTPException) as caught:await _post_beat(protocol, None)@@ -148,8 +159,10 @@ async def test_a_beat_for_an_unknown_connection_is_answered_404() -> None:assert caught.value.status_code == 404-async def test_a_client_that_cannot_be_fenced_still_beats() -> None:- protocol = _Protocol()+async def test_a_client_that_cannot_be_fenced_still_beats(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)_open(protocol, speaks=None)assert (await _post_beat(protocol, None))["ok"] is Truediff --git a/core/tests/switch_core/bridges/agent/api/test_connection_placements.py b/core/tests/switch_core/bridges/agent/api/test_connection_placements.pyindex 246c9d8b8..c9b8943ca 100644--- a/core/tests/switch_core/bridges/agent/api/test_connection_placements.py+++ b/core/tests/switch_core/bridges/agent/api/test_connection_placements.py@@ -16,6 +16,8 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS+from switch_core.db.models import TENANT_ZERO_IDAGENT_ID = "agent-1"OTHER_AGENT_ID = "agent-2"@@ -25,9 +27,9 @@ FOREIGN_ROOM = "room-foreign"class _Protocol:- def __init__(self) -> None:+ def __init__(self, event_buffer: EventBuffer) -> None:self.connections = AgentConnectionRegistry()- self.event_buffer = EventBuffer(sequence_base=0)+ self.event_buffer = event_bufferasync def require_room_member(self, agent_id: str, room_id: str) -> None:if room_id == FOREIGN_ROOM:@@ -37,6 +39,7 @@ class _Protocol:class _Agent:def __init__(self, agent_id: str) -> None:self.id = agent_id+ self.tenant_id = TENANT_ZERO_IDself.metadata_: dict[str, str] | None = None@@ -49,7 +52,7 @@ def _open(scope="all",delivery_filter="all",spawn_capable=True,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -77,8 +80,10 @@ async def _place(@pytest.mark.asyncio-async def test_placements_replace_what_the_connection_had() -> None:- protocol = _Protocol()+async def test_placements_replace_what_the_connection_had(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)conn = _open(protocol, "watcher")await _place(protocol, conn, {"session-1": ROOM_A, "session-2": ROOM_B})@@ -94,8 +99,8 @@ async def test_placements_replace_what_the_connection_had() -> None:@pytest.mark.asyncio-async def test_an_empty_set_unplaces_every_session() -> None:- protocol = _Protocol()+async def test_an_empty_set_unplaces_every_session(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)conn = _open(protocol, "watcher")await _place(protocol, conn, {"session-1": ROOM_A})@@ -107,8 +112,10 @@ async def test_an_empty_set_unplaces_every_session() -> None:@pytest.mark.asyncio-async def test_a_room_another_connection_holds_is_taken_over() -> None:- protocol = _Protocol()+async def test_a_room_another_connection_holds_is_taken_over(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)theirs = _open(protocol, "theirs")mine = _open(protocol, "mine")await _place(protocol, theirs, {"session-t": ROOM_A})@@ -124,8 +131,10 @@ async def test_a_room_another_connection_holds_is_taken_over() -> None:@pytest.mark.asyncio-async def test_a_room_the_agent_is_not_in_refuses_the_whole_request() -> None:- protocol = _Protocol()+async def test_a_room_the_agent_is_not_in_refuses_the_whole_request(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)conn = _open(protocol, "watcher")await _place(protocol, conn, {"session-1": ROOM_A})@@ -139,8 +148,8 @@ async def test_a_room_the_agent_is_not_in_refuses_the_whole_request() -> None:@pytest.mark.asyncio-async def test_two_sessions_in_one_room_are_refused() -> None:- protocol = _Protocol()+async def test_two_sessions_in_one_room_are_refused(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)conn = _open(protocol, "watcher")with pytest.raises(HTTPException) as refused:@@ -151,8 +160,8 @@ async def test_two_sessions_in_one_room_are_refused() -> None:@pytest.mark.asyncio-async def test_another_agents_connection_is_refused() -> None:- protocol = _Protocol()+async def test_another_agents_connection_is_refused(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)foreign = _open(protocol, "foreign", agent_id=OTHER_AGENT_ID)with pytest.raises(HTTPException) as refused:@@ -164,8 +173,8 @@ async def test_another_agents_connection_is_refused() -> None:@pytest.mark.asyncio-async def test_a_path_naming_another_agent_is_refused() -> None:- protocol = _Protocol()+async def test_a_path_naming_another_agent_is_refused(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)conn = _open(protocol, "watcher")with pytest.raises(HTTPException) as refused:@@ -176,8 +185,10 @@ async def test_a_path_naming_another_agent_is_refused() -> None:@pytest.mark.asyncio-async def test_a_displaced_client_cannot_rewrite_the_holders_placements() -> None:- protocol = _Protocol()+async def test_a_displaced_client_cannot_rewrite_the_holders_placements(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)conn = _open(protocol, "watcher")stale = conn.stream_generation_open(protocol, "watcher")diff --git a/core/tests/switch_core/bridges/agent/api/test_connection_socket.py b/core/tests/switch_core/bridges/agent/api/test_connection_socket.pyindex d15ff1f09..eb54471da 100644--- a/core/tests/switch_core/bridges/agent/api/test_connection_socket.py+++ b/core/tests/switch_core/bridges/agent/api/test_connection_socket.py@@ -3,17 +3,29 @@ authenticated once, and a heartbeat the server drives.Opening, fencing and room claims are shared with the SSE stream and testedthere; these cover what is particular to the socket.++The app runs on the test client's own event loop, so its db-buffer has an+engine of its own that opens connections there, and anything a test queues+goes through the client's portal onto that loop."""from __future__ import annotationsimport asyncio+import functools+import timefrom collections.abc import AsyncGenerator, Iteratorfrom typing import Anyimport pytestfrom fastapi import FastAPIfrom fastapi.testclient import TestClient+from sqlalchemy.ext.asyncio import (+ AsyncSession,+ async_sessionmaker,+ create_async_engine,+)+from sqlalchemy.pool import NullPoolfrom starlette.types import ASGIApp, Receive, Scope, Sendfrom starlette.websockets import WebSocket, WebSocketDisconnect@@ -26,16 +38,20 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload-from switch_core.db.models import Agent+from switch_core.db.engine import create_session_factory+from switch_core.db.models import TENANT_ZERO_ID, Agent+from switch_core.tenant_context import tenant_scope+from tests.db_buffer import db_buffer_on, seed_agentAGENT_ID = "agent-1"ROOM = "room-a"class _Protocol:- def __init__(self) -> None:- self.event_buffer = EventBuffer(sequence_base=0)+ def __init__(self, event_buffer: EventBuffer) -> None:+ self.event_buffer = event_bufferself.connections = AgentConnectionRegistry()self.approval_outcomes = Noneself.sessions = SessionReporter(None)@@ -50,7 +66,8 @@ class _Protocol:class _AuthenticatedAs:- """What the bearer-auth middleware leaves in scope for a valid token."""+ """What the bearer-auth middleware leaves for a valid token: the agent in+ scope, and its tenant bound."""def __init__(self, app: ASGIApp, agent: Agent) -> None:self.app = app@@ -58,12 +75,23 @@ class _AuthenticatedAs:async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:scope["agent"] = self.agent- await self.app(scope, receive, send)+ with tenant_scope(self.agent.tenant_id):+ await self.app(scope, receive, send)+++async def _agent_row(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent the socket is for, so its events have a row to belong to."""+ await seed_agent(session_factory, AGENT_ID)@pytest.fixture-def protocol() -> _Protocol:- return _Protocol()+def protocol(postgres_schema: str, _agent_row: None) -> Iterator[_Protocol]:+ # No pool: a pooled connection belongs to the loop that opened it, and+ # this engine is used from the test client's loop, not the test's.+ engine = create_async_engine(postgres_schema, poolclass=NullPool)+ yield _Protocol(db_buffer_on(create_session_factory(engine)))+ asyncio.run(engine.dispose())@pytest.fixture@@ -77,7 +105,10 @@ def client(app.dependency_overrides[get_protocol] = lambda: protocolapp.dependency_overrides[get_config] = lambda: Noneagent = Agent(- id=AGENT_ID, name="agent", metadata_={"known_agent_type": "claude-code"}+ id=AGENT_ID,+ name="agent",+ tenant_id=TENANT_ZERO_ID,+ metadata_={"known_agent_type": "claude-code"},)with TestClient(_AuthenticatedAs(app, agent)) as client: # type: ignore[arg-type]yield client@@ -118,27 +149,36 @@ def test_events_arrive_with_their_sequence_number() -> None:with client.websocket_connect(_url(rooms=ROOM)) as ws:ws.receive_json()- seq = protocol.event_buffer.enqueue(- AGENT_ID,- ROOM,- AgentEvent(- type="message",- room_id=ROOM,- payload=MessagePayload(- addressed=True,- sender="@u:s",- sender_name="u",- message_id="$evt-1",- body="hello",- timestamp=0,+ seq = client.portal.call( # type: ignore[union-attr]+ functools.partial(+ protocol.event_buffer.enqueue,+ TENANT_ZERO_ID,+ AGENT_ID,+ ROOM,+ AgentEvent(+ type="message",+ room_id=ROOM,+ payload=MessagePayload(+ addressed=True,+ sender="@u:s",+ sender_name="u",+ message_id="$evt-1",+ body="hello",+ timestamp=0,+ ),),- ),+ room_seq=0,+ message_key="$evt-1",+ ))message = _next(ws, "message")assert message["id"] == seqassert message["data"]["payload"]["body"] == "hello"+ # The client speaks positions, so it is told the event's place in its+ # source too.+ assert message["data"]["position"] == {OWN_EVENTS: seq}def test_the_server_pings_and_a_pong_counts_as_a_beat(@@ -178,6 +218,12 @@ def test_closing_the_socket_detaches_the_stream(conn = protocol.connections.get("c1")assert conn is not None+ # The stream detaches in its own cleanup, which the socket cancels rather+ # than awaits; closed straight after opening, that cleanup may still be+ # unwinding a read from the buffer when the socket is already gone.+ deadline = time.monotonic() + 2+ while conn.stream_attached and time.monotonic() < deadline:+ time.sleep(0.01)assert not conn.stream_attacheddiff --git a/core/tests/switch_core/bridges/agent/api/test_connection_subscribe_rooms.py b/core/tests/switch_core/bridges/agent/api/test_connection_subscribe_rooms.pyindex 0dcecfceb..495d6cd74 100644--- a/core/tests/switch_core/bridges/agent/api/test_connection_subscribe_rooms.py+++ b/core/tests/switch_core/bridges/agent/api/test_connection_subscribe_rooms.py@@ -17,6 +17,7 @@ import asynciofrom typing import Anyimport pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.api.handlers import connection_subscribefrom switch_core.bridges.agent.api.schemas import ConnectionSubscribeRequest@@ -26,7 +27,9 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer, Reader-from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS+from switch_core.db.models import TENANT_ZERO_ID+from tests.db_buffer import say, seed_memberAGENT_ID = "agent-1"CONN_ID = "conn-1"@@ -34,10 +37,18 @@ ROOM_A = "!room-a"ROOM_B = "!room-b"[email protected](autouse=True)+async def _agent_rows(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent in both rooms, as rows: a room's unread count is kept against+ the agent and the room, and a room with no row is not counted at all."""+ for room_id in (ROOM_A, ROOM_B):+ await seed_member(session_factory, AGENT_ID, room_id)++class _Protocol:- def __init__(self) -> None:+ def __init__(self, event_buffer: EventBuffer) -> None:self.connections = AgentConnectionRegistry()- self.event_buffer = EventBuffer(sequence_base=0)+ self.event_buffer = event_bufferasync def require_room_member(self, agent_id: str, room_id: str) -> None:return None@@ -54,6 +65,7 @@ class _Protocol:class _Agent:id = AGENT_ID+ tenant_id = TENANT_ZERO_IDmetadata_ = None@@ -64,7 +76,7 @@ def _open(protocol: _Protocol, scope: str, connection_id: str) -> Any:scope=scope,delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -91,13 +103,15 @@ async def _subscribe(@pytest.mark.asyncio-async def test_a_single_scope_subscribe_replaces_the_room_it_held() -> None:+async def test_a_single_scope_subscribe_replaces_the_room_it_held(+ db_buffer: EventBuffer,+) -> None:"""A→B leaves the connection in B alone.Staying in A as well would go on delivering a room the client has left,and leave the agent's slot in it occupied by a client that is not there."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)conn = _open(protocol, "single", CONN_ID)await _subscribe(protocol, ROOM_A, conn.stream_generation, CONN_ID, False)@@ -108,9 +122,9 @@ async def test_a_single_scope_subscribe_replaces_the_room_it_held() -> None:@pytest.mark.asyncio-async def test_resubscribing_to_the_same_room_keeps_it() -> None:+async def test_resubscribing_to_the_same_room_keeps_it(db_buffer: EventBuffer) -> None:"""The replacement must not release what the claim just took."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)conn = _open(protocol, "single", CONN_ID)await _subscribe(protocol, ROOM_A, conn.stream_generation, CONN_ID, False)@@ -120,9 +134,9 @@ async def test_resubscribing_to_the_same_room_keeps_it() -> None:@pytest.mark.asyncio-async def test_an_all_scope_subscribe_accumulates() -> None:+async def test_an_all_scope_subscribe_accumulates(db_buffer: EventBuffer) -> None:"""A supervising connection watches many rooms; one room at a time is not its rule."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)conn = _open(protocol, "all", CONN_ID)await _subscribe(protocol, ROOM_A, conn.stream_generation, CONN_ID, False)@@ -131,27 +145,22 @@ async def test_an_all_scope_subscribe_accumulates() -> None:assert conn.rooms == {ROOM_A, ROOM_B}-def _chatter(protocol: _Protocol, room_id: str, index: int) -> None:- protocol.event_buffer.enqueue(- AGENT_ID,- room_id,- AgentEvent(- type="message",- room_id=room_id,- payload=MessagePayload(- addressed=False,- sender="@u:s",- sender_name="u",- message_id=f"$m-{index}",- body="chatter",- timestamp=0,- ),- ),- )+async def _chatter(+ session_factory: async_sessionmaker[AsyncSession], room_id: str, count: int+) -> int:+ """Messages addressed to nobody, from someone else, in the room's log.+ Returns the room position of the last one."""+ last = 0+ for index in range(count):+ last = (await say(session_factory, room_id, f"chatter {index}")).seq+ return last@pytest.mark.asyncio-async def test_subscribing_takes_over_the_rooms_unread_count() -> None:+async def test_subscribing_takes_over_the_rooms_unread_count(+ db_buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],+) -> None:"""Whoever holds the room slot is the one whose reading clears it.Taking the room here and being told how far behind it is, while the count@@ -159,26 +168,32 @@ async def test_subscribing_takes_over_the_rooms_unread_count() -> None:unable to clear a room it has read to the end of: it is told the samenumber beside every message it is ever handed."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)first = _open(protocol, "single", "conn-a")await _subscribe(protocol, ROOM_A, first.stream_generation, "conn-a", False)- for index in range(3):- _chatter(protocol, ROOM_A, index)+ head = await _chatter(session_factory, ROOM_A, 3)second = _open(protocol, "single", "conn-b")await _subscribe(protocol, ROOM_A, second.stream_generation, "conn-b", True)buffer = protocol.event_buffer- head = buffer.head(AGENT_ID)- assert buffer.unread(AGENT_ID, ROOM_A, head).count == 3- buffer.caught_up(- AGENT_ID, Reader(id="conn-b", is_session=False), ROOM_A, head, "conn-b"+ assert (await buffer.unread(TENANT_ZERO_ID, AGENT_ID, ROOM_A, head)).count == 3+ await buffer.caught_up(+ TENANT_ZERO_ID,+ AGENT_ID,+ Reader(id="conn-b", is_session=False),+ ROOM_A,+ head,+ "conn-b",)- assert buffer.unread(AGENT_ID, ROOM_A, head).count == 0+ assert (await buffer.unread(TENANT_ZERO_ID, AGENT_ID, ROOM_A, head)).count == 0@pytest.mark.asyncio-async def test_a_legacy_subscribe_takes_the_room_from_a_managed_session() -> None:+async def test_a_legacy_subscribe_takes_the_room_from_a_managed_session(+ db_buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],+) -> None:"""The mixed takeover: a session holds the count, a bare connection takes the room.A session outranking every connection is right while the connection is only@@ -187,36 +202,39 @@ async def test_a_legacy_subscribe_takes_the_room_from_a_managed_session() -> Non— and the session that lost the room, whose read was in flight while ithappened, must not be able to take it back by finishing."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)managed = _open(protocol, "single", "conn-a")await _subscribe(protocol, ROOM_A, managed.stream_generation, "conn-a", False)session = Reader(id="managed-a", is_session=True)buffer = protocol.event_buffer- buffer.hand_counting_to(AGENT_ID, session, ROOM_A)- for index in range(3):- _chatter(protocol, ROOM_A, index)+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT_ID, session, ROOM_A)+ head = await _chatter(session_factory, ROOM_A, 3)legacy = _open(protocol, "single", "conn-b")await _subscribe(protocol, ROOM_A, legacy.stream_generation, "conn-b", True)assert protocol.connections.claimant_of(AGENT_ID, ROOM_A) is legacy- head = buffer.head(AGENT_ID)- assert buffer.unread(AGENT_ID, ROOM_A, head).count == 3- buffer.caught_up(- AGENT_ID, Reader(id="conn-b", is_session=False), ROOM_A, head, "conn-b"+ assert (await buffer.unread(TENANT_ZERO_ID, AGENT_ID, ROOM_A, head)).count == 3+ await buffer.caught_up(+ TENANT_ZERO_ID,+ AGENT_ID,+ Reader(id="conn-b", is_session=False),+ ROOM_A,+ head,+ "conn-b",)- assert buffer.unread(AGENT_ID, ROOM_A, head).count == 0+ assert (await buffer.unread(TENANT_ZERO_ID, AGENT_ID, ROOM_A, head)).count == 0- for index in range(2):- _chatter(protocol, ROOM_A, 10 + index)- later = buffer.head(AGENT_ID)- buffer.caught_up(AGENT_ID, session, ROOM_A, later, "conn-a")+ later = await _chatter(session_factory, ROOM_A, 2)+ await buffer.caught_up(TENANT_ZERO_ID, AGENT_ID, session, ROOM_A, later, "conn-a")- assert buffer.unread(AGENT_ID, ROOM_A, later).count == 2+ assert (await buffer.unread(TENANT_ZERO_ID, AGENT_ID, ROOM_A, later)).count == 2@pytest.mark.asyncio-async def test_a_subscribe_waits_while_the_agents_room_slots_are_held() -> None:+async def test_a_subscribe_waits_while_the_agents_room_slots_are_held(+ db_buffer: EventBuffer,+) -> None:"""A repoint lands either side of a decision taken on the slots, never inside one.The registry is in memory and every move through it is synchronous, so a@@ -225,7 +243,7 @@ async def test_a_subscribe_waits_while_the_agents_room_slots_are_held() -> None:this door — the one a repoint arrives at — is made to wait for it ratherthan move a room out from under a decision already taken on it."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)conn = _open(protocol, "single", CONN_ID)async with protocol.connections.slots(AGENT_ID):diff --git a/core/tests/switch_core/bridges/agent/api/test_event_stream_compat.py b/core/tests/switch_core/bridges/agent/api/test_event_stream_compat.pyindex 6e4b6430a..30f932778 100644--- a/core/tests/switch_core/bridges/agent/api/test_event_stream_compat.py+++ b/core/tests/switch_core/bridges/agent/api/test_event_stream_compat.py@@ -8,6 +8,10 @@ window (the expand half of expand/contract), so these drive the server the waysuch a client does: open the stream, read events, beat, and lapse when it stopsbeating. The stream encodes the same frames the socket sends, from the sameloop, so the rules themselves are tested once, on the frames.++Such a client keeps one number. Its stream reads the room's conversation as+well as the agent's own events, so the number it is handed with each event is+a ticket standing for the whole position after it."""from __future__ import annotations@@ -21,6 +25,7 @@ from typing import Anyimport pytestfrom fastapi import HTTPException+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom starlette.responses import StreamingResponsefrom switch_core.artifacts import contract_range@@ -32,9 +37,12 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)-from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.event_buffer import TICKET_FLOOR, EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS, room_sourcefrom switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.observability.metrics import MetricsRegistry, install, uninstall+from tests.db_buffer import say, seed_memberAGENT_ID = "agent-1"ROOM = "room-a"@@ -47,9 +55,16 @@ OLD_RUNTIME = {}[email protected](autouse=True)+async def _agent_row(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent these streams are for, in the room they declare, so its+ events have a row to belong to and the room a conversation to read."""+ await seed_member(session_factory, AGENT_ID, ROOM)++class _Protocol:- def __init__(self) -> None:- self.event_buffer = EventBuffer(sequence_base=0)+ def __init__(self, event_buffer: EventBuffer) -> None:+ self.event_buffer = event_bufferself.connections = AgentConnectionRegistry()self.approval_outcomes = Noneself.sessions = SessionReporter(None)@@ -64,7 +79,11 @@ class _Protocol:def _agent() -> Any:- return SimpleNamespace(id=AGENT_ID, metadata_={"known_agent_type": "claude-code"})+ return SimpleNamespace(+ id=AGENT_ID,+ tenant_id=TENANT_ZERO_ID,+ metadata_={"known_agent_type": "claude-code"},+ )def _message(body: str) -> AgentEvent:@@ -82,6 +101,18 @@ def _message(body: str) -> AgentEvent:)+async def _keep(protocol: _Protocol, body: str) -> int:+ """A message addressed to the agent, kept as one of its own events."""+ return await protocol.event_buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT_ID,+ ROOM,+ _message(body),+ room_seq=0,+ message_key=f"${body}",+ )++async def _open(protocol: _Protocol, **kw: Any) -> StreamingResponse:params: dict[str, Any] = {"accept": "text/event-stream",@@ -134,14 +165,18 @@ class _Reader:async def _beat(protocol: _Protocol, cursor: int, generation: int | None) -> Any:return await connection_beat(AGENT_ID,- ConnectionBeatRequest(connection_id="c1", cursor=cursor, generation=generation),+ ConnectionBeatRequest.model_validate(+ {"connection_id": "c1", "cursor": cursor, "generation": generation}+ ),SimpleNamespace(id=AGENT_ID), # type: ignore[arg-type]protocol, # type: ignore[arg-type])-async def test_an_old_client_connects_receives_beats_and_lapses() -> None:- protocol = _Protocol()+async def test_an_old_client_connects_receives_beats_and_lapses(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)stream = _Reader((await _open(protocol)).body_iterator)event, _, state = await stream.frame()@@ -149,19 +184,31 @@ async def test_an_old_client_connects_receives_beats_and_lapses() -> None:assert state["rooms"] == [ROOM]generation = state["generation"]- seq = protocol.event_buffer.enqueue(AGENT_ID, ROOM, _message("hello"))- event, sent_seq, data = await stream.frame()+ seq = await _keep(protocol, "hello")+ event, sent_id, data = await stream.frame()assert event == "message"- assert sent_seq == str(seq)assert data["payload"]["body"] == "hello"-- beaten = await _beat(protocol, seq, generation)- assert beaten == {"ok": True, "rooms": [ROOM], "cursor": seq}+ # A ticket, not the event's own number, and no position it would not read.+ assert sent_id is not None+ ticket = int(sent_id)+ assert ticket >= TICKET_FLOOR+ assert data["sequence"] == ticket+ assert "position" not in data++ # The beat carries the ticket, which is not read. It is answered with where+ # the connection stands: the last ticket sent and the position it stands for.+ beaten = await _beat(protocol, ticket, generation)+ assert beaten == {+ "ok": True,+ "rooms": [ROOM],+ "cursor": ticket,+ "position": {OWN_EVENTS: seq, room_source(ROOM): 0},+ }conn = protocol.connections.get("c1")assert conn is not Noneconn.last_beat = time.monotonic() - (HEARTBEAT_TTL_SECONDS + 1)- protocol.event_buffer.enqueue(AGENT_ID, ROOM, _message("not after a lapse"))+ await _keep(protocol, "not after a lapse")event, _, data = await stream.frame()assert event == "evicted"@@ -169,14 +216,16 @@ async def test_an_old_client_connects_receives_beats_and_lapses() -> None:await stream.close()with pytest.raises(HTTPException) as caught:- await _beat(protocol, seq, generation)+ await _beat(protocol, ticket, generation)assert caught.value.status_code == 404-async def test_an_old_client_resumes_from_last_event_id() -> None:- protocol = _Protocol()- first = protocol.event_buffer.enqueue(AGENT_ID, ROOM, _message("seen"))- protocol.event_buffer.enqueue(AGENT_ID, ROOM, _message("missed"))+async def test_an_old_client_resumes_from_last_event_id(db_buffer: EventBuffer) -> None:+ """A number below the ticket floor is one of the agent's own events: what+ a client was handed before its stream read the conversation."""+ protocol = _Protocol(db_buffer)+ first = await _keep(protocol, "seen")+ await _keep(protocol, "missed")# The old runtime sent the cursor both ways; the header wins.stream = _Reader(@@ -192,8 +241,88 @@ async def test_an_old_client_resumes_from_last_event_id() -> None:assert data["payload"]["body"] == "missed"-async def test_closing_the_stream_detaches_it_and_keeps_the_connection() -> None:- protocol = _Protocol()+async def test_an_old_client_resumes_from_the_ticket_it_was_handed(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """The ticket holds its place in the room as well as in the agent's own+ events, so a reconnect with it is sent both what was said while it was+ away and what was kept for it."""+ protocol = _Protocol(db_buffer)+ stream = _Reader((await _open(protocol)).body_iterator)+ await stream.frame()+ await _keep(protocol, "seen")+ _, ticket, _ = await stream.frame()+ await stream.close()++ await say(session_factory, ROOM, "said while away")+ await _keep(protocol, "kept while away")++ stream = _Reader(+ (await _open(protocol, start_from="head", last_event_id=ticket)).body_iterator+ )+ await stream.frame()+ said = await stream.frame()+ kept = await stream.frame()+ await stream.close()++ assert said[2]["payload"]["body"] == "said while away"+ assert kept[2]["payload"]["body"] == "kept while away"+++async def test_an_unknown_ticket_opens_with_a_gap(db_buffer: EventBuffer) -> None:+ """A ticket the server no longer holds (expired, or another server's)+ cannot be honoured. The stream opens where things are now and says so+ first, so the client re-reads its rooms rather than believing it is caught+ up."""+ protocol = _Protocol(db_buffer)+ lost = TICKET_FLOOR + 12345++ stream = _Reader((await _open(protocol, last_event_id=str(lost))).body_iterator)+ first, _, _ = await stream.frame()+ event, _, gap = await stream.frame()+ await stream.close()++ assert first == "connection_state"+ assert event == "gap"+ assert gap["from_sequence"] == lost+ assert gap["rooms"] == [ROOM]+ assert gap["all_rooms"] is True+ assert "no longer known" in gap["reason"]+++async def test_the_number_a_gap_hands_an_old_client_resumes_where_it_left_it(+ db_buffer: EventBuffer,+) -> None:+ """The old runtime adopts a gap's `resumed_at` as its number. For a client+ reading the conversation too, that number is a ticket for where the stream+ resumed: sent back, it resumes there, rather than being read as the+ agent's own events from the start and replaying all of them."""+ protocol = _Protocol(db_buffer)+ await _keep(protocol, "before the gap")+ lost = TICKET_FLOOR + 12345++ stream = _Reader((await _open(protocol, last_event_id=str(lost))).body_iterator)+ await stream.frame()+ _, _, gap = await stream.frame()+ await stream.close()+ await _keep(protocol, "after the gap")++ stream = _Reader(+ (await _open(protocol, last_event_id=str(gap["resumed_at"]))).body_iterator+ )+ await stream.frame()+ event, _, data = await stream.frame()+ await stream.close()++ assert gap["resumed_at"] >= TICKET_FLOOR+ assert event == "message"+ assert data["payload"]["body"] == "after the gap"+++async def test_closing_the_stream_detaches_it_and_keeps_the_connection(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)stream = _Reader((await _open(protocol)).body_iterator)await stream.frame()@@ -207,8 +336,10 @@ async def test_closing_the_stream_detaches_it_and_keeps_the_connection() -> None}-async def test_a_stream_attached_over_sse_is_reported_as_sse() -> None:- protocol = _Protocol()+async def test_a_stream_attached_over_sse_is_reported_as_sse(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)stream = _Reader((await _open(protocol)).body_iterator)await stream.frame()@@ -218,10 +349,12 @@ async def test_a_stream_attached_over_sse_is_reported_as_sse() -> None:await stream.close()-async def test_a_client_that_moves_to_the_socket_is_reported_on_the_socket() -> None:+async def test_a_client_that_moves_to_the_socket_is_reported_on_the_socket(+ db_buffer: EventBuffer,+) -> None:"""The transport is the last attach's: an upgraded Console reattaching thesame connection over the socket stops counting as an old client."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)stream = _Reader((await _open(protocol)).body_iterator)await stream.frame()@@ -231,7 +364,7 @@ async def test_a_client_that_moves_to_the_socket_is_reported_on_the_socket() ->scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=8, accepts=1, artifact="agent-runtime"),expected_generation=None,transport="websocket",@@ -243,12 +376,14 @@ async def test_a_client_that_moves_to_the_socket_is_reported_on_the_socket() ->await stream.close()-async def test_a_refused_stream_is_counted_like_a_refused_socket() -> None:+async def test_a_refused_stream_is_counted_like_a_refused_socket(+ db_buffer: EventBuffer,+) -> None:registry = MetricsRegistry()install(registry)try:with pytest.raises(HTTPException) as caught:- await _open(_Protocol(), protocol_version=99, protocol_accepts=99)+ await _open(_Protocol(db_buffer), protocol_version=99, protocol_accepts=99)finally:uninstall()@@ -305,7 +440,7 @@ def test_this_server_admits_an_old_runtime(speaks: int) -> None:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=speaks, accepts=1),expected_generation=None,transport="sse",diff --git a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.pyindex 5ba393216..2cbe07a53 100644--- a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py+++ b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py@@ -14,12 +14,13 @@ from typing import Anyimport pytestfrom fastapi import HTTPException+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom starlette.responses import StreamingResponsefrom switch_core.bridges.agent.api import session_reporterfrom switch_core.bridges.agent.api.handlers import (_open_connection,- _resolve_start_cursor,+ _resolve_start_position,poll_events,)from switch_core.bridges.agent.api.session_reporter import SessionReporter@@ -30,16 +31,29 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)-from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.event_buffer import TICKET_FLOOR, EventBuffer+from switch_core.bridges.agent.protocol.positions import (+ OWN_EVENTS,+ Position,+ room_source,+)+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.telemetry.service import TelemetryServicefrom switch_core.telemetry.sink import TelemetryRecord+from tests.db_buffer import seed_agentAGENT_ID = "agent-1"[email protected](autouse=True)+async def _agent_row(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent these connections are for, so its events have a row to belong to."""+ await seed_agent(session_factory, AGENT_ID)++class _Protocol:- def __init__(self) -> None:- self.event_buffer = EventBuffer(sequence_base=0)+ def __init__(self, event_buffer: EventBuffer) -> None:+ self.event_buffer = event_bufferself.connections = AgentConnectionRegistry()# No approval outcomes: these tests are about opening the stream.self.approval_outcomes = None@@ -74,7 +88,11 @@ class _Protocol:def _agent() -> Any:# `metadata_` carries the agent's runtime, which opening a stream reports.- return SimpleNamespace(id=AGENT_ID, metadata_={"known_agent_type": "claude-code"})+ return SimpleNamespace(+ id=AGENT_ID,+ tenant_id=TENANT_ZERO_ID,+ metadata_={"known_agent_type": "claude-code"},+ )async def _call(protocol: _Protocol, **kw: Any) -> Any:@@ -122,18 +140,22 @@ async def _call(protocol: _Protocol, **kw: Any) -> Any:return conn-async def test_without_the_sse_accept_header_it_long_polls() -> None:- protocol = _Protocol()+async def test_without_the_sse_accept_header_it_long_polls(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)resp = await _call(protocol, accept="application/json")assert protocol.polledassert resp.status_code == 204-async def test_with_the_sse_accept_header_it_opens_the_event_stream() -> None:+async def test_with_the_sse_accept_header_it_opens_the_event_stream(+ db_buffer: EventBuffer,+) -> None:"""How a runtime built before the WebSocket connects, kept for acompatibility window."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)resp = await poll_events(agent_id=AGENT_ID,agent=_agent(),@@ -157,8 +179,8 @@ async def test_with_the_sse_accept_header_it_opens_the_event_stream() -> None:assert conn.stream_transport == "sse"-async def test_opening_registers_the_connection() -> None:- protocol = _Protocol()+async def test_opening_registers_the_connection(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)conn = await _call(protocol, accept="text/event-stream", connection_id="c1", scope="all")@@ -169,8 +191,10 @@ async def test_opening_registers_the_connection() -> None:assert conn.stream_transport == "websocket"-async def test_streaming_without_a_connection_id_is_refused() -> None:- protocol = _Protocol()+async def test_streaming_without_a_connection_id_is_refused(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)with pytest.raises(HTTPException) as excinfo:await _call(protocol, accept="text/event-stream")@@ -182,8 +206,10 @@ async def test_streaming_without_a_connection_id_is_refused() -> None:("field", "value"),[("scope", "everything"), ("event_filter", "some")],)-async def test_bad_scope_or_filter_is_refused(field: str, value: str) -> None:- protocol = _Protocol()+async def test_bad_scope_or_filter_is_refused(+ field: str, value: str, db_buffer: EventBuffer+) -> None:+ protocol = _Protocol(db_buffer)with pytest.raises(HTTPException) as excinfo:await _call(protocol, accept="text/event-stream", connection_id="c1", **{field: value}@@ -192,8 +218,10 @@ async def test_bad_scope_or_filter_is_refused(field: str, value: str) -> None:assert excinfo.value.status_code == 400-async def test_an_incompatible_protocol_version_is_refused() -> None:- protocol = _Protocol()+async def test_an_incompatible_protocol_version_is_refused(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)with pytest.raises(HTTPException) as excinfo:await _call(protocol,@@ -209,13 +237,13 @@ async def test_an_incompatible_protocol_version_is_refused() -> None:assert excinfo.value.detail["remedy"] == "update switch-core"-async def test_the_refusal_body_carries_both_ranges() -> None:+async def test_the_refusal_body_carries_both_ranges(db_buffer: EventBuffer) -> None:"""The refused client never gets a connection_state frame.So the 409 is the only place it can learn what the server speaks, and itis structured rather than a sentence to parse (CHOO-1865)."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)with pytest.raises(HTTPException) as excinfo:await _call(protocol,@@ -235,7 +263,9 @@ async def test_the_refusal_body_carries_both_ranges() -> None:assert detail["message"]-async def test_a_client_that_declares_nothing_connects_and_records_unknown() -> None:+async def test_a_client_that_declares_nothing_connects_and_records_unknown(+ db_buffer: EventBuffer,+) -> None:"""Part 1 refuses nobody on silence.The parameter used to default to the server's own value, so a silent@@ -243,7 +273,7 @@ async def test_a_client_that_declares_nothing_connects_and_records_unknown() ->check had never fired at all. Absent must mean unknown, and unknown muststill connect."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)await _call(protocol,accept="text/event-stream",@@ -257,8 +287,8 @@ async def test_a_client_that_declares_nothing_connects_and_records_unknown() ->assert conn.declaration.declares_protocol is False-async def test_a_declared_client_is_recorded_in_full() -> None:- protocol = _Protocol()+async def test_a_declared_client_is_recorded_in_full(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)await _call(protocol,accept="text/event-stream",@@ -283,13 +313,13 @@ async def test_a_declared_client_is_recorded_in_full() -> None:assert protocol.recorded == [(AGENT_ID, "c1", declared)]-async def test_a_refused_client_is_not_recorded() -> None:+async def test_a_refused_client_is_not_recorded(db_buffer: EventBuffer) -> None:"""Recording happens after the connection opens.A bookkeeping failure must never be why an agent could not connect, and aclient we refused is not one we are running."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)with pytest.raises(HTTPException):await _call(protocol,@@ -301,13 +331,15 @@ async def test_a_refused_client_is_not_recorded() -> None:assert protocol.recorded == []-async def test_an_older_client_inside_the_server_range_is_accepted() -> None:+async def test_an_older_client_inside_the_server_range_is_accepted(+ db_buffer: EventBuffer,+) -> None:"""Overlap, not equality, is the test.The two numbers are equal today, so this pins the behaviour before afuture bump makes it observable."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)await _call(protocol,accept="text/event-stream",@@ -319,32 +351,119 @@ async def test_an_older_client_inside_the_server_range_is_accepted() -> None:assert protocol.connections.get("c1") is not None-# ── Start cursor ────────────────────────────────────────────────────────────+# ── Start position ──────────────────────────────────────────────────────────+++async def _start(+ protocol: _Protocol,+ *,+ start_from: str = "head",+ start_at: str | None = None,+ last_event_id: str | None = None,+ reads_conversation: bool = False,+) -> tuple[Position, int | None]:+ return await _resolve_start_position(+ protocol, # type: ignore[arg-type]+ _agent(),+ start_at=start_at,+ start_from=start_from,+ last_event_id=last_event_id,+ reads_conversation=reads_conversation,+ )+++async def _keep(protocol: _Protocol) -> int:+ """One of the agent's own events, so its head is somewhere."""+ return await protocol.event_buffer.enqueue(+ TENANT_ZERO_ID, AGENT_ID, "room", _event(), room_seq=0, message_key="$e"+ )-def test_head_means_only_what_happens_next() -> None:- protocol = _Protocol()- protocol.event_buffer.enqueue(AGENT_ID, "room", _event())- assert _resolve_start_cursor(protocol, AGENT_ID, "head") == 1+async def test_head_means_only_what_happens_next(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)+ seq = await _keep(protocol)+ assert await _start(protocol) == ({OWN_EVENTS: seq}, None)+ assert await _start(protocol, start_at="head") == ({OWN_EVENTS: seq}, None)-def test_last_event_id_wins_over_start_from() -> None:- protocol = _Protocol()- assert _resolve_start_cursor(protocol, AGENT_ID, "head", "42") == 42+async def test_last_event_id_wins_over_start_from(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)+ assert await _start(protocol, start_from="head", last_event_id="42") == (+ {OWN_EVENTS: 42},+ None,+ )-def test_explicit_start_from_is_honoured() -> None:- protocol = _Protocol()- assert _resolve_start_cursor(protocol, AGENT_ID, "17") == 17+async def test_explicit_start_from_is_honoured(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)+ assert await _start(protocol, start_from="17") == ({OWN_EVENTS: 17}, None)-def test_a_nonsense_cursor_is_refused_rather_than_guessed() -> None:- protocol = _Protocol()+async def test_a_nonsense_cursor_is_refused_rather_than_guessed(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)with pytest.raises(HTTPException) as excinfo:- _resolve_start_cursor(protocol, AGENT_ID, "banana")+ await _start(protocol, start_from="banana")assert excinfo.value.status_code == 400+async def test_a_client_that_keeps_a_position_starts_from_it(+ db_buffer: EventBuffer,+) -> None:+ """One number per source it has read. The agent's own events, when it+ names none of them, start at head like any fresh stream."""+ protocol = _Protocol(db_buffer)+ seq = await _keep(protocol)+ assert await _start(protocol, start_at='{"s": 3, "r:room": 7}') == (+ {OWN_EVENTS: 3, room_source("room"): 7},+ None,+ )+ assert await _start(protocol, start_at='{"r:room": 7}') == (+ {OWN_EVENTS: seq, room_source("room"): 7},+ None,+ )+++async def test_a_position_that_cannot_be_read_is_refused(+ db_buffer: EventBuffer,+) -> None:+ """A typo is an error the client sees, not a position that never moves."""+ protocol = _Protocol(db_buffer)+ with pytest.raises(HTTPException) as excinfo:+ await _start(protocol, start_at='{"room": 7}')+ assert excinfo.value.status_code == 400+++async def test_a_ticket_resumes_the_position_it_stands_for(+ db_buffer: EventBuffer,+) -> None:+ """A client that keeps one number, on a stream that reads the conversation+ too, was handed tickets, and sends back the last one it saw."""+ protocol = _Protocol(db_buffer)+ position = {OWN_EVENTS: 4, room_source("room"): 9}+ (ticket,) = await db_buffer.mint_tickets(TENANT_ZERO_ID, AGENT_ID, [position])+ assert await _start(protocol, start_from=str(ticket), reads_conversation=True) == (+ position,+ None,+ )+++async def test_an_unknown_ticket_starts_at_head_and_is_kept_to_say_so(+ db_buffer: EventBuffer,+) -> None:+ """Expired, or never this server's: where it stood is not known, so the+ stream opens at head, and the number is returned for the gap it opens+ with."""+ protocol = _Protocol(db_buffer)+ seq = await _keep(protocol)+ lost = TICKET_FLOOR + 12345+ assert await _start(protocol, start_from=str(lost), reads_conversation=True) == (+ {OWN_EVENTS: seq},+ lost,+ )++def _event() -> Any:from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload@@ -374,15 +493,17 @@ class TestDeclaringARoomAtOpenTakesOver:and retries forever while the session sits silent."""- async def test_an_incumbent_is_evicted_from_the_room(self) -> None:- protocol = _Protocol()+ async def test_an_incumbent_is_evicted_from_the_room(+ self, db_buffer: EventBuffer+ ) -> None:+ protocol = _Protocol(db_buffer)incumbent = protocol.connections.open(agent_id=AGENT_ID,connection_id="in-session-runtime",scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -403,8 +524,9 @@ class TestDeclaringARoomAtOpenTakesOver:async def test_reconnect_during_bookkeeping_cannot_detach_the_new_stream(monkeypatch: pytest.MonkeyPatch,+ db_buffer: EventBuffer,) -> None:- protocol = _Protocol()+ protocol = _Protocol(db_buffer)entered = asyncio.Event()release = asyncio.Event()@@ -435,7 +557,7 @@ async def test_reconnect_during_bookkeeping_cannot_detach_the_new_stream(conn = protocol.connections.get("c1")assert conn is not Noneassert protocol.connections.beat(- AGENT_ID, "c1", 0, conn.stream_generation+ AGENT_ID, "c1", conn.stream_generation).stream_attachedawait newer.body_iterator.aclose()@@ -456,7 +578,9 @@ class TestOpeningAStreamReportsASession:decided here, so a gate that never opens silences both session eventswhile every test of the reporter alone stays green."""- def _reporting(self) -> tuple[_Protocol, TelemetryService, _RecordingSink]:+ def _reporting(+ self, db_buffer: EventBuffer+ ) -> tuple[_Protocol, TelemetryService, _RecordingSink]:sink = _RecordingSink()service = TelemetryService(sink=sink, # type: ignore[arg-type]@@ -466,13 +590,15 @@ class TestOpeningAStreamReportsASession:telemetry_environment="prod",telemetry_internal=False,)- protocol = _Protocol()+ protocol = _Protocol(db_buffer)protocol.sessions = SessionReporter(service, protocol.connections)protocol.connections.set_close_listener(protocol.sessions.on_close)return protocol, service, sink- async def test_a_new_connection_reports_a_session_start(self) -> None:- protocol, service, sink = self._reporting()+ async def test_a_new_connection_reports_a_session_start(+ self, db_buffer: EventBuffer+ ) -> None:+ protocol, service, sink = self._reporting(db_buffer)await _call(protocol, accept="text/event-stream", connection_id="c1")await service.aclose()@@ -480,9 +606,9 @@ class TestOpeningAStreamReportsASession:assert [r.name for r in sink.sent] == ["switch_core.agent_session_started"]async def test_a_reattach_to_the_same_connection_is_not_another_start(- self,+ self, db_buffer: EventBuffer) -> None:- protocol, service, sink = self._reporting()+ protocol, service, sink = self._reporting(db_buffer)await _call(protocol, accept="text/event-stream", connection_id="c1")await _call(protocol, accept="text/event-stream", connection_id="c1")@@ -490,10 +616,12 @@ class TestOpeningAStreamReportsASession:assert [r.name for r in sink.sent] == ["switch_core.agent_session_started"]- async def test_a_refused_open_then_a_retry_is_one_start(self) -> None:+ async def test_a_refused_open_then_a_retry_is_one_start(+ self, db_buffer: EventBuffer+ ) -> None:"""The room claim refuses the first attempt; nothing began, so only theretry that gets a stream reports."""- protocol, service, sink = self._reporting()+ protocol, service, sink = self._reporting(db_buffer)refusals = [PermissionError("not a member yet")]async def member(agent_id: str, room_id: str) -> None:@@ -514,12 +642,12 @@ class TestOpeningAStreamReportsASession:assert [r.name for r in sink.sent] == ["switch_core.agent_session_started"]async def test_an_open_that_failed_after_registering_is_counted_on_retry(- self,+ self, db_buffer: EventBuffer) -> None:"""An unexpected failure leaves the connection registered, so the retryon the same id reattaches to it. It is still the session's firststream."""- protocol, service, sink = self._reporting()+ protocol, service, sink = self._reporting(db_buffer)failures = [RuntimeError("database went away")]async def member(agent_id: str, room_id: str) -> None:@@ -541,12 +669,12 @@ class TestOpeningAStreamReportsASession:assert [r.name for r in sink.sent] == ["switch_core.agent_session_started"]async def test_closing_the_only_connection_ends_the_session(- self, monkeypatch: pytest.MonkeyPatch+ self, monkeypatch: pytest.MonkeyPatch, db_buffer: EventBuffer) -> None:"""The end is reported only for a connection the start was reportedon, so a start that never fires takes the end down with it."""monkeypatch.setattr(session_reporter, "_RECONNECT_GRACE_SECONDS", 0)- protocol, service, sink = self._reporting()+ protocol, service, sink = self._reporting(db_buffer)await _call(protocol, accept="text/event-stream", connection_id="c1")protocol.connections.close("c1", HEARTBEAT_LAPSED)diff --git a/core/tests/switch_core/bridges/agent/api/test_reattach_refusal.py b/core/tests/switch_core/bridges/agent/api/test_reattach_refusal.pyindex 356332f42..4eca7dd75 100644--- a/core/tests/switch_core/bridges/agent/api/test_reattach_refusal.py+++ b/core/tests/switch_core/bridges/agent/api/test_reattach_refusal.py@@ -25,14 +25,16 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS+from switch_core.db.models import TENANT_ZERO_IDAGENT_ID = "agent-1"CONN_ID = "conn-1"class _Protocol:- def __init__(self) -> None:- self.event_buffer = EventBuffer(sequence_base=0)+ def __init__(self, event_buffer: EventBuffer) -> None:+ self.event_buffer = event_bufferself.connections = AgentConnectionRegistry()# No approval outcomes: these tests are about opening the stream.self.approval_outcomes = None@@ -55,7 +57,7 @@ def _attach(protocol: _Protocol) -> Any:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -64,7 +66,9 @@ def _attach(protocol: _Protocol) -> Any:async def _reopen(protocol: _Protocol, expected_generation: int | None) -> Any:conn, _frames = await _open_connection(config=None, # type: ignore[arg-type]- agent=SimpleNamespace(id=AGENT_ID, metadata_={}), # type: ignore[arg-type]+ agent=SimpleNamespace( # type: ignore[arg-type]+ id=AGENT_ID, tenant_id=TENANT_ZERO_ID, metadata_={}+ ),protocol=protocol, # type: ignore[arg-type]connection_id=CONN_ID,scope="single",@@ -78,8 +82,10 @@ async def _reopen(protocol: _Protocol, expected_generation: int | None) -> Any:return conn-async def test_a_reattach_claiming_a_superseded_incarnation_is_refused() -> None:- protocol = _Protocol()+async def test_a_reattach_claiming_a_superseded_incarnation_is_refused(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)displaced = _attach(protocol).stream_generation_attach(protocol) # the winner attaches; the incarnation bumps@@ -90,9 +96,11 @@ async def test_a_reattach_claiming_a_superseded_incarnation_is_refused() -> Noneassert caught.value.detail["code"] == "taken_over" # type: ignore[index]-async def test_the_refused_reattach_leaves_the_winner_attached() -> None:+async def test_the_refused_reattach_leaves_the_winner_attached(+ db_buffer: EventBuffer,+) -> None:"""Refusing must cost the holder nothing, or it is a way to disrupt it."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)displaced = _attach(protocol).stream_generationwinner = _attach(protocol)held = winner.stream_generation@@ -107,8 +115,8 @@ async def test_the_refused_reattach_leaves_the_winner_attached() -> None:assert protocol.declarations == []-async def test_the_holders_own_reattach_is_admitted() -> None:- protocol = _Protocol()+async def test_the_holders_own_reattach_is_admitted(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)conn = _attach(protocol)before = conn.stream_generation@@ -120,9 +128,11 @@ async def test_the_holders_own_reattach_is_admitted() -> None:assert protocol.declarations != []-async def test_a_client_that_claims_nothing_still_takes_over() -> None:+async def test_a_client_that_claims_nothing_still_takes_over(+ db_buffer: EventBuffer,+) -> None:"""Old clients, and deliberate takeovers, are unconditional as before."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)conn = _attach(protocol)before = conn.stream_generationdiff --git a/core/tests/switch_core/bridges/agent/api/test_room_control_fence.py b/core/tests/switch_core/bridges/agent/api/test_room_control_fence.pyindex b1c0942a4..2a0bf8ad1 100644--- a/core/tests/switch_core/bridges/agent/api/test_room_control_fence.py+++ b/core/tests/switch_core/bridges/agent/api/test_room_control_fence.py@@ -30,6 +30,8 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS+from switch_core.db.models import TENANT_ZERO_IDAGENT_ID = "agent-1"CONN_ID = "conn-1"@@ -40,9 +42,9 @@ ROOM_B = "!room-b"class _Protocol:"""Enough of AgentCore for the two room-control handlers."""- def __init__(self) -> None:+ def __init__(self, event_buffer: EventBuffer) -> None:self.connections = AgentConnectionRegistry()- self.event_buffer = EventBuffer(sequence_base=0)+ self.event_buffer = event_bufferself.membership_checks: list[str] = []async def require_room_member(self, agent_id: str, room_id: str) -> None:@@ -65,7 +67,7 @@ def _attach_declaring(protocol: _Protocol, declaration: ClientDeclaration) -> Anscope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=declaration,expected_generation=None,)@@ -84,6 +86,7 @@ def _request(room_id: str, generation: int | None) -> ConnectionSubscribeRequestclass _Agent:id = AGENT_ID+ tenant_id = TENANT_ZERO_IDmetadata_ = None@@ -99,11 +102,11 @@ async def _call(@pytest.mark.asyncio-async def test_a_displaced_client_cannot_claim_a_room_on_the_winners_connection() -> (- None-):+async def test_a_displaced_client_cannot_claim_a_room_on_the_winners_connection(+ db_buffer: EventBuffer,+) -> None:"""The reviewer's trigger: A owns N, B takes N+1, A claims with N."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)displaced = _attach(protocol).stream_generation # Aconn = _attach(protocol) # B takes overheld = conn.stream_generation@@ -121,13 +124,15 @@ async def test_a_displaced_client_cannot_claim_a_room_on_the_winners_connection(@pytest.mark.asyncio-async def test_the_refusal_comes_before_the_membership_check() -> None:+async def test_the_refusal_comes_before_the_membership_check(+ db_buffer: EventBuffer,+) -> None:"""A refused caller must not reach anything, not merely fail to write.The membership check is a database read on a room the caller named. Adisplaced client should not be able to drive it at all."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)displaced = _attach(protocol).stream_generation_attach(protocol)@@ -138,8 +143,10 @@ async def test_the_refusal_comes_before_the_membership_check() -> None:@pytest.mark.asyncio-async def test_a_displaced_client_cannot_release_the_winners_room() -> None:- protocol = _Protocol()+async def test_a_displaced_client_cannot_release_the_winners_room(+ db_buffer: EventBuffer,+) -> None:+ protocol = _Protocol(db_buffer)displaced = _attach(protocol).stream_generationconn = _attach(protocol)await _call(connection_subscribe, protocol, ROOM_B, conn.stream_generation)@@ -152,9 +159,11 @@ async def test_a_displaced_client_cannot_release_the_winners_room() -> None:@pytest.mark.asyncio-async def test_releasing_without_an_incarnation_is_refused_too() -> None:+async def test_releasing_without_an_incarnation_is_refused_too(+ db_buffer: EventBuffer,+) -> None:"""Each handler answers for itself, so each is asked."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)_attach(protocol)conn = _attach(protocol)await _call(connection_subscribe, protocol, ROOM_B, conn.stream_generation)@@ -168,20 +177,22 @@ async def test_releasing_without_an_incarnation_is_refused_too() -> None:@pytest.mark.asyncio-async def test_no_room_holder_is_evicted_by_a_refused_claim() -> None:+async def test_no_room_holder_is_evicted_by_a_refused_claim(+ db_buffer: EventBuffer,+) -> None:"""The sharpest edge: claiming is what evicts, so a refusal must not.A second connection of the same agent holds the room. A displaced clientasking for it with takeover would otherwise throw that holder off."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)holder = protocol.connections.open(agent_id=AGENT_ID,connection_id="conn-holder",scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -200,8 +211,8 @@ async def test_no_room_holder_is_evicted_by_a_refused_claim() -> None:@pytest.mark.asyncio-async def test_the_current_client_is_admitted() -> None:- protocol = _Protocol()+async def test_the_current_client_is_admitted(db_buffer: EventBuffer) -> None:+ protocol = _Protocol(db_buffer)conn = _attach(protocol)result = await _call(connection_subscribe, protocol, ROOM_A, conn.stream_generation)@@ -211,7 +222,9 @@ async def test_the_current_client_is_admitted() -> None:@pytest.mark.asyncio-async def test_a_client_claiming_nothing_is_refused_once_the_holder_is_fenced() -> None:+async def test_a_client_claiming_nothing_is_refused_once_the_holder_is_fenced(+ db_buffer: EventBuffer,+) -> None:"""Claiming nothing must not be the way past the claim.The displaced client here is one that never saw the first frame of its@@ -219,7 +232,7 @@ async def test_a_client_claiming_nothing_is_refused_once_the_holder_is_fenced()it can be displaced without knowing it. Reading its silence as "too old tofence" would leave the whole check optional at the caller's discretion."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)_attach(protocol)conn = _attach(protocol)held = conn.stream_generation@@ -235,13 +248,15 @@ async def test_a_client_claiming_nothing_is_refused_once_the_holder_is_fenced()@pytest.mark.asyncio-async def test_a_holder_too_old_to_be_fenced_keeps_the_unchecked_behaviour() -> None:+async def test_a_holder_too_old_to_be_fenced_keeps_the_unchecked_behaviour(+ db_buffer: EventBuffer,+) -> None:"""The declaration read is the holder's, so who cannot be fenced stays served.A client built before the incarnation existed has nothing to name, andrefusing it would lock it out of its own rooms rather than close a hole."""- protocol = _Protocol()+ protocol = _Protocol(db_buffer)conn = _attach_declaring(protocol, ClientDeclaration())result = await _call(connection_subscribe, protocol, ROOM_A, None)diff --git a/core/tests/switch_core/bridges/agent/api/test_session_selector.py b/core/tests/switch_core/bridges/agent/api/test_session_selector.pyindex 1c46647ae..771c818b9 100644--- a/core/tests/switch_core/bridges/agent/api/test_session_selector.py+++ b/core/tests/switch_core/bridges/agent/api/test_session_selector.py@@ -18,6 +18,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSAGENT = "agent-demo"CONNECTION = "connection-demo"@@ -36,7 +37,7 @@ def _protocol() -> _Protocol:scope="all",delivery_filter="addressed",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(),expected_generation=None,)diff --git a/core/tests/switch_core/bridges/agent/operations/test_binding_row_is_legacy_only.py b/core/tests/switch_core/bridges/agent/operations/test_binding_row_is_legacy_only.pyindex 7316ff4da..8277d8ee8 100644--- a/core/tests/switch_core/bridges/agent/operations/test_binding_row_is_legacy_only.py+++ b/core/tests/switch_core/bridges/agent/operations/test_binding_row_is_legacy_only.py@@ -26,6 +26,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,Closure,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSAGENT = "agent-1"ROOM = "room-1"@@ -49,7 +50,7 @@ def _open(registry: AgentConnectionRegistry, connection_id: str) -> Any:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)diff --git a/core/tests/switch_core/bridges/agent/operations/test_connect_claims_room.py b/core/tests/switch_core/bridges/agent/operations/test_connect_claims_room.pyindex 9a1557210..5d8d20cca 100644--- a/core/tests/switch_core/bridges/agent/operations/test_connect_claims_room.py+++ b/core/tests/switch_core/bridges/agent/operations/test_connect_claims_room.py@@ -32,6 +32,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,NoStreamAttachedError,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSAGENT = "agent-1"ROOM = "room-1"@@ -49,7 +50,7 @@ def _open(registry: AgentConnectionRegistry, connection_id: str, agent_id: str =scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)diff --git a/core/tests/switch_core/bridges/agent/operations/test_connect_to_room_eviction.py b/core/tests/switch_core/bridges/agent/operations/test_connect_to_room_eviction.pyindex 414a0bb33..fc5e5d815 100644--- a/core/tests/switch_core/bridges/agent/operations/test_connect_to_room_eviction.py+++ b/core/tests/switch_core/bridges/agent/operations/test_connect_to_room_eviction.py@@ -31,7 +31,10 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)-from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.event_buffer import Reader+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS+from switch_core.db.models import TENANT_ZERO_ID+from switch_core.tenant_context import tenant_scopeAGENT = "agent-1"ROOM = "room-1"@@ -63,6 +66,20 @@ class _RecordingSessionStore:self.bindings.append((agent_id, room_id, transport_session_id))+class _UncountedBuffer:+ """The buffer, as far as connecting reaches it.++ Connecting hands the room's unread count to whoever took the room. What+ that does to the count is the buffer's own business, pinned where the+ buffer is tested, and none of it bears on the payload.+ """++ async def hand_counting_to(+ self, tenant_id: str, agent_id: str, reader: Reader, room_id: str+ ) -> None:+ return None++def _protocol(registry: AgentConnectionRegistry,store: _RecordingSessionStore,@@ -104,7 +121,7 @@ def _protocol(return SimpleNamespace(connections=registry,- event_buffer=EventBuffer(sequence_base=0),+ event_buffer=_UncountedBuffer(),agent_session_store=store,session_factory=session_factory,agent_store=SimpleNamespace(get=_returning(agent)),@@ -130,7 +147,7 @@ def _open(registry: AgentConnectionRegistry, connection_id: str):scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -154,9 +171,11 @@ async def _connect_as(connection_id: str) -> dict[str, Any]:CallContext(agent_id=AGENT, session_key=connection_id, session=None))try:- return await definitions.connect_to_room(- ROOM, include_general_instructions=False- )+ # Bound for the call as authenticating the agent binds it for a request.+ with tenant_scope(TENANT_ZERO_ID):+ return await definitions.connect_to_room(+ ROOM, include_general_instructions=False+ )finally:reset_call_context(token)diff --git a/core/tests/switch_core/bridges/agent/operations/test_read_context_room_argument.py b/core/tests/switch_core/bridges/agent/operations/test_read_context_room_argument.pyindex e406068aa..89d3cbe25 100644--- a/core/tests/switch_core/bridges/agent/operations/test_read_context_room_argument.py+++ b/core/tests/switch_core/bridges/agent/operations/test_read_context_room_argument.py@@ -13,10 +13,11 @@ reach and not privilege.from __future__ import annotations-from collections.abc import Callable+from collections.abc import Awaitable, Callablefrom typing import Anyimport pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.operations import context as op_contextfrom switch_core.bridges.agent.operations.callctx import (@@ -31,12 +32,10 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)-from switch_core.bridges.agent.protocol.event_buffer import (- RESTARTED,- EventBuffer,- Reader,-)-from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.bridges.agent.protocol.event_buffer import EventBuffer, Reader+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS+from switch_core.db.models import TENANT_ZERO_ID+from tests.db_buffer import db_buffer_on, say, seed_memberAGENT = "agent-1"CONN = "conn-1"@@ -47,12 +46,12 @@ OTHER_ROOM = "room-elsewhere"class _Protocol:"""Just enough protocol to answer a read: a registry and a recorder."""- def __init__(self, registry: AgentConnectionRegistry) -> None:+ def __init__(self, registry: AgentConnectionRegistry, buffer: EventBuffer) -> None:self.connections = registry- self.event_buffer = EventBuffer(sequence_base=0)+ self.event_buffer = bufferself.calls: list[tuple[str, str]] = []self.members: set[str] = {CONNECTED_ROOM, OTHER_ROOM}- self.while_in_flight: list[Callable[[], None]] = []+ self.while_in_flight: list[Callable[[], Awaitable[None]]] = []async def read_context(self, agent_id: str, room_id: str, **kwargs: Any@@ -61,14 +60,20 @@ class _Protocol:raise PermissionError("Agent is not a member of this room")self.calls.append((agent_id, room_id))for during in self.while_in_flight:- during()+ await during()return {"threads": [], "truncated": False, "oldest_timestamp": None}@pytest.fixture-def protocol(monkeypatch: pytest.MonkeyPatch) -> _Protocol:+async def protocol(+ monkeypatch: pytest.MonkeyPatch,+ session_factory: async_sessionmaker[AsyncSession],+ db_buffer: EventBuffer,+) -> _Protocol:+ for room_id in (CONNECTED_ROOM, OTHER_ROOM):+ await seed_member(session_factory, AGENT, room_id)registry = AgentConnectionRegistry()- service = _Protocol(registry)+ service = _Protocol(registry, db_buffer)monkeypatch.setattr(op_context, "_protocol", service)return service@@ -81,7 +86,7 @@ def connected(protocol: _Protocol) -> None:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -181,67 +186,66 @@ async def test_the_room_is_advertised_as_an_argument() -> None:assert "room_id" not in schema.get("required", [])-def _chatter(protocol: _Protocol, room_id: str) -> None:- protocol.event_buffer.enqueue(- AGENT,- room_id,- AgentEvent(- type="message",- room_id=room_id,- payload=MessagePayload(- addressed=False,- sender="@u:s",- sender_name="u",- message_id="$m",- body="chatter",- timestamp=0,- ),- ),- )+async def _chatter(+ session_factory: async_sessionmaker[AsyncSession], room_id: str+) -> None:+ """Somebody else saying something in the room, addressed to nobody."""+ await say(session_factory, room_id, "chatter")-def _unread(protocol: _Protocol, room_id: str) -> int | None:+async def _unread(protocol: _Protocol, room_id: str) -> int | None:+ """What the room is behind by, through everything said in it so far."""buffer = protocol.event_buffer- return buffer.unread(AGENT, room_id, buffer.head(AGENT)).count+ head = (await buffer.room_heads(TENANT_ZERO_ID, {room_id}))[room_id]+ return (await buffer.unread(TENANT_ZERO_ID, AGENT, room_id, head)).count@pytest.mark.asyncioasync def test_reading_here_is_what_clears_this_room_s_unread_count(- protocol: _Protocol, connected: None, caller: None+ protocol: _Protocol,+ connected: None,+ caller: None,+ session_factory: async_sessionmaker[AsyncSession],) -> None:"""Reading is the act of catching up; being delivered an event is not."""buffer = protocol.event_buffer- buffer.ensure_counting(AGENT, CONN, CONNECTED_ROOM, 0)- _chatter(protocol, CONNECTED_ROOM)- assert _unread(protocol, CONNECTED_ROOM) == 1+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, CONN, CONNECTED_ROOM)+ await _chatter(session_factory, CONNECTED_ROOM)+ assert await _unread(protocol, CONNECTED_ROOM) == 1await read_context()- assert _unread(protocol, CONNECTED_ROOM) == 0+ assert await _unread(protocol, CONNECTED_ROOM) == 0@pytest.mark.asyncioasync def test_reading_elsewhere_clears_nothing(- protocol: _Protocol, connected: None, caller: None+ protocol: _Protocol,+ connected: None,+ caller: None,+ session_factory: async_sessionmaker[AsyncSession],) -> None:"""A cross-room read is a read of somewhere else, and counts nowhere here."""buffer = protocol.event_buffer- buffer.ensure_counting(AGENT, CONN, CONNECTED_ROOM, 0)- buffer.ensure_counting(AGENT, CONN, OTHER_ROOM, 0)- _chatter(protocol, CONNECTED_ROOM)- _chatter(protocol, OTHER_ROOM)+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, CONN, CONNECTED_ROOM)+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, CONN, OTHER_ROOM)+ await _chatter(session_factory, CONNECTED_ROOM)+ await _chatter(session_factory, OTHER_ROOM)await read_context(room_id=OTHER_ROOM)- assert _unread(protocol, CONNECTED_ROOM) == 1- # The room that was read is not covered by this connection, so nothing- # about it was being counted in the first place.- assert _unread(protocol, OTHER_ROOM) == 1+ assert await _unread(protocol, CONNECTED_ROOM) == 1+ # Nor the room that was read: this connection is not in it, so reading it+ # is a look elsewhere, not catching up there.+ assert await _unread(protocol, OTHER_ROOM) == 1@pytest.mark.asyncioasync def test_chatter_arriving_while_the_read_is_in_flight_stays_unread(- protocol: _Protocol, connected: None, caller: None+ protocol: _Protocol,+ connected: None,+ caller: None,+ session_factory: async_sessionmaker[AsyncSession],) -> None:"""History answers from a snapshot, so a later arrival is not in the answer.@@ -249,17 +253,19 @@ async def test_chatter_arriving_while_the_read_is_in_flight_stays_unread(report zero for a message the agent was never shown."""buffer = protocol.event_buffer- buffer.ensure_counting(AGENT, CONN, CONNECTED_ROOM, 0)- protocol.while_in_flight.append(lambda: _chatter(protocol, CONNECTED_ROOM))+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, CONN, CONNECTED_ROOM)+ protocol.while_in_flight.append(lambda: _chatter(session_factory, CONNECTED_ROOM))await read_context()- assert _unread(protocol, CONNECTED_ROOM) == 1+ assert await _unread(protocol, CONNECTED_ROOM) == 1@pytest.mark.asyncioasync def test_a_read_that_lands_after_losing_the_room_clears_nothing(- protocol: _Protocol, connected: None+ protocol: _Protocol,+ connected: None,+ session_factory: async_sessionmaker[AsyncSession],) -> None:"""Two sessions of one agent share a connection; only one is in the room.@@ -268,16 +274,21 @@ async def test_a_read_that_lands_after_losing_the_room_clears_nothing(room that is now somebody else's. That somebody has read nothing."""buffer = protocol.event_buffer- buffer.hand_counting_to(- AGENT, Reader(id="session-a", is_session=True), CONNECTED_ROOM+ await buffer.hand_counting_to(+ TENANT_ZERO_ID, AGENT, Reader(id="session-a", is_session=True), CONNECTED_ROOM)for _ in range(3):- _chatter(protocol, CONNECTED_ROOM)- protocol.while_in_flight.append(- lambda: buffer.hand_counting_to(- AGENT, Reader(id="session-b", is_session=True), CONNECTED_ROOM+ await _chatter(session_factory, CONNECTED_ROOM)++ async def displace() -> None:+ await buffer.hand_counting_to(+ TENANT_ZERO_ID,+ AGENT,+ Reader(id="session-b", is_session=True),+ CONNECTED_ROOM,)- )++ protocol.while_in_flight.append(displace)token = set_call_context(CallContext(@@ -296,25 +307,31 @@ async def test_a_read_that_lands_after_losing_the_room_clears_nothing(finally:reset_call_context(token)- assert _unread(protocol, CONNECTED_ROOM) == 3+ assert await _unread(protocol, CONNECTED_ROOM) == 3@pytest.mark.asyncio-async def test_a_session_reading_after_a_restart_repairs_its_rooms_count(- protocol: _Protocol, connected: None+async def test_a_session_reading_after_a_restart_takes_its_rooms_count(+ protocol: _Protocol,+ connected: None,+ session_factory: async_sessionmaker[AsyncSession],) -> None:- """A session that outlived the server is told "unknown" until it reads.+ """A restart keeps a room's count, and the session's read clears it.- What the restart recorded is the connection the stream reopened on: the- session had not spoken yet. It then reads, presenting itself, and that has- to be the same room — otherwise the read lands nowhere and every message- the session is ever handed carries "not known" beside it.+ The stream starts counting a room for the connection it opened on, before+ any session on it has spoken, and the count is kept in the database, so a+ restart leaves it there unchanged. The session then reads, presenting+ itself, and that has to land on the same count: otherwise the read clears+ nothing and every message the session is handed says the room is behind."""- buffer = protocol.event_buffer- buffer.ensure_counting(AGENT, CONN, CONNECTED_ROOM, 0)- buffer.mark_restarted(AGENT)- _chatter(protocol, CONNECTED_ROOM)- assert buffer.unread(AGENT, CONNECTED_ROOM, buffer.head(AGENT)).reason == RESTARTED+ await protocol.event_buffer.ensure_counting(+ TENANT_ZERO_ID, AGENT, CONN, CONNECTED_ROOM+ )+ await _chatter(session_factory, CONNECTED_ROOM)+ # The server restarts: a new process, with nothing in memory, on the same+ # tables.+ protocol.event_buffer = db_buffer_on(session_factory)+ assert await _unread(protocol, CONNECTED_ROOM) == 1token = set_call_context(CallContext(@@ -333,25 +350,29 @@ async def test_a_session_reading_after_a_restart_repairs_its_rooms_count(finally:reset_call_context(token)- _chatter(protocol, CONNECTED_ROOM)- assert _unread(protocol, CONNECTED_ROOM) == 1+ assert await _unread(protocol, CONNECTED_ROOM) == 0+ await _chatter(session_factory, CONNECTED_ROOM)+ assert await _unread(protocol, CONNECTED_ROOM) == 1@pytest.mark.asyncioasync def test_a_failed_read_catches_up_on_nothing(- protocol: _Protocol, connected: None, caller: None+ protocol: _Protocol,+ connected: None,+ caller: None,+ session_factory: async_sessionmaker[AsyncSession],) -> None:"""An agent that was handed an error has read nothing."""- def boom() -> None:+ async def boom() -> None:raise RuntimeError("homeserver said no")buffer = protocol.event_buffer- buffer.ensure_counting(AGENT, CONN, CONNECTED_ROOM, 0)- _chatter(protocol, CONNECTED_ROOM)+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, CONN, CONNECTED_ROOM)+ await _chatter(session_factory, CONNECTED_ROOM)protocol.while_in_flight.append(boom)with pytest.raises(RuntimeError, match="homeserver said no"):await read_context()- assert _unread(protocol, CONNECTED_ROOM) == 1+ assert await _unread(protocol, CONNECTED_ROOM) == 1diff --git a/core/tests/switch_core/bridges/agent/operations/test_role_holder_identity.py b/core/tests/switch_core/bridges/agent/operations/test_role_holder_identity.pyindex b3b7456b7..70f78fc8a 100644--- a/core/tests/switch_core/bridges/agent/operations/test_role_holder_identity.py+++ b/core/tests/switch_core/bridges/agent/operations/test_role_holder_identity.py@@ -29,6 +29,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSAGENT = "agent-1"CONNECTION = "connection-1"@@ -51,7 +52,7 @@ def holders():scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)diff --git a/core/tests/switch_core/bridges/agent/operations/test_session_room_resolution.py b/core/tests/switch_core/bridges/agent/operations/test_session_room_resolution.pyindex 63a053581..3593b98d5 100644--- a/core/tests/switch_core/bridges/agent/operations/test_session_room_resolution.py+++ b/core/tests/switch_core/bridges/agent/operations/test_session_room_resolution.py@@ -19,6 +19,7 @@ from types import SimpleNamespacefrom typing import Anyimport pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.operations import definitionsfrom switch_core.bridges.agent.operations.callctx import (@@ -37,7 +38,10 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer, Reader-from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS+from switch_core.db.models import TENANT_ZERO_ID+from switch_core.tenant_context import tenant_scope+from tests.db_buffer import say, seed_memberAGENT = "agent-1"CONNECTION = "connection-1"@@ -94,7 +98,7 @@ def _open(registry: AgentConnectionRegistry) -> Any:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -161,21 +165,9 @@ async def test_a_caller_with_no_session_still_reads_its_connection(registry) -># ── moving a session between rooms ───────────────────────────────────────────---def _chatter(room_id: str, index: int) -> AgentEvent:- return AgentEvent(- type="message",- room_id=room_id,- payload=MessagePayload(- addressed=False,- sender="@u:s",- sender_name="u",- message_id=f"$m-{index}",- body="chatter",- timestamp=0,- ),- )+#+# Connecting runs inside the agent's tenant, which authenticating it binds for+# a request; each call below binds it the same way.@pytest.mark.asyncio@@ -198,7 +190,7 @@ async def test_connecting_vacates_only_the_callers_own_room(monkeypatch.setattr(definitions, "build_room_instructions", lambda *a, **kw: "")init_operations_protocol(_protocol_for(registry, "room-c"))- with call_context(_caller("session-a", ROOM_A)):+ with tenant_scope(TENANT_ZERO_ID), call_context(_caller("session-a", ROOM_A)):await definitions.connect_to_room("room-c", include_general_instructions=False)assert registry.session_room(AGENT, "session-a") == "room-c"@@ -225,7 +217,7 @@ async def test_a_room_a_sibling_has_taken_is_not_vacated(monkeypatch.setattr(definitions, "build_room_instructions", lambda *a, **kw: "")init_operations_protocol(_protocol_for(registry, "room-c"))- with call_context(_caller("session-a", ROOM_A)):+ with tenant_scope(TENANT_ZERO_ID), call_context(_caller("session-a", ROOM_A)):await definitions.connect_to_room("room-c", include_general_instructions=False)assert connection.rooms == {ROOM_A, "room-c"}@@ -248,7 +240,7 @@ async def test_displacing_a_sibling_names_it_in_the_warning(monkeypatch.setattr(definitions, "build_room_instructions", lambda *a, **kw: "")init_operations_protocol(_protocol_for(registry, "room-c"))- with call_context(_caller("session-a", None)):+ with tenant_scope(TENANT_ZERO_ID), call_context(_caller("session-a", None)):result = await definitions.connect_to_room("room-c", include_general_instructions=False)@@ -258,7 +250,10 @@ async def test_displacing_a_sibling_names_it_in_the_warning(@pytest.mark.asyncioasync def test_connecting_takes_the_rooms_unread_count(- registry, monkeypatch: pytest.MonkeyPatch+ registry,+ monkeypatch: pytest.MonkeyPatch,+ session_factory: async_sessionmaker[AsyncSession],+ db_buffer: EventBuffer,) -> None:"""Whose reading clears a room follows who is in it.@@ -269,25 +264,30 @@ async def test_connecting_takes_the_rooms_unread_count(_open(registry)registry.place_session(AGENT, "session-b", "room-c", CONNECTION)monkeypatch.setattr(definitions, "build_room_instructions", lambda *a, **kw: "")- protocol = _protocol_for(registry, "room-c")+ await seed_member(session_factory, AGENT, "room-c")+ protocol = _protocol_for(registry, "room-c", event_buffer=db_buffer)init_operations_protocol(protocol)buffer = protocol.event_buffer- buffer.hand_counting_to(AGENT, Reader(id="session-b", is_session=True), "room-c")+ await buffer.hand_counting_to(+ TENANT_ZERO_ID, AGENT, Reader(id="session-b", is_session=True), "room-c"+ )for index in range(2):- buffer.enqueue(AGENT, "room-c", _chatter("room-c", index))+ said = await say(session_factory, "room-c", f"chatter {index}")- with call_context(_caller("session-a", None)):+ with tenant_scope(TENANT_ZERO_ID), call_context(_caller("session-a", None)):await definitions.connect_to_room("room-c", include_general_instructions=False)- buffer.caught_up(+ # A read session-b began before it lost the room, landing after it did.+ await buffer.caught_up(+ TENANT_ZERO_ID,AGENT,Reader(id="session-b", is_session=True),"room-c",- buffer.head(AGENT),+ said.seq,CONNECTION,)- assert buffer.unread(AGENT, "room-c", buffer.head(AGENT)).count == 2+ assert (await buffer.unread(TENANT_ZERO_ID, AGENT, "room-c", said.seq)).count == 2@pytest.mark.asyncio@@ -299,7 +299,7 @@ async def test_displacing_nobody_warns_about_nothing(monkeypatch.setattr(definitions, "build_room_instructions", lambda *a, **kw: "")init_operations_protocol(_protocol_for(registry, "room-c"))- with call_context(_caller("session-a", None)):+ with tenant_scope(TENANT_ZERO_ID), call_context(_caller("session-a", None)):result = await definitions.connect_to_room("room-c", include_general_instructions=False)@@ -324,7 +324,7 @@ async def test_one_eviction_is_reported_once_and_names_the_session(scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -334,7 +334,7 @@ async def test_one_eviction_is_reported_once_and_names_the_session(monkeypatch.setattr(definitions, "build_room_instructions", lambda *a, **kw: "")init_operations_protocol(_protocol_for(registry, "room-c"))- with call_context(_caller("session-a", None)):+ with tenant_scope(TENANT_ZERO_ID), call_context(_caller("session-a", None)):result = await definitions.connect_to_room("room-c", include_general_instructions=False)@@ -359,7 +359,7 @@ async def test_evicting_another_connection_still_names_the_connection(scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -368,7 +368,7 @@ async def test_evicting_another_connection_still_names_the_connection(monkeypatch.setattr(definitions, "build_room_instructions", lambda *a, **kw: "")init_operations_protocol(_protocol_for(registry, "room-c"))- with call_context(_caller("session-a", None)):+ with tenant_scope(TENANT_ZERO_ID), call_context(_caller("session-a", None)):result = await definitions.connect_to_room("room-c", include_general_instructions=False)@@ -376,7 +376,27 @@ async def test_evicting_another_connection_still_names_the_connection(assert "connection connection-old" in result["warning"]-def _protocol_for(registry: AgentConnectionRegistry, room_id: str) -> Any:+class _UncountedBuffer:+ """Takes the hand-over of a room's unread count and keeps none of it."""++ async def hand_counting_to(+ self, tenant_id: str, agent_id: str, reader: Reader, room_id: str+ ) -> None:+ return None+++def _protocol_for(+ registry: AgentConnectionRegistry,+ room_id: str,+ *,+ event_buffer: EventBuffer | None = None,+) -> Any:+ """Just enough protocol to connect to `room_id`.++ Connecting hands the room's unread count over, and the count is kept in+ the database: a test about the count passes a db-buffer, and every other+ one gets a stand-in that keeps nothing.+ """room = SimpleNamespace(id=room_id, name="Room C", description="A room")profile = {"connection_model": "session_addressable",@@ -402,7 +422,7 @@ def _protocol_for(registry: AgentConnectionRegistry, room_id: str) -> Any:return SimpleNamespace(connections=registry,- event_buffer=EventBuffer(sequence_base=0),+ event_buffer=event_buffer or _UncountedBuffer(),agent_session_store=_AbsentSessionStore(),session_factory=session_factory,agent_store=SimpleNamespace(diff --git a/core/tests/switch_core/bridges/agent/protocol/test_bridge_identity_tenant_scope.py b/core/tests/switch_core/bridges/agent/protocol/test_bridge_identity_tenant_scope.pyindex 90a68598b..4b8a69ae6 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_bridge_identity_tenant_scope.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_bridge_identity_tenant_scope.py@@ -152,7 +152,7 @@ class _StoppableClientLifecycle:class TestBridgeIdentityRemovalTenantScope:async def test_other_tenants_bridge_is_not_stripped_of_a_same_named_identity(- self, session_factory: async_sessionmaker[AsyncSession]+ self, session_factory: async_sessionmaker[AsyncSession], db_buffer: EventBuffer) -> None:# Tenant A deletes an agent named "shared-name"; tenant B happens to# have its own, unrelated agent of the same name on its own bridge.@@ -167,7 +167,7 @@ class TestBridgeIdentityRemovalTenantScope:[tenant_a_bridge, tenant_b_bridge])svc.client_lifecycle = _StoppableClientLifecycle(session_factory) # type: ignore[attr-defined]- svc.event_buffer = EventBuffer(sequence_base=0) # type: ignore[attr-defined]+ svc.event_buffer = db_buffer # type: ignore[attr-defined]owner = await make_owner(session_factory)agent_id = await register(svc, "shared-name", owner)@@ -182,7 +182,7 @@ class TestBridgeIdentityRemovalTenantScope:assert tenant_b_bridge.adapter.identities_removed == []async def test_unbound_deletion_is_refused_before_the_agent_is_stopped(- self, session_factory: async_sessionmaker[AsyncSession]+ self, session_factory: async_sessionmaker[AsyncSession], db_buffer: EventBuffer) -> None:# Same precondition from the other end. Raising part-way through leaves# the worst state of all: the client stopped but never removed, the@@ -191,7 +191,7 @@ class TestBridgeIdentityRemovalTenantScope:svc.collab_lifecycle = _MultiTenantBridges([]) # type: ignore[attr-defined]lifecycle = _StoppableClientLifecycle(session_factory)svc.client_lifecycle = lifecycle # type: ignore[attr-defined]- svc.event_buffer = EventBuffer(sequence_base=0) # type: ignore[attr-defined]+ svc.event_buffer = db_buffer # type: ignore[attr-defined]owner = await make_owner(session_factory)agent_id = await register(svc, "still-here", owner)diff --git a/core/tests/switch_core/bridges/agent/protocol/test_connections.py b/core/tests/switch_core/bridges/agent/protocol/test_connections.pyindex 64f7da6c4..53a779657 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_connections.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_connections.py@@ -11,6 +11,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (HEARTBEAT_LAPSED,HEARTBEAT_TTL_SECONDS,MAX_CONNECTIONS_PER_AGENT,+ POSITIONS_PROTOCOL_REVISION,PROTOCOL_ACCEPTS,PROTOCOL_VERSION,AgentConnectionRegistry,@@ -25,6 +26,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (UnfencedBeatError,UnknownConnectionError,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSAGENT = "agent-1"OTHER_AGENT = "agent-2"@@ -50,7 +52,7 @@ def _open(scope=scope, # type: ignore[arg-type]delivery_filter=delivery_filter, # type: ignore[arg-type]spawn_capable=spawn_capable,- cursor=cursor,+ position={OWN_EVENTS: cursor},declaration=ClientDeclaration(speaks=speaks),expected_generation=expected_generation,)@@ -91,7 +93,7 @@ def test_incompatible_protocol_is_refused() -> None:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION + 1),expected_generation=None,)@@ -109,7 +111,7 @@ def _open_declaring(scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=declaration,expected_generation=None,)@@ -222,7 +224,7 @@ def test_a_beat_without_a_stream_is_rejected() -> None:# The client is alive but receiving nothing. It must be told, not left# believing it is connected.with pytest.raises(NoStreamAttachedError):- registry.beat(AGENT, "c1", 5, conn.stream_generation)+ registry.beat(AGENT, "c1", conn.stream_generation)def test_a_stale_heartbeat_kills_the_connection_even_with_a_stream() -> None:@@ -248,15 +250,6 @@ def test_a_superseded_stream_cannot_clear_the_flag_of_its_replacement() -> None:assert conn.stream_attached-def test_beat_advances_the_cursor_but_never_rewinds_it() -> None:- registry = AgentConnectionRegistry()- conn = _open(registry, "c1")- current = conn.stream_generation-- assert registry.beat(AGENT, "c1", 7, current).cursor == 7- assert registry.beat(AGENT, "c1", 3, current).cursor == 7--def test_a_beat_for_a_superseded_incarnation_is_refused() -> None:registry = AgentConnectionRegistry()conn = _open(registry, "c1")@@ -265,28 +258,22 @@ def test_a_beat_for_a_superseded_incarnation_is_refused() -> None:_open(registry, "c1") # the winner attaches; incarnation bumpswith pytest.raises(SupersededConnectionError) as caught:- registry.beat(AGENT, "c1", 0, displaced)+ registry.beat(AGENT, "c1", displaced)assert caught.value.presented == displacedassert caught.value.current == displaced + 1-def test_a_refused_beat_leaves_the_winners_cursor_where_it_was() -> None:+def test_a_refused_beat_is_not_counted_for_the_winner() -> None:registry = AgentConnectionRegistry()conn = _open(registry, "c1")displaced = conn.stream_generationwinner = _open(registry, "c1")- registry.beat(AGENT, "c1", 7, winner.stream_generation)-- before = winner.cursor- assert before == 7+ registry.beat(AGENT, "c1", winner.stream_generation)- # The displaced client is further ahead than the winner — it was sent- # events the winner never saw. Adopting that cursor would skip them.with pytest.raises(SupersededConnectionError):- registry.beat(AGENT, "c1", 99, displaced)+ registry.beat(AGENT, "c1", displaced)- assert winner.cursor == beforeassert winner.beats == 1@@ -299,7 +286,7 @@ def test_a_refused_beat_does_not_keep_the_connection_alive() -> None:winner.last_beat = agingwith pytest.raises(SupersededConnectionError):- registry.beat(AGENT, "c1", 0, displaced)+ registry.beat(AGENT, "c1", displaced)# The loser cannot hold the winner's connection open on its behalf: the# clock keeps running, so a winner that has gone quiet still lapses.@@ -313,7 +300,7 @@ def test_a_beat_from_a_client_that_cannot_be_fenced_is_accepted() -> None:# A client that declares nothing sends no incarnation. Unknown is not# superseded.- assert registry.beat(AGENT, "c1", 4, None).cursor == 4+ assert registry.beat(AGENT, "c1", None).beats == 1def test_a_client_declaring_the_revision_before_the_fence_ticks_unfenced() -> None:@@ -323,22 +310,20 @@ def test_a_client_declaring_the_revision_before_the_fence_ticks_unfenced() -> No# The server still accepts revision 1, and that revision has no incarnation# to return, so its tick is taken as it always was. Refusing it would break# every client released before the fence rather than fencing it.- assert registry.beat(AGENT, "c1", 4, None).cursor == 4+ assert registry.beat(AGENT, "c1", None).beats == 1def test_a_holder_that_carries_an_incarnation_may_not_tick_without_one() -> None:registry = AgentConnectionRegistry()conn = _open(registry, "c1")- conn.cursor = 4# Otherwise the fence is a formality: a displaced client that never saw its# own incarnation — or one that would rather not be fenced — sends null and# is treated as the holder, which is what the incarnation exists to stop.with pytest.raises(UnfencedBeatError) as caught:- registry.beat(AGENT, "c1", 99, None)+ registry.beat(AGENT, "c1", None)assert caught.value.speaks == PROTOCOL_VERSION- assert conn.cursor == 4assert conn.beats == 0@@ -353,7 +338,7 @@ def test_what_a_connection_cannot_be_fenced_by_follows_its_current_holder() -> N_open(registry, "c1")with pytest.raises(UnfencedBeatError):- registry.beat(AGENT, "c1", 4, None)+ registry.beat(AGENT, "c1", None)# ── Room slots ──────────────────────────────────────────────────────────────@@ -547,7 +532,7 @@ class TestAReattachCanBeFenced:conn.stream_attached,conn.declaration,) == before- assert registry.beat(AGENT, "c1", 7, conn.stream_generation).cursor == 7+ assert registry.beat(AGENT, "c1", conn.stream_generation).beats == 1def test_claiming_nothing_still_takes_the_connection_over(self) -> None:"""A deliberate takeover makes no claim, and keeps working.@@ -626,3 +611,26 @@ class TestLiveConnectionIds:conn.last_beat = time.monotonic() - HEARTBEAT_TTL_SECONDS - 1assert registry.live_connection_ids() == {"c2"}+++def test_the_one_number_a_client_is_told_is_a_ticket_only_where_it_has_to_be() -> None:+ """A client holding one number over the conversation and its own events is+ told a ticket standing for its position. A client that holds the position+ is told its own events' number beside it, as is any client that reads only+ its own events."""+ registry = AgentConnectionRegistry()+ holds_position = _open(registry, "c1", cursor=7)+ one_number = _open(registry, "c2", cursor=7, speaks=POSITIONS_PROTOCOL_REVISION - 1)+ own_events_only = _open(+ registry,+ "c3",+ cursor=7,+ delivery_filter="addressed",+ speaks=POSITIONS_PROTOCOL_REVISION - 1,+ )+ for conn in (holds_position, one_number, own_events_only):+ conn.ticket = 2**48 + 5++ assert holds_position.cursor == 7+ assert one_number.cursor == 2**48 + 5+ assert own_events_only.cursor == 7diff --git a/core/tests/switch_core/bridges/agent/protocol/test_controller_presence.py b/core/tests/switch_core/bridges/agent/protocol/test_controller_presence.pyindex 46d74c021..467df576d 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_controller_presence.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_controller_presence.py@@ -613,11 +613,21 @@ def _addressing_client(ns._report_addressed = lambda *_a, **_k: Nonens._triggered_by_auto_reply = AgentConsumer._triggered_by_auto_replyns.actor = SimpleNamespace(send_message=sent)- ns._event_buffer = SimpleNamespace(- enqueue=lambda _agent_id, _room_id, event: enqueued.append(- event.payload.message_id- )- )++ async def _enqueue(+ _tenant_id: str,+ _agent_id: str,+ _room_id: str,+ event: Any,+ *,+ room_seq: int,+ message_key: str | None,+ ) -> int:+ enqueued.append(event.payload.message_id)+ return len(enqueued)++ ns.tenant_id = TENANT_ZERO_ID+ ns._event_buffer = SimpleNamespace(enqueue=_enqueue)ns._sender_handle = AgentConsumer._sender_handle.__get__(ns)ns._post_auto_reply = AgentConsumer._post_auto_reply.__get__(ns)return ns, sent, enqueueddiff --git a/core/tests/switch_core/bridges/agent/protocol/test_conversation_reading.py b/core/tests/switch_core/bridges/agent/protocol/test_conversation_reading.pynew file mode 100644index 000000000..fc2466644--- /dev/null+++ b/core/tests/switch_core/bridges/agent/protocol/test_conversation_reading.py@@ -0,0 +1,216 @@+"""A room's conversation, read for an agent from the room's own log.++What a reader that wants everything (`filter=all`, the legacy polls) is sent+besides the agent's own events. Three properties are pinned here, each found+running the stream end to end:++- a row is read once the agent's consumer has decided it is not the agent's+ own, and no sooner, so it is never sent twice;+- the agent's own event for a message stands for that message up to the row it+ was delivered through, so a file that arrives after its group was delivered+ is still read;+- a place in a room past the room's newest row is from a history the room no+ longer has, and is brought back to the room's end.+"""++from __future__ import annotations++from datetime import UTC, datetime, timedelta++import pytest+from sqlalchemy import delete+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.attachments import ATTACHMENT_GROUP_KEY+from switch_core.bridges.agent.protocol.event_buffer import BufferedEvent, EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS, room_source+from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.db.models import TENANT_ZERO_ID, Agent, Message, MessageAttachment+from switch_core.db.session_scope import tenant_session+from switch_core.db.stores.message_store import MessageStore+from tests.db_buffer import db_buffer_on, say, seed_member, seed_room++AGENT = "agent-1"+ROOM = "room-1"+EMPTY_ROOM = "room-2"++SessionFactory = async_sessionmaker[AsyncSession]++[email protected](autouse=True)+async def _rows(session_factory: SessionFactory) -> None:+ await seed_member(session_factory, AGENT, ROOM)+ await seed_room(session_factory, EMPTY_ROOM)+++def _unsettling(session_factory: SessionFactory) -> EventBuffer:+ """A buffer that takes a minute to settle a row on its own, so a test row+ is read only when the agent's own events say it was decided."""+ return db_buffer_on(session_factory, settle_seconds=60.0)+++async def _keep(buffer: EventBuffer, room_seq: int, message_key: str) -> None:+ """The agent's own event for a message addressed to it, as its consumer+ keeps it."""+ await buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT,+ ROOM,+ AgentEvent(+ type="message",+ room_id=ROOM,+ payload=MessagePayload(+ addressed=True,+ sender="@alice:test",+ sender_name="Alice",+ message_id=message_key,+ body="@agent over to you",+ timestamp=0,+ ),+ ),+ room_seq=room_seq,+ message_key=message_key,+ )+++def _bodies(items: list[BufferedEvent]) -> list[str | None]:+ return [getattr(item.event.payload, "body", None) for item in items]+++async def test_what_came_before_the_agents_own_event_is_read_at_once(+ session_factory: SessionFactory,+) -> None:+ """The consumer takes a room's rows one at a time, in order, so once it has+ kept a row as the agent's own, every row before it is decided. Waiting for+ them to settle would send the agent its mention before the conversation+ that led up to it."""+ buffer = _unsettling(session_factory)+ await say(session_factory, ROOM, "before")+ asked = await say(session_factory, ROOM, "@agent over to you")+ await _keep(buffer, asked.seq, asked.transport_event_id)+ await say(session_factory, ROOM, "after")++ read = await buffer.read_conversation(TENANT_ZERO_ID, AGENT, {ROOM: 0}, limit=100)++ assert _bodies(read.events) == ["before"]+ # Looked through the agent's own row, and no further: "after" is not+ # decided yet.+ assert read.through == {ROOM: asked.seq}+++async def test_a_row_not_yet_decided_holds_back_the_rows_after_it(+ session_factory: SessionFactory,+) -> None:+ """Rows are read as an unbroken run from the reader's place. A settled row+ after an unsettled one waits for it, or the reader's place would move past+ the unsettled row and it would never be read."""+ buffer = db_buffer_on(session_factory, settle_seconds=30.0)+ now = datetime.now(UTC)+ await say(session_factory, ROOM, "settled", sent_at=now - timedelta(minutes=5))+ await say(session_factory, ROOM, "fresh", sent_at=now)+ await say(session_factory, ROOM, "stamped late", sent_at=now - timedelta(minutes=5))++ read = await buffer.read_conversation(TENANT_ZERO_ID, AGENT, {ROOM: 0}, limit=100)++ assert _bodies(read.events) == ["settled"]+++async def test_a_file_that_arrives_after_its_group_was_delivered_is_still_read(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """The consumer delivers several files posted as one once they are all in,+ or when it stops waiting for the rest. A file arriving after that is past+ the row the group was delivered through: it is conversation, and the files+ already delivered are not sent again."""+ buffer = db_buffer+ long_ago = datetime.now(UTC) - timedelta(minutes=1)++ def part(index: int) -> dict[str, object]:+ return {ATTACHMENT_GROUP_KEY: {"id": "grp", "index": index, "total": 3}}++ await say(session_factory, ROOM, "first", content=part(0), sent_at=long_ago)+ second = await say(+ session_factory, ROOM, "second", content=part(1), sent_at=long_ago+ )+ await _keep(buffer, second.seq, "grp")+ await say(session_factory, ROOM, "late", content=part(2), sent_at=long_ago)++ read = await buffer.read_conversation(TENANT_ZERO_ID, AGENT, {ROOM: 0}, limit=100)++ assert _bodies(read.events) == ["late"]+++async def test_a_message_posted_between_the_files_of_a_group_goes_out_first(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """A multi-file message goes out once, at its last file. A message posted+ between its files goes out before it, so the room's events go out in rising+ order and a client that disconnects after the group has not been moved past+ the message in between."""+ buffer = db_buffer+ long_ago = datetime.now(UTC) - timedelta(minutes=1)++ async def file(index: int, name: str) -> Message:+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:+ row = await MessageStore().create(+ session,+ Message(+ room_id=ROOM,+ transport_event_id=f"$part{index}",+ sender_id="@alice:test",+ sender_name="Alice",+ event_type="m.room.message",+ msgtype="m.file",+ body=name,+ formatted_body=None,+ content={+ "body": name,+ ATTACHMENT_GROUP_KEY: {"id": "g1", "index": index, "total": 2},+ },+ sent_at=long_ago,+ ),+ [MessageAttachment(uri=f"mxc://s/{name}", filename=name)],+ )+ await session.commit()+ return row++ await file(0, "one.pdf")+ between = await say(session_factory, ROOM, "in between", sent_at=long_ago)+ last = await file(1, "two.pdf")++ read = await buffer.read_conversation(TENANT_ZERO_ID, AGENT, {ROOM: 0}, limit=100)++ assert [item.seq for item in read.events] == [between.seq, last.seq]+ assert _bodies(read.events)[0] == "in between"+++async def test_a_place_past_the_end_of_a_room_is_brought_back_to_it(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """A position never moves back, so a place a room's log does not reach (a+ restored database) would pass over that many of its next messages. The+ agent's own events are left to their own checks."""+ buffer = db_buffer+ await say(session_factory, ROOM, "one")+ await say(session_factory, ROOM, "two")++ within, past = await buffer.within_rooms(+ TENANT_ZERO_ID,+ {OWN_EVENTS: 99, room_source(ROOM): 9, room_source(EMPTY_ROOM): 3},+ )++ assert within == {OWN_EVENTS: 99, room_source(ROOM): 2, room_source(EMPTY_ROOM): 0}+ assert past == [ROOM, EMPTY_ROOM]+++async def test_a_poll_for_an_agent_deleted_meanwhile_saves_nothing(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """A long poll can be waiting when its agent is deleted. The place it would+ save goes with the agent rather than failing the request."""+ buffer = db_buffer+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:+ await session.execute(delete(Agent).where(Agent.id == AGENT))+ await session.commit()++ assert await buffer.poll(TENANT_ZERO_ID, AGENT, rooms={ROOM}, timeout=0) == []diff --git a/core/tests/switch_core/bridges/agent/protocol/test_delete_agent.py b/core/tests/switch_core/bridges/agent/protocol/test_delete_agent.pyindex c08413cd8..023637495 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_delete_agent.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_delete_agent.py@@ -45,12 +45,12 @@ class _DeletingClientLifecycle(FakeClientLifecycle):class TestDeleteAgentInARoom:async def test_the_agent_its_client_and_both_memberships_go(- self, session_factory: async_sessionmaker[AsyncSession]+ self, session_factory: async_sessionmaker[AsyncSession], db_buffer: EventBuffer) -> None:svc = make_service(session_factory)lifecycle = _DeletingClientLifecycle(session_factory)svc.client_lifecycle = lifecycle # type: ignore[assignment]- svc.event_buffer = EventBuffer(sequence_base=0)+ svc.event_buffer = db_bufferowner = await make_owner(session_factory)agent_id = await register(svc, "in-a-room", owner)diff --git a/core/tests/switch_core/bridges/agent/protocol/test_event_buffer.py b/core/tests/switch_core/bridges/agent/protocol/test_event_buffer.pyindex 3697c68ca..5a6771f31 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_event_buffer.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_event_buffer.py@@ -4,23 +4,60 @@ The auto_session watcher consumes a separate, agent-scoped notification stream.The critical invariant: fanning an event out to that stream must NOT remove itfrom the per-room queue a live session poller drains — otherwise the watcherwould steal events from connected rooms.++The agent's own events (addressed messages, arrivals it listens for, tasks,+commands) are what the buffer keeps. The rest of a room's conversation stays in+the room's log, and the per-room and all-rooms polls read it from there."""from __future__ import annotations+from collections.abc import AsyncIterator+from contextlib import asynccontextmanager++import pytest+from sqlalchemy import delete, select+from sqlalchemy.exc import OperationalError+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.agent.protocol import event_bufferfrom switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS, Positionfrom switch_core.bridges.agent.protocol.types import (AgentEvent,+ CommandPayload,MessagePayload,RoomJoinPayload,TaskDelegatePayload,)+from switch_core.db.models import (+ AGENT_EVENT_BOOT_MAX,+ TENANT_ZERO_ID,+ TICKET_CEILING,+ TICKET_FLOOR,+ Agent,+ AgentPollPosition,+)+from switch_core.db.session_scope import tenant_session+from tests.db_buffer import db_buffer_on, say, seed_agent, seed_memberAGENT = "agent-1"ROOM = "room-1"-def _message(addressed: bool, room_id: str = ROOM) -> AgentEvent:[email protected](autouse=True)+async def _agent_rows(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent every event here is queued for, a member of the rooms they are+ queued in, so its rows have one to belong to and the rooms' conversation is+ its to read."""+ await seed_agent(session_factory, AGENT)+ await seed_member(session_factory, AGENT, ROOM)+ await seed_member(session_factory, AGENT, "room-2")+++def _message(+ addressed: bool, room_id: str = ROOM, *, message_id: str = "$m"+) -> AgentEvent:return AgentEvent(type="message",room_id=room_id,@@ -28,7 +65,7 @@ def _message(addressed: bool, room_id: str = ROOM) -> AgentEvent:addressed=addressed,sender="@u:s",sender_name="u",- message_id="$m",+ message_id=message_id,body="hi",timestamp=0,),@@ -59,90 +96,179 @@ def _task_delegate() -> AgentEvent:)-async def test_addressed_message_fans_out_without_draining_room_queue() -> None:- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=True))+def _command() -> AgentEvent:+ return AgentEvent(+ type="command",+ room_id=ROOM,+ payload=CommandPayload(command="reset", user_id="@u:s", user_name="u"),+ )+++async def _keep(buffer: EventBuffer, event: AgentEvent) -> int:+ """Keep one of the agent's own events that stands for no room row here."""+ return await buffer.enqueue(+ TENANT_ZERO_ID, AGENT, event.room_id, event, room_seq=0, message_key=None+ )+++async def _asked(+ buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],+ room_id: str = ROOM,+) -> int:+ """A message addressed to the agent, as its consumer keeps it: the row in+ the room's log, and the agent's own event for that row."""+ row = await say(session_factory, room_id, "hi", sender="@u:s", sender_name="u")+ return await buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT,+ room_id,+ _message(True, room_id, message_id=row.transport_event_id),+ room_seq=row.seq,+ message_key=row.transport_event_id,+ )+++async def _poll_position(+ session_factory: async_sessionmaker[AsyncSession], reader_id: str+) -> Position:+ """Where a legacy poller has got to. It sends no position of its own, so+ the server keeps one for it."""+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:+ position = await session.scalar(+ select(AgentPollPosition.position).where(+ AgentPollPosition.agent_id == AGENT,+ AgentPollPosition.reader_id == reader_id,+ )+ )+ assert position is not None, f"{reader_id} has not polled"+ return dict(position)+++async def test_addressed_message_fans_out_without_draining_room_queue(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ q = db_buffer+ await _asked(q, session_factory)# The notification stream sees it...- notifs = await q.poll_notifications(AGENT, timeout=0, rooms={ROOM})+ notifs = await q.poll_notifications(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM})assert len(notifs) == 1assert notifs[0].type == "message"- # ...and it is STILL waiting in the per-room queue for the session poller.- room_events = await q.poll_room(AGENT, ROOM, timeout=0)+ # ...and it is STILL waiting for the session poller in the room, once: the+ # room's row is the agent's own event, so it is not read again as chatter.+ room_events = await q.poll_room(TENANT_ZERO_ID, AGENT, ROOM, timeout=0)assert len(room_events) == 1+ assert room_events[0].payload.addressed is True-async def test_unaddressed_message_does_not_fan_out() -> None:- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=False))+async def test_unaddressed_message_does_not_fan_out(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ q = db_buffer+ await say(session_factory, ROOM, "hi")- assert await q.poll_notifications(AGENT, timeout=0, rooms={ROOM}) == []- # Still queued per-room (unaddressed chatter is delivered there, just not- # surfaced as a notification).- assert len(await q.poll_room(AGENT, ROOM, timeout=0)) == 1+ assert (+ await q.poll_notifications(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM}) == []+ )+ # Still delivered per room (unaddressed chatter is the room's conversation,+ # read from its log by the session poller, just not surfaced as a+ # notification).+ [chatter] = await q.poll_room(TENANT_ZERO_ID, AGENT, ROOM, timeout=0)+ assert chatter.payload.addressed is False-async def test_task_event_fans_out() -> None:- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _task_delegate())- notifs = await q.poll_notifications(AGENT, timeout=0, rooms={ROOM})+async def test_task_event_fans_out(db_buffer: EventBuffer) -> None:+ q = db_buffer+ await _keep(q, _task_delegate())+ notifs = await q.poll_notifications(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM})assert len(notifs) == 1assert notifs[0].type == "task_delegate"-async def test_room_join_fans_out_only_when_listening() -> None:- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _room_join(listening=False))- assert await q.poll_notifications(AGENT, timeout=0, rooms={ROOM}) == []+async def test_room_join_fans_out_only_when_listening(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """An arrival the agent does not listen for is left in the room's log, the+ conversation a session reads; one it listens for is its own event."""+ q = db_buffer+ await say(+ session_factory,+ ROOM,+ "",+ sender="@u:s",+ sender_name="u",+ event_type="m.room.member",+ content={"membership": "join"},+ )+ assert (+ await q.poll_notifications(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM}) == []+ )+ [arrival] = await q.poll_room(TENANT_ZERO_ID, AGENT, ROOM, timeout=0)+ assert arrival.type == "room_join"+ assert arrival.payload.listening is False- q.enqueue(AGENT, ROOM, _room_join(listening=True))- notifs = await q.poll_notifications(AGENT, timeout=0, rooms={ROOM})+ await _keep(q, _room_join(listening=True))+ notifs = await q.poll_notifications(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM})assert len(notifs) == 1assert notifs[0].type == "room_join"-async def test_polling_everything_can_be_limited_to_the_rooms_given() -> None:+async def test_polling_everything_can_be_limited_to_the_rooms_given(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""The buffer is keyed by agent and knows nothing about who is in what.An event queued while the agent was a member stays queued after it isremoved, so the caller passes the rooms it is in now and that is what- keeps the event from being handed over.+ keeps the event from being handed over. The same rooms are the only ones+ whose conversation is read."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=False))- q.enqueue(AGENT, "room-2", _message(addressed=False, room_id="room-2"))+ q = db_buffer+ await _asked(q, session_factory, ROOM)+ await _asked(q, session_factory, "room-2")+ await say(session_factory, ROOM, "chatter")- polled = await q.poll(AGENT, timeout=0, rooms={"room-2"})+ polled = await q.poll(TENANT_ZERO_ID, AGENT, timeout=0, rooms={"room-2"})assert [event.room_id for event in polled] == ["room-2"]-async def test_polling_with_no_rooms_at_all_returns_nothing() -> None:+async def test_polling_with_no_rooms_at_all_returns_nothing(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""An agent in no rooms is not a caller asking for every room."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=False))+ q = db_buffer+ await _asked(q, session_factory)+ await say(session_factory, ROOM, "chatter")- assert await q.poll(AGENT, timeout=0, rooms=set()) == []+ assert await q.poll(TENANT_ZERO_ID, AGENT, timeout=0, rooms=set()) == []-async def test_notifications_are_limited_to_the_rooms_given_too() -> None:+async def test_notifications_are_limited_to_the_rooms_given_too(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""The notification stream is the one carrying addressed messages.Filtering the all-rooms poll and not this one would leave the leak open onthe more sensitive of the two: an agent removed from a room would stopseeing its chatter and go on being handed everything said *to* it there."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=True))- q.enqueue(AGENT, "room-2", _message(addressed=True, room_id="room-2"))+ q = db_buffer+ await _asked(q, session_factory, ROOM)+ await _asked(q, session_factory, "room-2")- polled = await q.poll_notifications(AGENT, timeout=0, rooms={"room-2"})+ polled = await q.poll_notifications(+ TENANT_ZERO_ID, AGENT, timeout=0, rooms={"room-2"}+ )assert [event.room_id for event in polled] == ["room-2"]-async def test_dropping_a_room_forgets_what_it_still_held() -> None:+async def test_dropping_a_room_forgets_what_it_still_held(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""What the transport stops reading, the buffer has to stop holding.Dropping the subscription only governs what has not been read yet. An@@ -150,104 +276,202 @@ async def test_dropping_a_room_forgets_what_it_still_held() -> None:and to an SSE reader resuming from an old cursor for the whole retentionwindow."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=True))- q.enqueue(AGENT, "room-2", _message(addressed=True, room_id="room-2"))+ q = db_buffer+ await _asked(q, session_factory, ROOM)+ await _asked(q, session_factory, "room-2")- q.drop_room(AGENT, ROOM)+ await q.drop_room(TENANT_ZERO_ID, AGENT, ROOM)# Gone from the low-level read every reader is built on, filter or no# filter — which is what closes it for the stream, the one reader with no# membership of its own to apply.- assert [item.room_id for item in q.read_from(AGENT, 0)] == ["room-2"]+ assert [item.room_id for item in (await q.read_from(TENANT_ZERO_ID, AGENT, 0))] == [+ "room-2"+ ]-async def test_dropping_a_room_does_not_report_a_gap() -> None:+async def test_dropping_a_room_does_not_report_a_gap(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""A reader that skips the dropped events has missed nothing it was owed.Saying otherwise would send an agent off to re-read the context of a roomit is no longer in."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=True))- q.enqueue(AGENT, "room-2", _message(addressed=True, room_id="room-2"))+ q = db_buffer+ await _asked(q, session_factory, ROOM)+ await _asked(q, session_factory, "room-2")- q.drop_room(AGENT, ROOM)+ await q.drop_room(TENANT_ZERO_ID, AGENT, ROOM)- assert not q.has_gap_before(AGENT, 0)- assert [item.seq for item in q.read_from(AGENT, 0)] == [2]+ assert await q.rooms_dropped_after(TENANT_ZERO_ID, AGENT, 0) == ()+ assert [item.seq for item in (await q.read_from(TENANT_ZERO_ID, AGENT, 0))] == [2]-async def test_the_cursor_advances_past_what_the_reader_can_never_want() -> None:- """Unaddressed chatter is excluded on a property of the event, not on who- the agent is, so the notification reader will never want it and the cursor- is free to move past it. Left behind it, the cursor parks below the head- until retention trims it and the next read reports a gap that never was.+async def test_the_cursor_advances_past_what_the_reader_can_never_want(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """A command is excluded on a property of the event, not on who the agent+ is, so the notification reader will never want it and its position is free+ to move past it. Left behind it, the position parks below the head until+ retention trims it and the next read reports a gap that never was."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=False))- q.enqueue(AGENT, ROOM, _message(addressed=False))+ q = db_buffer+ await _keep(q, _command())+ await _keep(q, _command())- assert await q.poll_notifications(AGENT, timeout=0, rooms={ROOM}) == []- assert q._cursors[AGENT]["legacy:notifications"] == 2+ assert (+ await q.poll_notifications(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM}) == []+ )+ assert (await _poll_position(session_factory, "legacy:notifications"))[+ OWN_EVENTS+ ] == 2-async def test_the_cursor_does_not_advance_past_a_room_joined_later() -> None:+async def test_the_cursor_does_not_advance_past_a_room_joined_later(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""Membership is not a property of the event, so it can change.A poll reads the agent's rooms once; anything arriving for a room it joinswhile that poll is parked is filtered against the older set. Confirming- past it would put the cursor beyond an event the agent is entitled to, and- no later poll would ever reach it again — it would sit in the buffer,+ past it would put the position beyond an event the agent is entitled to,+ and no later poll would ever reach it again: it would sit in the buffer,retained and unreachable, until it aged out."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, "room-2", _message(addressed=True, room_id="room-2"))+ q = db_buffer+ await _asked(q, session_factory, "room-2")- assert await q.poll(AGENT, timeout=0, rooms={ROOM}) == []- assert q._cursors[AGENT]["legacy:all"] == 0+ assert await q.poll(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM}) == []+ assert (await _poll_position(session_factory, "legacy:all"))[OWN_EVENTS] == 0- polled = await q.poll(AGENT, timeout=0, rooms={ROOM, "room-2"})+ polled = await q.poll(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM, "room-2"})assert [event.room_id for event in polled] == ["room-2"]-async def test_the_notification_stream_also_survives_a_room_joined_later() -> None:+async def test_the_notification_stream_also_survives_a_room_joined_later(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""The same rule on the stream carrying what was said *to* the agent."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, "room-2", _message(addressed=True, room_id="room-2"))+ q = db_buffer+ await _asked(q, session_factory, "room-2")- assert await q.poll_notifications(AGENT, timeout=0, rooms={ROOM}) == []- polled = await q.poll_notifications(AGENT, timeout=0, rooms={ROOM, "room-2"})+ assert (+ await q.poll_notifications(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM}) == []+ )+ polled = await q.poll_notifications(+ TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM, "room-2"}+ )assert [event.room_id for event in polled] == ["room-2"]-async def test_a_room_reader_still_advances_past_other_rooms() -> None:+async def test_a_room_reader_still_advances_past_other_rooms(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""`poll_room`'s filter is the reader's own scope, not a membership snapshot.`legacy:room:X` will never want room Y whatever the agent joins later, so- parking its cursor behind Y's events would strand it for no gain.+ parking its position behind Y's events would strand it for no gain."""- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, "room-2", _message(addressed=True, room_id="room-2"))- q.enqueue(AGENT, ROOM, _message(addressed=True))+ q = db_buffer+ await _asked(q, session_factory, "room-2")+ await _asked(q, session_factory, ROOM)- polled = await q.poll_room(AGENT, ROOM, timeout=0)+ polled = await q.poll_room(TENANT_ZERO_ID, AGENT, ROOM, timeout=0)assert [event.room_id for event in polled] == [ROOM]- assert q._cursors[AGENT][f"legacy:room:{ROOM}"] == 2+ assert (await _poll_position(session_factory, f"legacy:room:{ROOM}"))[+ OWN_EVENTS+ ] == 2-async def test_remove_clears_notification_queue() -> None:- q = EventBuffer(sequence_base=0)- q.enqueue(AGENT, ROOM, _message(addressed=True))+async def test_deleting_the_agent_clears_its_notifications(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """The rows belong to the agent's own row, so they go when it does.++ `remove` only forgets what this process holds; the agent's events are its+ rows, and the foreign key is what takes them away.+ """+ q = db_buffer+ await _asked(q, session_factory)q.remove(AGENT)- assert await q.poll_notifications(AGENT, timeout=0, rooms={ROOM}) == []+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:+ await session.execute(delete(Agent).where(Agent.id == AGENT))+ await session.commit()+ assert await q.read_from(TENANT_ZERO_ID, AGENT, 0) == []-def test_removing_agent_does_not_reuse_event_sequences():- buffer = EventBuffer(sequence_base=1 << 32)- first = buffer.enqueue(AGENT, ROOM, _message(True))++async def test_removing_agent_does_not_reuse_event_sequences(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ buffer = db_buffer_on(session_factory, sequence_base=1 << 32)+ first = await _keep(buffer, _message(True))buffer.remove(AGENT)- second = buffer.enqueue(AGENT, ROOM, _message(True))+ second = await _keep(buffer, _message(True))assert second > firstassert second < 2**53+++def test_ticket_ids_sit_above_every_own_event_number() -> None:+ """A client that holds one number sends back either an own event number or+ a ticket id, and the server tells them apart by size. The largest own event+ number, four billion events into the numbering of an agent first seen at+ the last boot the boot sequence allows, is below the first ticket id, and+ the last ticket id is still an integer a JavaScript client holds exactly."""+ largest_own_event = (AGENT_EVENT_BOOT_MAX << 32) + 2**32 - 1++ assert largest_own_event < TICKET_FLOOR+ assert TICKET_CEILING == 2**53 - 1+++async def test_overlapping_polls_never_move_a_reader_back(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """Two polls of the same reader can overlap, and the one that finishes+ last may have read less. Its save is merged with the stored position,+ source by source, so the reader is never moved back to events it was+ already sent."""+ room = f"r:{ROOM}"+ await db_buffer._save_poll_position(+ TENANT_ZERO_ID, AGENT, "legacy:all", {OWN_EVENTS: 5, room: 7}+ )+ await db_buffer._save_poll_position(+ TENANT_ZERO_ID, AGENT, "legacy:all", {OWN_EVENTS: 3, room: 9, "r:other": 1}+ )++ assert await _poll_position(session_factory, "legacy:all") == {+ OWN_EVENTS: 5,+ room: 9,+ "r:other": 1,+ }+++async def test_a_write_that_fails_on_the_connection_is_retried(+ db_buffer: EventBuffer, monkeypatch: pytest.MonkeyPatch+) -> None:+ """The consumer has moved past the room row by the time it stores the+ agent's own event, so a write lost to a dropped connection or a pool+ timeout would never be made. It is retried, and stored once."""+ real = event_buffer.tenant_session+ failures = [OperationalError("INSERT", {}, ConnectionError("connection reset"))]++ @asynccontextmanager+ async def flaky(factory: object, tenant_id: str) -> AsyncIterator[AsyncSession]:+ if failures:+ raise failures.pop()+ async with real(factory, tenant_id) as session:+ yield session++ monkeypatch.setattr(event_buffer, "tenant_session", flaky)+ monkeypatch.setattr(event_buffer, "ENQUEUE_RETRY_DELAYS", (0.0, 0.0, 0.0))+ seq = await db_buffer.enqueue(+ TENANT_ZERO_ID, AGENT, ROOM, _message(True), room_seq=0, message_key=None+ )+ monkeypatch.undo()++ assert not failures+ assert [+ item.seq for item in await db_buffer.read_from(TENANT_ZERO_ID, AGENT, 0)+ ] == [seq]diff --git a/core/tests/switch_core/bridges/agent/protocol/test_event_buffer_cost.py b/core/tests/switch_core/bridges/agent/protocol/test_event_buffer_cost.pyindex 444d1c50f..5008b7bc0 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_event_buffer_cost.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_event_buffer_cost.py@@ -1,33 +1,39 @@-"""What the agent event buffer costs per delivered event, and what it logs.+"""What the agent event buffer records about its reads and what it drops.-An agent past the cap drops an event on every enqueue, and used to log a-warning on every one: a line per delivered message for an agent that had read-everything. The warning is now at most once per interval per agent, while the-drop counter and the gap a reader is told about stay exact.+Events used to sit in a capped in-memory deque, and an agent past the cap lost+one on every enqueue, with a warning rate-limited per agent. The cap and the+warning are gone: rows are deleted only by `expire`, and each deletion is+counted exactly and leaves a gap a reader is told about.-The buffer answers reads by walking the agent's retained events, so the walk is-measured: how many events, and how long, per call.+Reads are indexed queries now rather than walks of the deque, so what is+measured is how many events each call returned, and how long it took."""from __future__ import annotations-import loggingfrom collections.abc import Iteratorimport pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker-from switch_core.bridges.agent.protocol import event_buffer as buffer_modulefrom switch_core.bridges.agent.protocol.event_buffer import (- OVERFLOW_WARNING_INTERVAL_SECONDS,CursorExpiredError,EventBuffer,Reader,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS, room_sourcefrom switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.observability.metrics import MetricsRegistry, install, uninstallfrom switch_core.observability.otlp import HistogramPoint+from tests.db_buffer import age_events, say, seed_agent, seed_member-_LOGGER = "switch_core.bridges.agent.protocol.event_buffer"+[email protected](autouse=True)+async def _agent_rows(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agents events are queued for here, so their rows have one to belong to."""+ await seed_agent(session_factory, "agent-1")+ await seed_agent(session_factory, "agent-2")@pytest.fixture@@ -38,42 +44,27 @@ def registry() -> Iterator[MetricsRegistry]:uninstall()-class _Clock:- def __init__(self) -> None:- self.now = 1000.0-- def __call__(self) -> float:- return self.now---def clock(monkeypatch: pytest.MonkeyPatch) -> _Clock:- clock = _Clock()- monkeypatch.setattr(buffer_module.time, "monotonic", clock)- return clock---def _event(index: int, *, addressed: bool = True) -> AgentEvent:+def _event(index: int, *, message_id: str | None = None) -> AgentEvent:return AgentEvent(type="message",room_id="room-1",payload=MessagePayload(- message_id=f"m{index}",+ message_id=message_id or f"m{index}",sender="@someone:test",sender_name="someone",body=f"hello {index}",- addressed=addressed,+ addressed=True,timestamp=index,),)-def _overflow_warnings(caplog: pytest.LogCaptureFixture) -> list[logging.LogRecord]:- return [- record- for record in caplog.records- if record.name == _LOGGER and "exceeded" in record.getMessage()- ]+async def _keep(buffer: EventBuffer, agent_id: str, event: AgentEvent) -> int:+ """Keep one of an agent's own events. What is measured is the agent's own+ sequence, so the room row it stands for is left out."""+ return await buffer.enqueue(+ TENANT_ZERO_ID, agent_id, "room-1", event, room_seq=0, message_key=None+ )def _dropped(registry: MetricsRegistry) -> dict[tuple, float]:@@ -95,143 +86,120 @@ def _histograms(registry: MetricsRegistry, name: str) -> dict[str, HistogramPoinreturn {point.attributes["operation"]: point for point in payload.histograms}-def test_overflow_warns_once_per_interval_per_agent(clock, registry, caplog):- caplog.set_level(logging.WARNING, logger=_LOGGER)- buffer = EventBuffer(- max_events_per_agent=3, retention_seconds=3600, sequence_base=0- )-- for index in range(50):- buffer.enqueue("agent-1", "room-1", _event(index))- clock.now += 0.1-- # 47 drops inside five seconds: one line, not 47.- assert len(_overflow_warnings(caplog)) == 1- assert _dropped(registry) == {(("reason", "overflow"),): 47.0}---def test_overflow_warning_resumes_after_the_interval_with_a_count(- clock, registry, caplog+async def test_expiry_counts_every_drop_and_leaves_the_gap_for_readers(+ registry, db_buffer: EventBuffer, session_factory):- caplog.set_level(logging.WARNING, logger=_LOGGER)- buffer = EventBuffer(- max_events_per_agent=3, retention_seconds=3600, sequence_base=0- )-- for index in range(4):- buffer.enqueue("agent-1", "room-1", _event(index))- for index in range(4, 14):- clock.now += 1- buffer.enqueue("agent-1", "room-1", _event(index))- clock.now += OVERFLOW_WARNING_INTERVAL_SECONDS- buffer.enqueue("agent-1", "room-1", _event(14))-- warnings = _overflow_warnings(caplog)- assert len(warnings) == 2- # The ten drops between the two lines are counted into the second.- assert "plus 10 dropped since the last warning" in warnings[1].getMessage()- assert _dropped(registry) == {(("reason", "overflow"),): 12.0}---def test_overflow_warning_is_per_agent(clock, caplog):- caplog.set_level(logging.WARNING, logger=_LOGGER)- buffer = EventBuffer(- max_events_per_agent=1, retention_seconds=3600, sequence_base=0- )-- for index in range(5):- buffer.enqueue("agent-1", "room-1", _event(index))- buffer.enqueue("agent-2", "room-1", _event(index))-- warned = sorted(- record.getMessage().split()[1] for record in _overflow_warnings(caplog)- )- assert warned == ["agent=agent-1", "agent=agent-2"]---def test_a_quiet_warning_still_leaves_the_gap_for_readers(clock, caplog):- caplog.set_level(logging.WARNING, logger=_LOGGER)- buffer = EventBuffer(- max_events_per_agent=3, retention_seconds=3600, sequence_base=0- )-- for index in range(20):- buffer.enqueue("agent-1", "room-1", _event(index))-- assert len(_overflow_warnings(caplog)) == 1- # A reader from the start is told about every drop, logged or not.+ buffer = db_buffer+ for index in range(17):+ await _keep(buffer, "agent-1", _event(index))+ await _keep(buffer, "agent-2", _event(0))+ await age_events(session_factory, "agent-1", seconds=2 * 3600)+ await age_events(session_factory, "agent-2", seconds=2 * 3600)++ assert await buffer.expire(TENANT_ZERO_ID) == 18+ for index in range(17, 20):+ await _keep(buffer, "agent-1", _event(index))++ # Every deleted row is counted, across agents, under the retention reason.+ assert _dropped(registry) == {(("reason", "retention"),): 18.0}+ # A reader from the start is told about every drop.with pytest.raises(CursorExpiredError) as exc:- buffer.read_from("agent-1", 0)+ await buffer.read_from(TENANT_ZERO_ID, "agent-1", 0)assert exc.value.oldest == 18assert exc.value.rooms == ("room-1",)- assert [item.seq for item in buffer.read_from("agent-1", 17)] == [18, 19, 20]+ assert [+ item.seq for item in await buffer.read_from(TENANT_ZERO_ID, "agent-1", 17)+ ] == [18, 19, 20]-def test_removing_an_agent_forgets_its_warning_state(clock, caplog):- caplog.set_level(logging.WARNING, logger=_LOGGER)- buffer = EventBuffer(- max_events_per_agent=1, retention_seconds=3600, sequence_base=0- )+async def test_an_expiry_with_nothing_old_enough_drops_and_counts_nothing(+ registry, db_buffer: EventBuffer+):+ buffer = db_buffer+ await _keep(buffer, "agent-1", _event(0))- for index in range(3):- buffer.enqueue("agent-1", "room-1", _event(index))- buffer.remove("agent-1")- for index in range(3):- buffer.enqueue("agent-1", "room-1", _event(index))+ assert await buffer.expire(TENANT_ZERO_ID) == 0- assert len(_overflow_warnings(caplog)) == 2+ assert _dropped(registry) == {}+ assert await buffer.rooms_dropped_after(TENANT_ZERO_ID, "agent-1", 0) == ()-def test_a_read_records_how_many_events_it_walked(registry):- buffer = EventBuffer(- max_events_per_agent=100, retention_seconds=3600, sequence_base=0- )+async def test_a_read_records_how_many_events_it_returned(+ registry, db_buffer: EventBuffer+):+ buffer = db_bufferfor index in range(10):- buffer.enqueue("agent-1", "room-1", _event(index))+ await _keep(buffer, "agent-1", _event(index))- buffer.read_from("agent-1", 0)- # Stopping at the limit walks only as far as the limit was reached.- buffer.read_from("agent-1", 0, limit=3)+ await buffer.read_from(TENANT_ZERO_ID, "agent-1", 0)+ # A limited read is bounded by its limit, not by what is retained.+ await buffer.read_from(TENANT_ZERO_ID, "agent-1", 0, limit=3)scanned = _histograms(registry, "switch.agent.buffer.scanned")["read"]assert scanned.count == 2assert scanned.total == 13.0-def test_a_read_and_an_unread_count_record_their_duration(registry):- buffer = EventBuffer(- max_events_per_agent=100, retention_seconds=3600, sequence_base=0- )+async def test_a_read_and_an_unread_count_record_their_duration(+ registry, db_buffer: EventBuffer, session_factory+):+ buffer = db_buffer+ await seed_member(session_factory, "agent-1", "room-1")reader = Reader(id="session-1", is_session=True)- buffer.caught_up("agent-1", reader, "room-1", 0, arrived_on=None)- for index in range(4):- buffer.enqueue("agent-1", "room-1", _event(index, addressed=index == 3))+ await buffer.caught_up(TENANT_ZERO_ID, "agent-1", reader, "room-1", 0, None)+ # Three messages of conversation, then one addressed to the agent: a row in+ # the room like the others, and the agent's own event besides.+ for index in range(3):+ await say(session_factory, "room-1", f"hello {index}")+ asked = await say(session_factory, "room-1", "hello 3")+ await buffer.enqueue(+ TENANT_ZERO_ID,+ "agent-1",+ "room-1",+ _event(3, message_id=asked.transport_event_id),+ room_seq=asked.seq,+ message_key=asked.transport_event_id,+ )- buffer.read_from("agent-1", 0)- assert buffer.unread("agent-1", "room-1", 4).count == 3+ await buffer.read(+ TENANT_ZERO_ID,+ "agent-1",+ {OWN_EVENTS: 0, room_source("room-1"): 0},+ conversation_rooms={"room-1"},+ limit=200,+ )+ assert (+ await buffer.unread(TENANT_ZERO_ID, "agent-1", "room-1", asked.seq)+ ).count == 3collected = registry.collect()durations = next(p for p in collected if p.name == "switch.agent.buffer.scan.duration")scanned = next(p for p in collected if p.name == "switch.agent.buffer.scanned")+ # A read is two scans: the agent's own events, and the rooms' conversation.assert {p.attributes["operation"]: p.count for p in durations.histograms} == {- "read": 1,+ "read": 2,"unread": 1,}assert all(p.total >= 0 for p in durations.histograms)+ # Each scan of a read records the rows it returned (one event of the+ # agent's own, three of conversation); an unread count is one query, and+ # records what it counted (the addressed fourth message is not unread).assert {p.attributes["operation"]: p.total for p in scanned.histograms} == {"read": 4.0,- "unread": 4.0,+ "unread": 3.0,}-def test_an_unread_count_with_nothing_to_count_records_no_scan(registry):- buffer = EventBuffer(sequence_base=0)- buffer.enqueue("agent-1", "room-1", _event(0))+async def test_an_unread_count_with_nothing_to_count_records_no_scan(+ registry, db_buffer: EventBuffer+):+ buffer = db_buffer+ await _keep(buffer, "agent-1", _event(0))- # No baseline: answered without walking the buffer.- assert buffer.unread("agent-1", "room-1", 1).count is None+ # No baseline: answered without counting the room's log.+ assert (await buffer.unread(TENANT_ZERO_ID, "agent-1", "room-1", 1)).count is Nonenames = {p.name for p in registry.collect()}assert "switch.agent.buffer.scanned" not in namesdiff --git a/core/tests/switch_core/bridges/agent/protocol/test_event_buffer_resume.py b/core/tests/switch_core/bridges/agent/protocol/test_event_buffer_resume.pyindex 75935fd36..a16b8840c 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_event_buffer_resume.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_event_buffer_resume.py@@ -8,24 +8,41 @@ fallen off the end of the buffer is told rather than quietly fast-forwarded.from __future__ import annotationsimport pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.protocol.event_buffer import (+ BufferedEvent,CursorExpiredError,EventBuffer,)-from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.bridges.agent.protocol.types import (+ AgentEvent,+ CommandPayload,+ MessagePayload,+)+from switch_core.db.models import TENANT_ZERO_ID+from tests.db_buffer import age_events, db_buffer_on, say, seed_agent, seed_memberAGENT = "agent-1"ROOM_A = "room-a"ROOM_B = "room-b"-def _message(body: str, *, addressed: bool = False, room: str = ROOM_A) -> AgentEvent:[email protected](autouse=True)+async def _agent_rows(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent every event here is queued for, so its rows have one to belong+ to, and a member of the room the legacy pollers read the conversation of."""+ await seed_agent(session_factory, AGENT)+ await seed_member(session_factory, AGENT, ROOM_A)+++def _message(body: str, *, room: str = ROOM_A) -> AgentEvent:+ """A message addressed to the agent: the kind of message it keeps."""return AgentEvent(type="message",room_id=room,payload=MessagePayload(- addressed=addressed,+ addressed=True,sender="@u:s",sender_name="u",message_id=f"$evt-{body}",@@ -35,181 +52,295 @@ def _message(body: str, *, addressed: bool = False, room: str = ROOM_A) -> Agent)-def _bodies(items: list) -> list[str]:- return [item.event.payload.body for item in items]+def _command(name: str, *, room: str = ROOM_A) -> AgentEvent:+ """One of the agent's own events that is not a notification."""+ return AgentEvent(+ type="command",+ room_id=room,+ payload=CommandPayload(command=name, user_id="@u:s", user_name="u"),+ )+++async def _keep(buf: EventBuffer, event: AgentEvent) -> int:+ """Keep one of the agent's own events. What is under test is the agent's+ sequence, so the room row it stands for is left out."""+ return await buf.enqueue(+ TENANT_ZERO_ID, AGENT, event.room_id, event, room_seq=0, message_key=None+ )+++def _bodies(items: list[BufferedEvent]) -> list[str]:+ """What each event says: a message's body, or a command as it was typed."""+ return [+ f"!{item.event.payload.command}"+ if isinstance(item.event.payload, CommandPayload)+ else item.event.payload.body+ for item in items+ ]-def test_sequence_numbers_are_monotonic_per_agent() -> None:- buf = EventBuffer(sequence_base=0)- assert buf.enqueue(AGENT, ROOM_A, _message("one")) == 1- assert buf.enqueue(AGENT, ROOM_B, _message("two", room=ROOM_B)) == 2- assert buf.enqueue(AGENT, ROOM_A, _message("three")) == 3- assert buf.head(AGENT) == 3+async def test_sequence_numbers_are_monotonic_per_agent(db_buffer: EventBuffer) -> None:+ buf = db_buffer+ assert await _keep(buf, _message("one")) == 1+ assert await _keep(buf, _message("two", room=ROOM_B)) == 2+ assert await _keep(buf, _message("three")) == 3+ assert await buf.head(TENANT_ZERO_ID, AGENT) == 3-def test_reading_does_not_consume() -> None:- buf = EventBuffer(sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("one"))+async def test_reading_does_not_consume(db_buffer: EventBuffer) -> None:+ buf = db_buffer+ await _keep(buf, _message("one"))- assert _bodies(buf.read_from(AGENT, 0)) == ["one"]+ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, 0)) == ["one"]# The same event is still there for a second, independent reader — this is# what removes the need for DISABLE_POLL.- assert _bodies(buf.read_from(AGENT, 0)) == ["one"]+ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, 0)) == ["one"]-def test_resume_returns_only_events_after_the_cursor() -> None:- buf = EventBuffer(sequence_base=0)+async def test_resume_returns_only_events_after_the_cursor(+ db_buffer: EventBuffer,+) -> None:+ buf = db_bufferfor body in ("one", "two", "three"):- buf.enqueue(AGENT, ROOM_A, _message(body))+ await _keep(buf, _message(body))- assert _bodies(buf.read_from(AGENT, 1)) == ["two", "three"]- assert _bodies(buf.read_from(AGENT, 3)) == []+ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, 1)) == ["two", "three"]+ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, 3)) == []-def test_events_missed_while_disconnected_are_replayed_on_resume() -> None:- buf = EventBuffer(sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("before"))- seen = buf.read_from(AGENT, 0)+async def test_events_missed_while_disconnected_are_replayed_on_resume(+ db_buffer: EventBuffer,+) -> None:+ buf = db_buffer+ await _keep(buf, _message("before"))+ seen = await buf.read_from(TENANT_ZERO_ID, AGENT, 0)cursor = seen[-1].seq# Client is gone; events keep arriving.- buf.enqueue(AGENT, ROOM_A, _message("during-1"))- buf.enqueue(AGENT, ROOM_A, _message("during-2"))+ await _keep(buf, _message("during-1"))+ await _keep(buf, _message("during-2"))- assert _bodies(buf.read_from(AGENT, cursor)) == ["during-1", "during-2"]+ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, cursor)) == [+ "during-1",+ "during-2",+ ]-def test_room_and_notifiable_filters_are_independent() -> None:- buf = EventBuffer(sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("a-chatter"))- buf.enqueue(AGENT, ROOM_A, _message("a-addressed", addressed=True))- buf.enqueue(AGENT, ROOM_B, _message("b-addressed", addressed=True, room=ROOM_B))+async def test_room_and_notifiable_filters_are_independent(+ db_buffer: EventBuffer,+) -> None:+ buf = db_buffer+ await _keep(buf, _command("reset"))+ await _keep(buf, _message("a-addressed"))+ await _keep(buf, _message("b-addressed", room=ROOM_B))# A session: one room, everything in it.- assert _bodies(buf.read_from(AGENT, 0, rooms={ROOM_A})) == [- "a-chatter",+ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, 0, rooms={ROOM_A})) == [+ "!reset","a-addressed",]# A supervising connection: every room, addressed only.- assert _bodies(buf.read_from(AGENT, 0, notifiable_only=True)) == [+ assert _bodies(+ await buf.read_from(TENANT_ZERO_ID, AGENT, 0, notifiable_only=True)+ ) == ["a-addressed","b-addressed",]# Both dials at once.- assert _bodies(buf.read_from(AGENT, 0, rooms={ROOM_B}, notifiable_only=True)) == [- "b-addressed"- ]-+ assert _bodies(+ await buf.read_from(+ TENANT_ZERO_ID, AGENT, 0, rooms={ROOM_B}, notifiable_only=True+ )+ ) == ["b-addressed"]-def test_overflow_drops_oldest_and_flags_a_gap() -> None:- buf = EventBuffer(max_events_per_agent=3, sequence_base=0)- for body in ("one", "two", "three", "four"):- buf.enqueue(AGENT, ROOM_A, _message(body))- assert _bodies(buf.read_from(AGENT, 1)) == ["two", "three", "four"]- assert buf.has_gap_before(AGENT, 0)- assert not buf.has_gap_before(AGENT, 1)+async def test_expiry_drops_the_oldest_and_flags_a_gap(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ buf = db_buffer+ await _keep(buf, _message("one"))+ await age_events(session_factory, AGENT, seconds=2 * 3600)+ await buf.expire(TENANT_ZERO_ID)+ for body in ("two", "three", "four"):+ await _keep(buf, _message(body))++ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, 1)) == [+ "two",+ "three",+ "four",+ ]+ assert await buf.rooms_dropped_after(TENANT_ZERO_ID, AGENT, 0) == (ROOM_A,)+ assert await buf.rooms_dropped_after(TENANT_ZERO_ID, AGENT, 1) == ()-def test_resuming_from_an_expired_cursor_raises_rather_than_skipping() -> None:- buf = EventBuffer(max_events_per_agent=2, sequence_base=0)- for body in ("one", "two", "three"):- buf.enqueue(AGENT, ROOM_A, _message(body))+async def test_resuming_from_an_expired_cursor_raises_rather_than_skipping(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ buf = db_buffer+ await _keep(buf, _message("one"))+ await age_events(session_factory, AGENT, seconds=2 * 3600)+ await buf.expire(TENANT_ZERO_ID)+ for body in ("two", "three"):+ await _keep(buf, _message(body))with pytest.raises(CursorExpiredError) as excinfo:- buf.read_from(AGENT, 0)+ await buf.read_from(TENANT_ZERO_ID, AGENT, 0)assert excinfo.value.requested == 0assert excinfo.value.oldest == 2+ assert excinfo.value.rooms == (ROOM_A,)-def test_retention_window_expires_events_and_flags_a_gap(- monkeypatch: pytest.MonkeyPatch,+async def test_retention_window_expires_events_and_flags_a_gap(+ session_factory: async_sessionmaker[AsyncSession],) -> None:- clock = {"now": 1000.0}- monkeypatch.setattr(- "switch_core.bridges.agent.protocol.event_buffer.time.monotonic",- lambda: clock["now"],- )+ """Only what is older than the window goes: an event inside it survives+ the same sweep."""+ buf = db_buffer_on(session_factory, retention_seconds=60)+ await _keep(buf, _message("old"))+ await age_events(session_factory, AGENT, seconds=61)+ await _keep(buf, _message("new"))- buf = EventBuffer(retention_seconds=60, sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("old"))+ assert await buf.expire(TENANT_ZERO_ID) == 1- clock["now"] += 61- buf.enqueue(AGENT, ROOM_A, _message("new"))+ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, 1)) == ["new"]+ with pytest.raises(CursorExpiredError):+ await buf.read_from(TENANT_ZERO_ID, AGENT, 0)+++async def test_a_quiet_agent_stops_serving_an_event_when_its_window_ends(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """Expiry sweeps the tenant rather than riding on an append, so an agent+ nothing else is queued for loses its old events all the same."""+ buf = db_buffer_on(session_factory, retention_seconds=60)+ await _keep(buf, _message("only"))+ await age_events(session_factory, AGENT, seconds=61)++ await buf.expire(TENANT_ZERO_ID)- assert _bodies(buf.read_from(AGENT, 1)) == ["new"]+ assert await buf.read_from(TENANT_ZERO_ID, AGENT, 1) == []with pytest.raises(CursorExpiredError):- buf.read_from(AGENT, 0)+ await buf.read_from(TENANT_ZERO_ID, AGENT, 0)-def test_a_quiet_agent_stops_serving_an_event_when_its_window_ends(- monkeypatch: pytest.MonkeyPatch,+async def test_a_reader_resumes_past_everything_expiry_deleted(+ session_factory: async_sessionmaker[AsyncSession],) -> None:- """Nothing else appends for this agent, so nothing else can expire it."""- clock = {"now": 1000.0}- monkeypatch.setattr(- "switch_core.bridges.agent.protocol.event_buffer.time.monotonic",- lambda: clock["now"],- )+ """When retention has deleted all of the agent's own events, there is no+ oldest one to resume before. The error names a place past every deleted+ number, and a reader moved there reads nothing rather than being told+ about the same deletion again."""+ buf = db_buffer_on(session_factory, retention_seconds=60)+ first = await _keep(buf, _message("one"))+ last = await _keep(buf, _message("two"))+ await age_events(session_factory, AGENT, seconds=61)+ await buf.expire(TENANT_ZERO_ID)- buf = EventBuffer(retention_seconds=60, sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("only"))+ with pytest.raises(CursorExpiredError) as excinfo:+ await buf.read_from(TENANT_ZERO_ID, AGENT, first - 1)- clock["now"] += 61+ assert excinfo.value.oldest == 0+ assert excinfo.value.resume_after == last+ assert await buf.read_from(TENANT_ZERO_ID, AGENT, excinfo.value.resume_after) == []- assert buf.read_from(AGENT, 1) == []- with pytest.raises(CursorExpiredError):- buf.read_from(AGENT, 0)++async def test_a_long_poll_after_everything_expired_returns_nothing(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """A long-polling client cannot be told about a gap. Once retention has+ deleted everything after its place, its poll moves past what was deleted+ and returns what is left, here nothing, instead of failing."""+ buf = db_buffer_on(session_factory, retention_seconds=60)+ assert await buf.poll(TENANT_ZERO_ID, AGENT, rooms={ROOM_A}, timeout=0) == []+ await _keep(buf, _message("only"))+ await age_events(session_factory, AGENT, seconds=61)+ await buf.expire(TENANT_ZERO_ID)++ assert await buf.poll(TENANT_ZERO_ID, AGENT, rooms={ROOM_A}, timeout=0) == []-def test_confirming_does_not_discard_events_for_other_readers() -> None:- buf = EventBuffer(sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("one"))+async def test_processes_of_different_boots_number_an_agent_alike(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """A process reads the head of an agent that has no own events yet, and a+ process started at an earlier boot then writes the agent's first one. The+ event is numbered after the head the first process reported, so a reader+ placed at that head still receives it."""+ newer = db_buffer_on(session_factory, sequence_base=11 << 32)+ older = db_buffer_on(session_factory, sequence_base=10 << 32)++ head = await newer.head(TENANT_ZERO_ID, AGENT)+ first = await _keep(older, _message("first"))++ assert first == head + 1+ assert _bodies(await newer.read_from(TENANT_ZERO_ID, AGENT, head)) == ["first"]- buf.confirm(AGENT, "reader-a", 1)- # A reader that arrives afterwards still sees it: retention is by age and- # cap, not by what someone else has consumed.- assert _bodies(buf.read_from(AGENT, 0)) == ["one"]+async def test_consuming_does_not_discard_events_for_other_readers(+ db_buffer: EventBuffer,+) -> None:+ buf = db_buffer+ await _keep(buf, _message("one"))+ # A legacy poller takes it, and the position kept for it moves past it.+ assert len(await buf.poll_room(TENANT_ZERO_ID, AGENT, ROOM_A, timeout=0)) == 1-def test_confirm_never_rewinds() -> None:- buf = EventBuffer(sequence_base=0)- buf.register_reader(AGENT, "reader-a", 0)- buf.confirm(AGENT, "reader-a", 5)- buf.confirm(AGENT, "reader-a", 2)- assert buf._cursors[AGENT]["reader-a"] == 5+ # A reader that arrives afterwards still sees it: retention is by age,+ # not by what someone else has consumed.+ assert _bodies(await buf.read_from(TENANT_ZERO_ID, AGENT, 0)) == ["one"]-async def test_legacy_pollers_no_longer_steal_from_each_other() -> None:- buf = EventBuffer(sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("hello", addressed=True))+async def test_legacy_pollers_no_longer_steal_from_each_other(+ db_buffer: EventBuffer,+) -> None:+ buf = db_buffer+ await _keep(buf, _message("hello"))- room = await buf.poll_room(AGENT, ROOM_A, timeout=0)- notif = await buf.poll_notifications(AGENT, timeout=0, rooms={ROOM_A})- every = await buf.poll(AGENT, timeout=0, rooms={ROOM_A})+ room = await buf.poll_room(TENANT_ZERO_ID, AGENT, ROOM_A, timeout=0)+ notif = await buf.poll_notifications(+ TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM_A}+ )+ every = await buf.poll(TENANT_ZERO_ID, AGENT, timeout=0, rooms={ROOM_A})assert [e.payload.body for e in room] == ["hello"]assert [e.payload.body for e in notif] == ["hello"]assert [e.payload.body for e in every] == ["hello"]-async def test_legacy_poller_does_not_see_the_same_event_twice() -> None:- buf = EventBuffer(sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("one"))-- assert len(await buf.poll_room(AGENT, ROOM_A, timeout=0)) == 1- assert await buf.poll_room(AGENT, ROOM_A, timeout=0) == []-- buf.enqueue(AGENT, ROOM_A, _message("two"))- second = await buf.poll_room(AGENT, ROOM_A, timeout=0)+async def test_legacy_poller_does_not_see_the_same_event_twice(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """Neither the conversation nor the agent's own events: the position kept+ for the poller moves past both, and an addressed message, which is both a+ row in the room and the agent's own event, comes once."""+ buf = db_buffer+ await say(session_factory, ROOM_A, "one")++ assert len(await buf.poll_room(TENANT_ZERO_ID, AGENT, ROOM_A, timeout=0)) == 1+ assert await buf.poll_room(TENANT_ZERO_ID, AGENT, ROOM_A, timeout=0) == []++ row = await say(session_factory, ROOM_A, "two")+ await buf.enqueue(+ TENANT_ZERO_ID,+ AGENT,+ ROOM_A,+ _message("two"),+ room_seq=row.seq,+ message_key=row.transport_event_id,+ )+ second = await buf.poll_room(TENANT_ZERO_ID, AGENT, ROOM_A, timeout=0)assert [e.payload.body for e in second] == ["two"]-async def test_legacy_poller_receives_events_queued_before_it_polled() -> None:- buf = EventBuffer(sequence_base=0)- buf.enqueue(AGENT, ROOM_A, _message("queued-while-away"))+async def test_legacy_poller_receives_events_queued_before_it_polled(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """A poller seen for the first time reads the room from the start of the+ retention window, not from now: what was said while nobody was polling is+ what its first poll is for."""+ buf = db_buffer+ await say(session_factory, ROOM_A, "queued-while-away")- events = await buf.poll_room(AGENT, ROOM_A, timeout=0)+ events = await buf.poll_room(TENANT_ZERO_ID, AGENT, ROOM_A, timeout=0)assert [e.payload.body for e in events] == ["queued-while-away"]diff --git a/core/tests/switch_core/bridges/agent/protocol/test_poll_events_membership.py b/core/tests/switch_core/bridges/agent/protocol/test_poll_events_membership.pyindex c2036538e..984e778ca 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_poll_events_membership.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_poll_events_membership.py@@ -12,9 +12,10 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload-from switch_core.db.models import Room+from switch_core.db.models import TENANT_ZERO_ID, Roomfrom switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.room_store import RoomStore+from tests.db_buffer import say, seed_memberfrom tests.switch_core.bridges.agent.protocol.registration_harness import (make_owner,make_service,@@ -22,48 +23,75 @@ from tests.switch_core.bridges.agent.protocol.registration_harness import ()-def _message(room_id: str, body: str, *, addressed: bool = False) -> AgentEvent:- return AgentEvent(- type="message",- room_id=room_id,- payload=MessagePayload(- addressed=addressed,- sender="@someone:test",- sender_name="someone",- message_id="$m",- body=body,- timestamp=0,- ),- )--async def _room(session_factory: async_sessionmaker[AsyncSession], name: str, agent_id: str) -> str:+ """A room with the agent in it: a member, and its client in the room's+ conversation."""async with session_factory() as session:room = Room(transport_room_id=f"!{name}:test", name=name, description="")session.add(room)await session.flush()await RoomStore().add_agents(session, room.id, [agent_id])await session.commit()- return room.id+ room_id = room.id+ await seed_member(session_factory, agent_id, room_id)+ return room_id+++async def _ask(+ session_factory: async_sessionmaker[AsyncSession],+ buffer: EventBuffer,+ agent_id: str,+ room_id: str,+ body: str,+) -> None:+ """A message addressed to the agent, as its consumer keeps it: the row in+ the room's log, and the agent's own event for that row."""+ row = await say(session_factory, room_id, body, sender="@someone:test")+ await buffer.enqueue(+ TENANT_ZERO_ID,+ agent_id,+ room_id,+ AgentEvent(+ type="message",+ room_id=room_id,+ payload=MessagePayload(+ addressed=True,+ sender="@someone:test",+ sender_name="someone",+ message_id=row.transport_event_id,+ body=body,+ timestamp=0,+ ),+ ),+ room_seq=row.seq,+ message_key=row.transport_event_id,+ )async def test_events_from_a_room_the_agent_was_removed_from_are_not_returned(session_factory: async_sessionmaker[AsyncSession],+ db_buffer: EventBuffer,) -> None:+ """Neither what was said there nor what was asked of the agent there.++ The all-rooms poll reads the conversation of the rooms it is given as well+ as the agent's own events, so membership has to govern both.+ """svc = make_service(session_factory)svc.room_store = RoomStore() # type: ignore[attr-defined]svc.agent_session_store = AgentSessionStore() # type: ignore[attr-defined]- svc.event_buffer = EventBuffer(sequence_base=0) # type: ignore[attr-defined]+ svc.event_buffer = db_buffer # type: ignore[attr-defined]owner = await make_owner(session_factory)agent_id = await register(svc, "poller", owner)kept = await _room(session_factory, "kept", agent_id)left = await _room(session_factory, "left", agent_id)- svc.event_buffer.enqueue(agent_id, left, _message(left, "said in the old room"))- svc.event_buffer.enqueue(agent_id, kept, _message(kept, "said in this one"))+ await say(session_factory, left, "said in the old room", sender="@someone:test")+ await _ask(session_factory, db_buffer, agent_id, left, "asked in the old room")+ await say(session_factory, kept, "said in this one", sender="@someone:test")async with session_factory() as session:await RoomStore().remove_agents(session, left, [agent_id])@@ -76,6 +104,7 @@ async def test_events_from_a_room_the_agent_was_removed_from_are_not_returned(async def test_notifications_from_a_room_the_agent_was_removed_from_are_not_returned(session_factory: async_sessionmaker[AsyncSession],+ db_buffer: EventBuffer,) -> None:"""The stream that carries what was said *to* the agent, under the same rule.@@ -86,19 +115,15 @@ async def test_notifications_from_a_room_the_agent_was_removed_from_are_not_retusvc = make_service(session_factory)svc.room_store = RoomStore() # type: ignore[attr-defined]svc.agent_session_store = AgentSessionStore() # type: ignore[attr-defined]- svc.event_buffer = EventBuffer(sequence_base=0) # type: ignore[attr-defined]+ svc.event_buffer = db_buffer # type: ignore[attr-defined]owner = await make_owner(session_factory)agent_id = await register(svc, "watcher", owner)kept = await _room(session_factory, "kept-notif", agent_id)left = await _room(session_factory, "left-notif", agent_id)- svc.event_buffer.enqueue(- agent_id, left, _message(left, "asked in the old room", addressed=True)- )- svc.event_buffer.enqueue(- agent_id, kept, _message(kept, "asked in this one", addressed=True)- )+ await _ask(session_factory, db_buffer, agent_id, left, "asked in the old room")+ await _ask(session_factory, db_buffer, agent_id, kept, "asked in this one")async with session_factory() as session:await RoomStore().remove_agents(session, left, [agent_id])diff --git a/core/tests/switch_core/bridges/agent/protocol/test_room_released.py b/core/tests/switch_core/bridges/agent/protocol/test_room_released.pyindex aa2a7f240..f01ceba85 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_room_released.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_room_released.py@@ -17,6 +17,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (Released,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.agent.protocol.stream import KEEPALIVE, event_framesAGENT = "agent-1"@@ -38,7 +39,7 @@ def _open(scope=scope, # type: ignore[arg-type]delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=speaks),expected_generation=None,)@@ -198,9 +199,11 @@ def test_two_sessions_in_one_room_are_refused_without_change() -> None:assert conn.rooms == {ROOM_B}-async def test_the_displaced_stream_is_sent_room_released() -> None:+async def test_the_displaced_stream_is_sent_room_released(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferloser = _open(registry, "loser", speaks=PROTOCOL_VERSION, scope="all")winner = _open(registry, "winner", speaks=PROTOCOL_VERSION, scope="all")registry.replace_placements(loser, {"session-1": ROOM_A})@@ -218,9 +221,11 @@ async def test_the_displaced_stream_is_sent_room_released() -> None:assert [name for name, _ in frames].count("room_released") == 1-async def test_a_client_that_declared_nothing_is_not_sent_room_released() -> None:+async def test_a_client_that_declared_nothing_is_not_sent_room_released(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferloser = _open(registry, "loser", speaks=None, scope="all")winner = _open(registry, "winner", speaks=PROTOCOL_VERSION, scope="all")registry.replace_placements(loser, {"session-1": ROOM_A})diff --git a/core/tests/switch_core/bridges/agent/protocol/test_runtime_state_sweep.py b/core/tests/switch_core/bridges/agent/protocol/test_runtime_state_sweep.pyindex 844f60f9d..368045474 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_runtime_state_sweep.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_runtime_state_sweep.py@@ -29,6 +29,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.agent_core import AgentCore+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.db.models import TENANT_ZERO_IDAGENT = "agent-1"@@ -106,7 +107,7 @@ def _connected(room: str | None) -> AgentConnectionRegistry:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)diff --git a/core/tests/switch_core/bridges/agent/protocol/test_statuses.py b/core/tests/switch_core/bridges/agent/protocol/test_statuses.pyindex df26690b6..a76b58bf0 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_statuses.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_statuses.py@@ -12,6 +12,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.agent.protocol.statuses import compute_agent_statusesfrom switch_core.bridges.agent.protocol.types import AgentStatus@@ -69,7 +70,7 @@ def _registry(scope=scope, # type: ignore[arg-type]delivery_filter="all",spawn_capable=spawn_capable,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)diff --git a/core/tests/switch_core/bridges/agent/protocol/test_stream.py b/core/tests/switch_core/bridges/agent/protocol/test_stream.pyindex 79a4eb78e..8da24cbba 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_stream.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_stream.py@@ -1,24 +1,40 @@-"""SSE delivery: catch-up, live push, resume and the control events (CHOO-1857)."""+"""SSE delivery: catch-up, live push, resume and the control events (CHOO-1857).++A stream carries two kinds of event. The agent's own (a message addressed to+it, a command, a task) are kept for it and numbered in its own sequence; here+they are kept with `_keep`. The rest of a room's conversation is read from the+room's own log, which a test writes with `say`.+"""from __future__ import annotationsimport asyncio+import inspect+from collections.abc import Callablefrom typing import Anyimport pytest+from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core import version as version_modulefrom switch_core.bridges.agent.protocol import stream as stream_modulefrom switch_core.bridges.agent.protocol.agent_connections import (HEARTBEAT_LAPSED,HEARTBEAT_TTL_SECONDS,+ POSITIONS_PROTOCOL_REVISION,PROTOCOL_ACCEPTS,PROTOCOL_VERSION,AgentConnectionRegistry,ClientDeclaration,Closure,)-from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.event_buffer import (+ NO_BASELINE,+ TICKET_FLOOR,+ EventBuffer,+)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTS, room_sourcefrom switch_core.bridges.agent.protocol.stream import (KEEPALIVE,Frame,@@ -27,29 +43,126 @@ from switch_core.bridges.agent.protocol.stream import (event_frames,sse_stream,)-from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.bridges.agent.protocol.types import (+ AgentEvent,+ CommandPayload,+ MessagePayload,+)+from switch_core.db.models import TENANT_ZERO_ID, Agent, Message+from switch_core.db.session_scope import tenant_session+from switch_core.db.stores.room_store import RoomStorefrom switch_core.observability.metrics import MetricsRegistry, install, uninstall+from tests.db_buffer import age_events, db_buffer_on, say, seed_member, sender_ofAGENT = "agent-1"ROOM_A = "room-a"ROOM_B = "room-b"-def _message(body: str, *, addressed: bool = False, room: str = ROOM_A) -> AgentEvent:[email protected](autouse=True)+async def _agent_rows(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agents every stream here is for, in their rooms, so their events+ have a row to belong to and their rooms a conversation to read."""+ await seed_member(session_factory, AGENT, ROOM_A)+ await seed_member(session_factory, AGENT, ROOM_B)+ await seed_member(session_factory, "agent-2", ROOM_A)+++def _message(+ body: str, *, room: str = ROOM_A, message_id: str | None = None+) -> AgentEvent:+ """A message addressed to the agent: one of its own events."""return AgentEvent(type="message",room_id=room,payload=MessagePayload(- addressed=addressed,+ addressed=True,sender="@u:s",sender_name="u",- message_id=f"$evt-{body}",+ message_id=message_id or f"$evt-{body}",body=body,timestamp=0,),)+def _command(name: str, *, room: str = ROOM_A) -> AgentEvent:+ """A command sent to the agent: one of its own events, and never one it is+ woken for."""+ return AgentEvent(+ type="command",+ room_id=room,+ payload=CommandPayload(command=name, user_id="@u:s", user_name="u"),+ )+++async def _keep(buffer: EventBuffer, event: AgentEvent, *, agent: str = AGENT) -> int:+ """Keep `event` as one of the agent's own events and return its number.++ No row in the room's log stands behind it (`room_seq` 0), which is all a+ test that does not count the room needs; `_addressed` writes the row too.+ """+ key = (+ event.payload.message_id if isinstance(event.payload, MessagePayload) else None+ )+ return await buffer.enqueue(+ TENANT_ZERO_ID, agent, event.room_id, event, room_seq=0, message_key=key+ )+++async def _addressed(+ session_factory: async_sessionmaker[AsyncSession],+ buffer: EventBuffer,+ body: str,+ *,+ room: str = ROOM_A,+) -> Message:+ """A message addressed to the agent, as one really arrives: a row in the+ room's log, and the event the agent's consumer keeps for it, naming that+ row. Returns the row.++ Only while no stream that reads the conversation is running: a test's rows+ are settled at once, so one reading in between would take this row for+ conversation before its event lands.+ """+ row = await say(session_factory, room, body)+ await buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT,+ room,+ _message(body, room=room, message_id=row.transport_event_id),+ room_seq=row.seq,+ message_key=row.transport_event_id,+ )+ return row+++async def _leave(session_factory: async_sessionmaker[AsyncSession], room: str) -> None:+ """Take the agent out of the room's membership, as removing it does."""+ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:+ client_id = await session.scalar(+ select(Agent.client_id).where(Agent.id == AGENT)+ )+ assert client_id is not None+ await RoomStore().remove_client(session, client_id, room)+ await session.commit()+++async def _until(check: Callable[[], Any], timeout: float = 2.0) -> None:+ """Wait for the stream to have done something it sends no frame for."""++ async def poll() -> None:+ while True:+ done = check()+ if inspect.isawaitable(done):+ done = await done+ if done:+ return+ await asyncio.sleep(0.01)++ await asyncio.wait_for(poll(), timeout=timeout)++def _parse(frame: Frame) -> tuple[str, dict[str, Any]]:"""A frame as (event name, data)."""return frame.event, frame.data@@ -71,14 +184,19 @@ async def _take(stream, count: int, timeout: float = 2.0) -> list[tuple[str, dicreturn out-def _open(registry: AgentConnectionRegistry, **kw: Any):+def _open(registry: AgentConnectionRegistry, *, cursor: int = 0, **kw: Any):+ """A session's connection: one room, everything said in it.++ `cursor` is where the client resumes in the agent's own events; a test+ that resumes a room's conversation as well passes the whole `position`.+ """params: dict[str, Any] = {"agent_id": AGENT,"connection_id": kw.pop("connection_id", "c1"),"scope": "single","delivery_filter": "all","spawn_capable": False,- "cursor": 0,+ "position": {OWN_EVENTS: cursor},"declaration": ClientDeclaration(speaks=PROTOCOL_VERSION),"expected_generation": None,}@@ -86,9 +204,9 @@ def _open(registry: AgentConnectionRegistry, **kw: Any):return registry.open(**params)-async def test_first_frame_is_the_connection_state() -> None:+async def test_first_frame_is_the_connection_state(db_buffer: EventBuffer) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)@@ -103,9 +221,15 @@ async def test_first_frame_is_the_connection_state() -> None:# The client returns this on every heartbeat; without it the server cannot# tell the holder of a connection from a client displaced from it.assert data["generation"] == conn.stream_generation+ # Where the stream starts, for a client that keeps a position: in the+ # agent's own events and, since it reads the room's conversation, at the+ # room's newest message (none yet).+ assert data["position"] == {OWN_EVENTS: 0, room_source(ROOM_A): 0}-async def test_the_first_frame_declares_the_server(monkeypatch) -> None:+async def test_the_first_frame_declares_the_server(+ monkeypatch, db_buffer: EventBuffer+) -> None:"""Version disclosure rides this frame, not an endpoint of its own.The stream is already authenticated, and nothing about the server's@@ -113,7 +237,7 @@ async def test_the_first_frame_declares_the_server(monkeypatch) -> None:"""monkeypatch.setattr(version_module, "switch_core_version", lambda: "9.9.9")registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)@@ -132,11 +256,12 @@ async def test_the_first_frame_declares_the_server(monkeypatch) -> None:async def test_an_unreadable_server_version_is_null_not_a_placeholder(monkeypatch,+ db_buffer: EventBuffer,) -> None:"""Null means unknown. A placeholder would read as a version we chose."""monkeypatch.setattr(version_module, "switch_core_version", lambda: None)registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)@@ -145,14 +270,16 @@ async def test_an_unreadable_server_version_is_null_not_a_placeholder(assert data["server"]["version"] is None-async def test_the_first_frame_echoes_what_the_client_declared() -> None:+async def test_the_first_frame_echoes_what_the_client_declared(+ db_buffer: EventBuffer,+) -> None:"""So a declaration that failed to parse cannot pass unnoticed.Both sides otherwise believe it landed, which is worse than never havingsent it."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry,declaration=ClientDeclaration(@@ -174,9 +301,11 @@ async def test_the_first_frame_echoes_what_the_client_declared() -> None:}-async def test_an_undeclared_client_is_echoed_as_all_null() -> None:+async def test_an_undeclared_client_is_echoed_as_all_null(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry, declaration=ClientDeclaration())stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)@@ -190,24 +319,24 @@ async def test_an_undeclared_client_is_echoed_as_all_null() -> None:}-async def test_catch_up_then_live_delivery() -> None:+async def test_catch_up_then_live_delivery(db_buffer: EventBuffer) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)- # Queued before the stream opened: must be caught up, not skipped.- buffer.enqueue(AGENT, ROOM_A, _message("before"))+ # Kept before the stream opened: must be caught up, not skipped.+ await _keep(buffer, _message("before"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)frames = await _take(stream, 2)assert frames[1][0] == "message"assert frames[1][1]["payload"]["body"] == "before"- # Appended while the stream is open: pushed without being asked for.+ # Kept while the stream is open: pushed without being asked for.async def append_soon() -> None:await asyncio.sleep(0.01)- buffer.enqueue(AGENT, ROOM_A, _message("after"))+ await _keep(buffer, _message("after"))task = asyncio.create_task(append_soon())live = await _take(stream, 1)@@ -216,25 +345,206 @@ async def test_catch_up_then_live_delivery() -> None:assert live[0][1]["payload"]["body"] == "after"-async def test_sequence_number_is_carried_for_resume() -> None:+async def test_the_conversation_is_read_from_where_the_room_was_when_covered(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """The rest of a room's conversation is not kept for the agent: it is read+ from the room's own log, from where the room was when the stream first+ covered it. What was said before that is history, for `read_context`, not+ a backlog to deliver.++ A client that keeps a position is told the event's place in the room, and+ no number in the agent's own events, which it has none of.+ """registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)conn = _open(registry)registry.claim_room(conn, ROOM_A)- seq = buffer.enqueue(AGENT, ROOM_A, _message("one"))+ await say(session_factory, ROOM_A, "history")++ stream = event_frames(+ conn=conn, registry=registry, buffer=db_buffer, approvals=None+ )+ await _take(stream, 1)+ arriving = asyncio.ensure_future(_take(stream, 1))+ await _until(lambda: room_source(ROOM_A) in conn.position)+ live = await say(session_factory, ROOM_A, "live")+ ((name, data),) = await arriving+ await stream.aclose()++ assert name == "message"+ assert data["payload"]["body"] == "live"+ assert data["payload"]["addressed"] is False+ assert "sequence" not in data+ assert data["position"] == {room_source(ROOM_A): live.seq}+++async def test_the_chatter_before_a_mention_arrives_with_it_and_ahead_of_it(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """The agent's consumer takes a room's rows in order, so every row up to+ one it kept for the agent has been decided: those are read straight away+ rather than once settled, and what led up to a mention arrives ahead of+ it."""+ registry = AgentConnectionRegistry()+ # Settles long after this test is over.+ buffer = db_buffer_on(session_factory, settle_seconds=60)+ conn = _open(registry, position={OWN_EVENTS: 0, room_source(ROOM_A): 0})+ registry.claim_room(conn, ROOM_A)+ await say(session_factory, ROOM_A, "chatter")+ await _addressed(session_factory, buffer, "for you")++ stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)+ _, (_, before), (_, mention) = await _take(stream, 3)+ await stream.aclose()++ assert before["payload"]["body"] == "chatter"+ assert mention["payload"]["body"] == "for you"+++async def test_a_conversation_reader_starts_with_a_place_in_each_room(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """A client learns where it starts from `connection_state`, and one that+ reconnects before any room message arrives resumes from there. Each room it+ reads must already have its place in that position: missing, the room+ would start at its newest message again on the reconnect, and what was+ said in between would never arrive."""+ registry = AgentConnectionRegistry()+ buffer = db_buffer+ said = await say(session_factory, ROOM_A, "before the client connected")+ conn = _open(registry)+ registry.claim_room(conn, ROOM_A)++ stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)+ ((name, opening),) = await _take(stream, 1)+ await stream.aclose()+ await say(session_factory, ROOM_A, "while the client was away")+ again = _open(registry, position=opening["position"])+ registry.claim_room(again, ROOM_A)+ stream = event_frames(conn=again, registry=registry, buffer=buffer, approvals=None)+ _, (_, missed) = await _take(stream, 2)+ await stream.aclose()++ assert name == "connection_state"+ assert opening["position"] == {OWN_EVENTS: 0, room_source(ROOM_A): said.seq}+ assert missed["payload"]["body"] == "while the client was away"+++async def test_a_gap_for_own_events_all_deleted_is_sent_once(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """When retention has deleted every one of the agent's own events, the gap+ moves the connection past all of them, so the next frame is the next+ event rather than the same gap again."""+ registry = AgentConnectionRegistry()+ buffer = db_buffer+ await _keep(buffer, _message("dropped"))+ await age_events(session_factory, AGENT, seconds=2 * 3600)+ await buffer.expire(TENANT_ZERO_ID)+ conn = _open(registry, cursor=0)+ registry.claim_room(conn, ROOM_A)++ stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)+ _, (gap, _) = await _take(stream, 2)+ await _keep(buffer, _message("after the gap"))+ ((name, after),) = await _take(stream, 1)+ await stream.aclose()++ assert gap == "gap"+ assert name == "message"+ assert after["payload"]["body"] == "after the gap"+++async def test_sequence_number_is_carried_for_resume(db_buffer: EventBuffer) -> None:+ registry = AgentConnectionRegistry()+ buffer = db_buffer+ conn = _open(registry)+ registry.claim_room(conn, ROOM_A)+ seq = await _keep(buffer, _message("one"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)frames = await _take(stream, 2)assert frames[1][1]["sequence"] == seq+ # And, for a client that keeps a position, the event's place in its source.+ assert frames[1][1]["position"] == {OWN_EVENTS: seq}assert conn.cursor == seq-async def test_resuming_from_a_cursor_skips_what_was_already_seen() -> None:+async def test_a_client_that_keeps_one_number_is_handed_tickets(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:+ """A client built before positions keeps one number per stream. A stream+ that reads the conversation as well as the agent's own events has a place+ in each, so every event it sends such a client is numbered with a ticket+ standing for the whole position after it: the number the client sends+ back resumes it exactly there."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)- first = buffer.enqueue(AGENT, ROOM_A, _message("seen"))- buffer.enqueue(AGENT, ROOM_A, _message("missed"))+ buffer = db_buffer+ said = await say(session_factory, ROOM_A, "chatter")+ kept = await _keep(buffer, _message("for you"))+ conn = _open(+ registry,+ position={OWN_EVENTS: 0, room_source(ROOM_A): 0},+ declaration=ClientDeclaration(speaks=POSITIONS_PROTOCOL_REVISION - 1),+ )+ registry.claim_room(conn, ROOM_A)++ stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)+ _, (_, chatter), (_, mine) = await _take(stream, 3)+ await stream.aclose()++ assert chatter["payload"]["body"] == "chatter"+ assert mine["payload"]["body"] == "for you"+ assert chatter["sequence"] >= TICKET_FLOOR+ assert "position" not in chatter+ assert await buffer.ticket(TENANT_ZERO_ID, AGENT, chatter["sequence"]) == {+ OWN_EVENTS: 0,+ room_source(ROOM_A): said.seq,+ }+ assert await buffer.ticket(TENANT_ZERO_ID, AGENT, mine["sequence"]) == {+ OWN_EVENTS: kept,+ room_source(ROOM_A): said.seq,+ }+ assert conn.cursor == mine["sequence"]+++async def test_a_ticket_never_covers_an_event_still_to_come(+ db_buffer: EventBuffer,+) -> None:+ """One of the agent's own events for a room this connection does not cover+ is not sent, and the position moves past it. A ticket handed out for an+ event before it must not include it: a client that reconnects with that+ ticket would resume past the events in between and never receive them."""+ registry = AgentConnectionRegistry()+ buffer = db_buffer+ first = await _keep(buffer, _message("first"))+ second = await _keep(buffer, _message("second"))+ await _keep(buffer, _message("elsewhere", room=ROOM_B))+ conn = _open(+ registry,+ position={OWN_EVENTS: 0, room_source(ROOM_A): 0},+ declaration=ClientDeclaration(speaks=POSITIONS_PROTOCOL_REVISION - 1),+ )+ registry.claim_room(conn, ROOM_A)++ stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)+ _, (_, one), (_, two) = await _take(stream, 3)+ await stream.aclose()+ after_one = await buffer.ticket(TENANT_ZERO_ID, AGENT, one["sequence"])+ after_two = await buffer.ticket(TENANT_ZERO_ID, AGENT, two["sequence"])++ assert after_one is not None and after_one[OWN_EVENTS] == first+ assert after_two is not None and after_two[OWN_EVENTS] == second+++async def test_resuming_from_a_cursor_skips_what_was_already_seen(+ db_buffer: EventBuffer,+) -> None:+ registry = AgentConnectionRegistry()+ buffer = db_buffer+ first = await _keep(buffer, _message("seen"))+ await _keep(buffer, _message("missed"))conn = _open(registry, cursor=first)registry.claim_room(conn, ROOM_A)@@ -245,11 +555,15 @@ async def test_resuming_from_a_cursor_skips_what_was_already_seen() -> None:assert frames[1][1]["payload"]["body"] == "missed"-async def test_expired_cursor_produces_a_gap_event_rather_than_silence() -> None:+async def test_expired_cursor_produces_a_gap_event_rather_than_silence(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(max_events_per_agent=1, sequence_base=0)- buffer.enqueue(AGENT, ROOM_A, _message("dropped"))- buffer.enqueue(AGENT, ROOM_A, _message("kept"))+ buffer = db_buffer+ await _keep(buffer, _message("dropped"))+ await age_events(session_factory, AGENT, seconds=2 * 3600)+ await buffer.expire(TENANT_ZERO_ID)+ await _keep(buffer, _message("kept"))conn = _open(registry, cursor=0)registry.claim_room(conn, ROOM_A)@@ -261,14 +575,16 @@ async def test_expired_cursor_produces_a_gap_event_rather_than_silence() -> Noneassert "re-read" in frames[1][1]["reason"]-async def test_events_for_rooms_the_connection_does_not_cover_are_skipped() -> None:+async def test_events_for_rooms_the_connection_does_not_cover_are_skipped(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)- buffer.enqueue(AGENT, ROOM_B, _message("elsewhere", room=ROOM_B))- buffer.enqueue(AGENT, ROOM_A, _message("mine"))+ await _keep(buffer, _message("elsewhere", room=ROOM_B))+ await _keep(buffer, _message("mine"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)frames = await _take(stream, 2)@@ -276,13 +592,22 @@ async def test_events_for_rooms_the_connection_does_not_cover_are_skipped() -> Nassert frames[1][1]["payload"]["body"] == "mine"-async def test_addressed_filter_drops_ambient_chatter() -> None:+async def test_addressed_filter_drops_ambient_chatter(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)- conn = _open(registry, scope="all", delivery_filter="addressed")+ buffer = db_buffer+ # From a position before the chatter, which a stream reading everything+ # would be sent.+ conn = _open(+ registry,+ scope="all",+ delivery_filter="addressed",+ position={OWN_EVENTS: 0, room_source(ROOM_A): 0},+ )- buffer.enqueue(AGENT, ROOM_A, _message("chatter"))- buffer.enqueue(AGENT, ROOM_B, _message("wanted", addressed=True, room=ROOM_B))+ await say(session_factory, ROOM_A, "chatter")+ await _keep(buffer, _message("wanted", room=ROOM_B))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)frames = await _take(stream, 2)@@ -290,9 +615,11 @@ async def test_addressed_filter_drops_ambient_chatter() -> None:assert frames[1][1]["payload"]["body"] == "wanted"-async def test_a_superseded_stream_is_told_it_was_evicted() -> None:+async def test_a_superseded_stream_is_told_it_was_evicted(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)@@ -301,7 +628,7 @@ async def test_a_superseded_stream_is_told_it_was_evicted() -> None:# A second stream attaches to the same connection id._open(registry)- buffer.enqueue(AGENT, ROOM_A, _message("wake up"))+ await _keep(buffer, _message("wake up"))frames = await _take(stream, 1)assert frames[0][0] == "evicted"@@ -310,9 +637,11 @@ async def test_a_superseded_stream_is_told_it_was_evicted() -> None:assert frames[0][1]["code"] == "taken_over"-async def test_closing_the_connection_ends_the_stream_with_a_reason() -> None:+async def test_closing_the_connection_ends_the_stream_with_a_reason(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)@@ -328,10 +657,12 @@ async def test_closing_the_connection_ends_the_stream_with_a_reason() -> None:assert frames[0][1]["room_id"] is None-async def test_a_close_about_a_room_names_the_room_it_was_about() -> None:+async def test_a_close_about_a_room_names_the_room_it_was_about(+ db_buffer: EventBuffer,+) -> None:"""A client that loses a connection over a room it declared must be told which."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)@@ -349,9 +680,9 @@ async def test_a_close_about_a_room_names_the_room_it_was_about() -> None:assert data["room_id"] == ROOM_A-async def test_subscription_change_is_announced() -> None:+async def test_subscription_change_is_announced(db_buffer: EventBuffer) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)@@ -371,9 +702,11 @@ async def test_subscription_change_is_announced() -> None:assert frames[0][1]["rooms"] == [ROOM_B]-async def test_stream_detaches_on_exit_without_killing_the_connection() -> None:+async def test_stream_detaches_on_exit_without_killing_the_connection(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)@@ -385,10 +718,21 @@ async def test_stream_detaches_on_exit_without_killing_the_connection() -> None:@pytest.mark.parametrize("scope", ["single", "all"])-async def test_two_connections_receive_the_same_event(scope: str) -> None:- """Non-destructive reads: one reader must not steal from another."""+async def test_two_connections_receive_the_same_event(+ scope: str,+ db_buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """Non-destructive reads: one reader must not steal from another.++ The conversation is read where it lies, in the room's log, so one row is+ read by every agent in the room.+ """registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_buffer+ await say(session_factory, ROOM_A, "shared")+ # Both resume from before it.+ start = {OWN_EVENTS: 0, room_source(ROOM_A): 0}session = registry.open(agent_id=AGENT,@@ -396,7 +740,7 @@ async def test_two_connections_receive_the_same_event(scope: str) -> None:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position=start,declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -408,15 +752,12 @@ async def test_two_connections_receive_the_same_event(scope: str) -> None:scope=scope, # type: ignore[arg-type]delivery_filter="all",spawn_capable=False,- cursor=0,+ position=start,declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)registry.claim_room(other_agent, ROOM_A)- buffer.enqueue(AGENT, ROOM_A, _message("shared"))- buffer.enqueue("agent-2", ROOM_A, _message("shared"))-a = event_frames(conn=session, registry=registry, buffer=buffer, approvals=None)b = event_frames(conn=other_agent, registry=registry, buffer=buffer, approvals=None)@@ -424,7 +765,9 @@ async def test_two_connections_receive_the_same_event(scope: str) -> None:assert (await _take(b, 2))[1][1]["payload"]["body"] == "shared"-async def test_resume_replays_buffered_events_for_a_room_claimed_at_open() -> None:+async def test_resume_replays_buffered_events_for_a_room_claimed_at_open(+ db_buffer: EventBuffer,+) -> None:"""The reconnect case the whole design exists for.A client that drops and comes back declares its room when it reopens. If@@ -433,10 +776,10 @@ async def test_resume_replays_buffered_events_for_a_room_claimed_at_open() -> Nothem — losing exactly what resume is meant to recover."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_buffer- seen = buffer.enqueue(AGENT, ROOM_A, _message("before the drop"))- buffer.enqueue(AGENT, ROOM_A, _message("while disconnected"))+ seen = await _keep(buffer, _message("before the drop"))+ await _keep(buffer, _message("while disconnected"))conn = _open(registry, connection_id="c-resumed", cursor=seen)# Claimed before the stream is created, as the endpoint does.@@ -449,15 +792,17 @@ async def test_resume_replays_buffered_events_for_a_room_claimed_at_open() -> Noassert frames[1][1]["payload"]["body"] == "while disconnected"-async def test_events_for_uncovered_rooms_do_not_block_the_cursor() -> None:+async def test_events_for_uncovered_rooms_do_not_block_the_cursor(+ db_buffer: EventBuffer,+) -> None:"""Skipping is deliberate for rooms this connection does not cover."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)- buffer.enqueue(AGENT, ROOM_B, _message("someone else's room", room=ROOM_B))- last = buffer.enqueue(AGENT, ROOM_A, _message("mine"))+ await _keep(buffer, _message("someone else's room", room=ROOM_B))+ last = await _keep(buffer, _message("mine"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)frames = await _take(stream, 2)@@ -466,16 +811,19 @@ async def test_events_for_uncovered_rooms_do_not_block_the_cursor() -> None:assert conn.cursor == last-async def test_a_cursor_from_before_a_restart_is_reported_not_ignored() -> None:- """The buffer is in memory, so a restart resets the numbering.+async def test_a_cursor_from_before_a_restart_is_reported_not_ignored(+ db_buffer: EventBuffer,+) -> None:+ """A cursor ahead of everything the agent's events reach is from some other+ history: the in-memory buffer before them, a restored database.- A client that comes back with a cursor from the previous process would- otherwise sit quietly at a position that no longer means anything, looking- caught up while its history has a hole in it.+ A client that comes back with one would otherwise sit quietly at a+ position that no longer means anything, looking caught up while its+ history has a hole in it."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)- buffer.enqueue(AGENT, ROOM_A, _message("after the restart"))+ buffer = db_buffer+ await _keep(buffer, _message("after the restart"))conn = _open(registry, cursor=4812) # from a previous liferegistry.claim_room(conn, ROOM_A)@@ -487,13 +835,16 @@ async def test_a_cursor_from_before_a_restart_is_reported_not_ignored() -> None:assert "restarted" in frames[1][1]["reason"]-async def test_stream_reports_restart_below_floor() -> None:- """Each boot numbers above the last, so a previous boot's cursor is below- this one's floor rather than above its head. The restart is still told, and- `resumed_at` sits above the old cursor so the client keeps its dedupe."""+async def test_stream_reports_restart_below_floor(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """An agent's numbering starts above every earlier boot's, so a cursor+ from before its events were kept here is below its floor rather than above+ its head. That is still told, and `resumed_at` sits above the old cursor so+ the client keeps its dedupe."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=7 << 32)- first = buffer.enqueue(AGENT, ROOM_A, _message("after the restart"))+ buffer = db_buffer_on(session_factory, sequence_base=7 << 32)+ first = await _keep(buffer, _message("after the restart"))old_cursor = (6 << 32) + 4812conn = _open(registry, cursor=old_cursor)@@ -507,10 +858,14 @@ async def test_stream_reports_restart_below_floor() -> None:assert gap["from_sequence"] == old_cursorassert gap["resumed_at"] == buffer.sequence_floor - 1assert gap["resumed_at"] > old_cursor+ # The same place, for a client that keeps a position.+ assert gap["resumed_position"] == {+ OWN_EVENTS: gap["resumed_at"],+ room_source(ROOM_A): 0,+ }assert gap["all_rooms"] is Trueassert "restarted" in gap["reason"]assert frames[2][1]["sequence"] == first == buffer.sequence_floor- assert buffer.unread(AGENT, ROOM_A, first).count is Noneclass TestALapsedHeartbeatStopsDelivery:@@ -525,11 +880,13 @@ class TestALapsedHeartbeatStopsDelivery:session from it."""- async def test_the_stream_evicts_when_the_heartbeat_lapses(self) -> None:+ async def test_the_stream_evicts_when_the_heartbeat_lapses(+ self, db_buffer: EventBuffer+ ) -> None:import time as _timeregistry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)@@ -540,7 +897,7 @@ class TestALapsedHeartbeatStopsDelivery:await _take(stream, 1)conn.last_beat = _time.monotonic() - (HEARTBEAT_TTL_SECONDS + 1)- buffer.enqueue(AGENT, ROOM_A, _message("should not arrive"))+ await _keep(buffer, _message("should not arrive"))((name, data),) = await _take(stream, 1)@@ -548,12 +905,14 @@ class TestALapsedHeartbeatStopsDelivery:assert data["code"] == "heartbeat_lapsed"assert "heartbeat" in data["reason"]- async def test_the_connection_is_closed_not_merely_ignored(self) -> None:+ async def test_the_connection_is_closed_not_merely_ignored(+ self, db_buffer: EventBuffer+ ) -> None:"""Otherwise the room slot stays claimed by a connection that is gone."""import time as _timeregistry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)registry.claim_room(conn, ROOM_A)@@ -583,16 +942,16 @@ class TestFilteredEventsDoNotSpinTheLoop:"""async def test_the_cursor_advances_past_events_the_filter_excludes(- self, monkeypatch: pytest.MonkeyPatch+ self, monkeypatch: pytest.MonkeyPatch, db_buffer: EventBuffer) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry, delivery_filter="addressed")registry.claim_room(conn, ROOM_A)- # Unaddressed chatter: real events, none of them notifiable.+ # Commands: the agent's own events, none of them notifiable.for i in range(3):- buffer.enqueue(AGENT, ROOM_A, _message(f"chatter-{i}", addressed=False))+ await _keep(buffer, _command(f"command-{i}"))# Shorten the keepalive so "did it reach its wait?" is answered in# milliseconds. A spinning generator never yields one at any interval.@@ -604,20 +963,21 @@ class TestFilteredEventsDoNotSpinTheLoop:await _take(stream, 1) # connection_stateawait asyncio.wait_for(anext(stream), timeout=2.0)- assert conn.cursor == buffer.head(AGENT)+ assert conn.cursor == await buffer.head(TENANT_ZERO_ID, AGENT)await stream.aclose()async def test_an_addressed_event_after_the_excluded_ones_still_arrives(self,+ db_buffer: EventBuffer,) -> None:"""Advancing past the excluded events must not skip what follows."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry, delivery_filter="addressed")registry.claim_room(conn, ROOM_A)- buffer.enqueue(AGENT, ROOM_A, _message("chatter", addressed=False))- buffer.enqueue(AGENT, ROOM_A, _message("for-you", addressed=True))+ await _keep(buffer, _command("reset"))+ await _keep(buffer, _message("for-you"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None@@ -628,6 +988,41 @@ class TestFilteredEventsDoNotSpinTheLoop:assert frames[1][1]["payload"]["body"] == "for-you"await stream.aclose()+ async def test_the_room_position_moves_past_rows_that_are_not_conversation(+ self,+ monkeypatch: pytest.MonkeyPatch,+ db_buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ """The same for the conversation. The agent's own message, and a row it+ was already sent as one of its own events, are looked at and passed+ over: the stream moves past them rather than reading them again on+ every pass, and the addressed message arrives once, not twice."""+ monkeypatch.setattr(stream_module, "KEEPALIVE_INTERVAL_SECONDS", 0.05)+ registry = AgentConnectionRegistry()+ buffer = db_buffer+ conn = _open(registry, position={OWN_EVENTS: 0, room_source(ROOM_A): 0})+ registry.claim_room(conn, ROOM_A)++ await say(session_factory, ROOM_A, "chatter")+ mine = await sender_of(session_factory, AGENT)+ await say(session_factory, ROOM_A, "said by the agent", sender=mine)+ addressed = await _addressed(session_factory, buffer, "for you")++ stream = event_frames(+ conn=conn, registry=registry, buffer=buffer, approvals=None+ )+ frames = await _take(stream, 3)+ # Nothing more to send: the next thing out is the idle tick.+ assert await asyncio.wait_for(anext(stream), timeout=2.0) is KEEPALIVE+ await stream.aclose()++ assert sorted(+ (data["payload"]["body"], data["payload"]["addressed"])+ for _, data in frames[1:]+ ) == [("chatter", False), ("for you", True)]+ assert conn.position[room_source(ROOM_A)] == addressed.seq+class TestAConnectionWithNoRoomDoesNotConsume:"""A session connection must not burn through the buffer before it has a room.@@ -644,35 +1039,35 @@ class TestAConnectionWithNoRoomDoesNotConsume:"""async def test_the_cursor_survives_the_wait_for_a_room(- self, monkeypatch: pytest.MonkeyPatch+ self, monkeypatch: pytest.MonkeyPatch, db_buffer: EventBuffer) -> None:monkeypatch.setattr(stream_module, "KEEPALIVE_INTERVAL_SECONDS", 0.05)registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_buffer# Opened at 0, like a session handed its trigger's position.conn = _open(registry, cursor=0)- buffer.enqueue(AGENT, ROOM_A, _message("the trigger", addressed=True))+ await _keep(buffer, _message("the trigger"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)await _take(stream, 1) # connection_state- # Parked: a keepalive rather than the event, and no cursor movement.+ # Parked: a keepalive rather than the event, and no position moved.await asyncio.wait_for(anext(stream), timeout=2.0)- assert conn.cursor == 0+ assert conn.position == {OWN_EVENTS: 0}await stream.aclose()async def test_the_trigger_arrives_once_the_room_is_claimed(- self, monkeypatch: pytest.MonkeyPatch+ self, monkeypatch: pytest.MonkeyPatch, db_buffer: EventBuffer) -> None:monkeypatch.setattr(stream_module, "KEEPALIVE_INTERVAL_SECONDS", 0.05)registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry, cursor=0)- buffer.enqueue(AGENT, ROOM_A, _message("the trigger", addressed=True))+ await _keep(buffer, _message("the trigger"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None@@ -689,13 +1084,15 @@ class TestAConnectionWithNoRoomDoesNotConsume:assert frames[1][1]["payload"]["body"] == "the trigger"await stream.aclose()- async def test_an_all_scope_connection_is_not_parked(self) -> None:+ async def test_an_all_scope_connection_is_not_parked(+ self, db_buffer: EventBuffer+ ) -> None:"""A watcher holds no room by design and must keep receiving."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry, scope="all", connection_id="watcher")- buffer.enqueue(AGENT, ROOM_A, _message("hello", addressed=True))+ await _keep(buffer, _message("hello"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None@@ -706,19 +1103,23 @@ class TestAConnectionWithNoRoomDoesNotConsume:await stream.aclose()-async def test_replaced_stream_cannot_capture_its_successors_generation() -> None:+async def test_replaced_stream_cannot_capture_its_successors_generation(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)old = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)_open(registry)assert await _take(old, 1) == []- assert registry.beat(AGENT, conn.id, 0, conn.stream_generation).stream_attached+ assert registry.beat(AGENT, conn.id, conn.stream_generation).stream_attached-async def test_closed_stream_cannot_detach_a_recreated_connection() -> None:+async def test_closed_stream_cannot_detach_a_recreated_connection(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)old = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)await anext(old)@@ -727,13 +1128,13 @@ async def test_closed_stream_cannot_detach_a_recreated_connection() -> None:assert replacement is not connawait old.aclose()assert registry.beat(- AGENT, replacement.id, 0, replacement.stream_generation+ AGENT, replacement.id, replacement.stream_generation).stream_attached-async def test_a_resumed_stream_does_not_replay_a_room_the_agent_was_removed_from() -> (- None-):+async def test_a_resumed_stream_does_not_replay_a_room_the_agent_was_removed_from(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:"""The leak this stream had no way of its own to close.Membership is checked when a room is claimed and never again, and an@@ -744,21 +1145,30 @@ async def test_a_resumed_stream_does_not_replay_a_room_the_agent_was_removed_froWhat closes it is acting on the removal once, where it is known: theroom's events leave the buffer and its claim is released, so there is- nothing left for any reader to be handed. This asserts the property at the- reader that has no other defence.+ nothing left for any reader to be handed. The room's conversation stays+ in its log, and is not read for a room the agent is no longer in. This+ asserts the property at the reader that has no other defence."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_buffer- buffer.enqueue(AGENT, ROOM_A, _message("said before the removal"))- buffer.enqueue(AGENT, ROOM_B, _message("still a member here", room=ROOM_B))+ await say(session_factory, ROOM_A, "chatter before the removal")+ await _keep(buffer, _message("said before the removal"))+ await _keep(buffer, _message("still a member here", room=ROOM_B))- # What a kick does, through the two calls `AgentConsumer.on_removed` makes.- buffer.drop_room(AGENT, ROOM_A)+ # What a kick does: the membership goes, and `AgentConsumer.on_removed`+ # makes these two calls.+ await _leave(session_factory, ROOM_A)+ await buffer.drop_room(TENANT_ZERO_ID, AGENT, ROOM_A)registry.release_room_everywhere(AGENT, ROOM_A)- # The supervisor comes back and resumes from before both events.- conn = _open(registry, connection_id="c-resumed", scope="all", cursor=0)+ # The supervisor comes back and resumes from before all of it.+ conn = _open(+ registry,+ connection_id="c-resumed",+ scope="all",+ position={OWN_EVENTS: 0, room_source(ROOM_A): 0, room_source(ROOM_B): 0},+ )stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)frames = await _take(stream, 2)@@ -766,29 +1176,31 @@ async def test_a_resumed_stream_does_not_replay_a_room_the_agent_was_removed_froassert frames[1][1]["payload"]["body"] == "still a member here"-async def test_a_last_event_id_reconnect_does_not_replay_a_removed_room() -> None:+async def test_a_last_event_id_reconnect_does_not_replay_a_removed_room(+ db_buffer: EventBuffer,+) -> None:"""The resume a real client actually performs.An SSE client reconnects by sending back the `Last-Event-ID` it last saw;- `_resolve_start_cursor` prefers it over `start_from` and the stream resumes+ `_resolve_start_position` prefers it over `start_from` and the stream resumesfrom there. That is the path the removed room's retained tail would comeback down, and it is the one a browser or an agent runtime takes withoutbeing asked — so it is worth pinning separately from an explicitlyrequested `start_from`."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_buffer- seen = buffer.enqueue(AGENT, ROOM_A, _message("before the drop"))- buffer.enqueue(AGENT, ROOM_A, _message("while it was still a member"))- buffer.enqueue(AGENT, ROOM_B, _message("in the room it kept", room=ROOM_B))+ seen = await _keep(buffer, _message("before the drop"))+ await _keep(buffer, _message("while it was still a member"))+ await _keep(buffer, _message("in the room it kept", room=ROOM_B))- buffer.drop_room(AGENT, ROOM_A)+ await buffer.drop_room(TENANT_ZERO_ID, AGENT, ROOM_A)registry.release_room_everywhere(AGENT, ROOM_A)# `seen` is what the client would send back as Last-Event-ID: a cursor from# while it was still in room A, resolved to exactly this by- # `_resolve_start_cursor`.+ # `_resolve_start_position`.conn = _open(registry, connection_id="c-reconnect", scope="all", cursor=seen)stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)frames = await _take(stream, 2)@@ -800,24 +1212,29 @@ async def test_a_last_event_id_reconnect_does_not_replay_a_removed_room() -> Nonclass TestWhatADeliveredEventSaysAboutItsRoom:"""An agent is woken for addressed traffic; the chatter rides along with it.- The count is per room and comes off the buffer, so the client renders what- it is told rather than tallying what it happened to filter out.+ The count is per room and is taken from the room's log, so the client+ renders what it is told rather than tallying what it happened to filter+ out."""async def test_a_delivered_event_carries_the_chatter_of_its_own_room(self,+ db_buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry, delivery_filter="addressed")- registry.claim_room(conn, ROOM_A)- registry.claim_room(conn, ROOM_B)+ for room in (ROOM_A, ROOM_B):+ registry.claim_room(conn, room)+ # Declared as the connection opened, which counts the room from then.+ await buffer.take_counting(TENANT_ZERO_ID, AGENT, conn.id, room)- buffer.enqueue(AGENT, ROOM_A, _message("chatter-1"))- buffer.enqueue(AGENT, ROOM_A, _message("chatter-2"))- buffer.enqueue(AGENT, ROOM_B, _message("elsewhere", room=ROOM_B))- buffer.enqueue(AGENT, ROOM_A, _message("for you", addressed=True))- buffer.enqueue(AGENT, ROOM_B, _message("also you", addressed=True, room=ROOM_B))+ await say(session_factory, ROOM_A, "chatter-1")+ await say(session_factory, ROOM_A, "chatter-2")+ await say(session_factory, ROOM_B, "elsewhere")+ await _addressed(session_factory, buffer, "for you")+ await _addressed(session_factory, buffer, "also you", room=ROOM_B)stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None@@ -828,43 +1245,52 @@ class TestWhatADeliveredEventSaysAboutItsRoom:assert frames[1][1]["missed"] == {"count": 2, "reason": None}assert frames[2][1]["missed"] == {"count": 1, "reason": None}- async def test_chatter_the_stream_walked_past_is_still_counted(self) -> None:- """The fast-forward moves the cursor, not the reader's watermark.+ async def test_chatter_the_stream_moved_past_is_still_counted(+ self,+ db_buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ """Sending the conversation moves the position, not where the agent+ caught up.- Skipping unnotifiable events is what keeps the generator from spinning;- it must not double as a claim that the agent has seen them.+ The position is what keeps the stream from reading the chatter again;+ it must not double as a claim that the agent has read it. Only+ catching up (`read_context`) clears the count."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)- conn = _open(registry, delivery_filter="addressed")+ buffer = db_buffer+ conn = _open(registry, position={OWN_EVENTS: 0, room_source(ROOM_A): 0})registry.claim_room(conn, ROOM_A)- chatter = buffer.enqueue(AGENT, ROOM_A, _message("chatter"))+ await buffer.take_counting(TENANT_ZERO_ID, AGENT, conn.id, ROOM_A)+ chatter = await say(session_factory, ROOM_A, "chatter")stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)- await _take(stream, 1)-- waiting = asyncio.ensure_future(_take(stream, 1))- await asyncio.sleep(0.05)- assert conn.cursor == chatter # walked past rather than delivered+ (_, (_, sent)) = await _take(stream, 2)+ assert sent["payload"]["body"] == "chatter"+ assert conn.position[room_source(ROOM_A)] == chatter.seq- buffer.enqueue(AGENT, ROOM_A, _message("for you", addressed=True))- ((_, data),) = await waiting+ # The stream waits on the frame it just yielded, so the addressed row+ # and its event both land before it reads again.+ await _addressed(session_factory, buffer, "for you")+ ((_, data),) = await _take(stream, 1)await stream.aclose()- assert data["missed"]["count"] == 1+ assert data["missed"] == {"count": 1, "reason": None}async def test_a_room_claimed_after_the_connection_opened_counts_from_there(self,+ db_buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry, delivery_filter="addressed")registry.claim_room(conn, ROOM_A)- buffer.enqueue(AGENT, ROOM_B, _message("before the claim", room=ROOM_B))- buffer.enqueue(AGENT, ROOM_A, _message("for you", addressed=True))+ await say(session_factory, ROOM_B, "before the claim")+ await _addressed(session_factory, buffer, "for you")stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None@@ -872,42 +1298,60 @@ class TestWhatADeliveredEventSaysAboutItsRoom:await _take(stream, 2) # connection_state, then the message in room Aregistry.claim_room(conn, ROOM_B)- buffer.enqueue(AGENT, ROOM_B, _message("chatter", room=ROOM_B))- buffer.enqueue(AGENT, ROOM_B, _message("for you", addressed=True, room=ROOM_B))- frames = await _take(stream, 2) # subscription_changed, then the message+ # subscription_changed, then the message.+ arriving = asyncio.ensure_future(_take(stream, 2))++ async def counting_room_b() -> bool:+ unread = await buffer.unread(TENANT_ZERO_ID, AGENT, ROOM_B, 0)+ return unread.reason is None++ await _until(counting_room_b)+ await say(session_factory, ROOM_B, "chatter")+ await _addressed(session_factory, buffer, "for you", room=ROOM_B)+ frames = await arrivingawait stream.aclose()assert frames[1][1]["missed"] == {"count": 1, "reason": None}- async def test_a_count_is_absent_rather_than_zero_after_a_restart(self) -> None:+ async def test_a_count_is_absent_rather_than_zero_where_nothing_counts_the_room(+ self,+ db_buffer: EventBuffer,+ session_factory: async_sessionmaker[AsyncSession],+ ) -> None:+ """A watcher covers every room no session holds, and counts none of+ them: a room is counted from when something takes it. An event in a+ room nothing has counted says the count cannot be told, rather than a+ zero the agent would believe."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)- conn = _open(registry, cursor=4812) # from a previous life- registry.claim_room(conn, ROOM_A)+ buffer = db_buffer+ conn = _open(registry, scope="all", delivery_filter="addressed")++ await say(session_factory, ROOM_A, "chatter")+ await _addressed(session_factory, buffer, "for you")stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)- assert (await _take(stream, 2))[1][0] == "gap"-- buffer.enqueue(AGENT, ROOM_A, _message("for you", addressed=True))- ((_, data),) = await _take(stream, 1)+ frames = await _take(stream, 2)await stream.aclose()- assert data["missed"]["count"] is None- assert "restarted" in data["missed"]["reason"]+ assert frames[1][1]["missed"] == {"count": None, "reason": NO_BASELINE}class TestAGapNamesTheRoomsThatLostEvents:""" "Something was dropped" is unactionable across a dozen rooms."""- async def test_an_expired_cursor_names_them(self) -> None:+ async def test_an_expired_cursor_names_them(+ self, db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(max_events_per_agent=2, sequence_base=0)- buffer.enqueue(AGENT, ROOM_A, _message("dropped"))- buffer.enqueue(AGENT, ROOM_B, _message("dropped", room=ROOM_B))- buffer.enqueue(AGENT, ROOM_A, _message("kept"))- buffer.enqueue(AGENT, ROOM_B, _message("kept", room=ROOM_B))+ buffer = db_buffer+ await _keep(buffer, _message("dropped"))+ await _keep(buffer, _message("dropped", room=ROOM_B))+ await age_events(session_factory, AGENT, seconds=2 * 3600)+ await buffer.expire(TENANT_ZERO_ID)+ await _keep(buffer, _message("kept"))+ await _keep(buffer, _message("kept", room=ROOM_B))conn = _open(registry, cursor=0)registry.claim_room(conn, ROOM_A)@@ -922,10 +1366,12 @@ class TestAGapNamesTheRoomsThatLostEvents:assert frames[1][0] == "gap"assert sorted(frames[1][1]["rooms"]) == [ROOM_A, ROOM_B]- async def test_a_restart_names_the_rooms_the_connection_covers(self) -> None:+ async def test_a_restart_names_the_rooms_the_connection_covers(+ self, db_buffer: EventBuffer+ ) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)- buffer.enqueue(AGENT, ROOM_A, _message("after the restart"))+ buffer = db_buffer+ await _keep(buffer, _message("after the restart"))conn = _open(registry, cursor=4812)registry.claim_room(conn, ROOM_A)@@ -940,16 +1386,27 @@ class TestAGapNamesTheRoomsThatLostEvents:assert frames[1][1]["rooms"] == [ROOM_A]assert frames[1][1]["all_rooms"] is True- async def test_a_restart_says_the_loss_is_not_confined_to_them(self) -> None:+ async def test_a_restart_says_the_loss_is_not_confined_to_them(+ self, db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:"""A watcher of every room names none, and its rooms arrive afterwards.Reporting only what the connection had claimed would leave every room- its sessions go on to claim answering with a fresh zero, which is the- restart made invisible in exactly the rooms the agent works in.+ its sessions go on to claim looking untouched, which is the restart+ made invisible in exactly the rooms the agent works in. What each of+ those rooms is behind by is kept in the database, so it survives the+ restart: told in full, never a fresh zero."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)- buffer.enqueue(AGENT, ROOM_A, _message("after the restart"))+ buffer = db_buffer+ # Before the restart a session had room B, and the room went on talking.+ before_the_restart = db_buffer_on(session_factory)+ await before_the_restart.take_counting(+ TENANT_ZERO_ID, AGENT, "session-before", ROOM_B+ )+ await say(session_factory, ROOM_B, "said before the restart")++ await _keep(buffer, _message("after the restart"))conn = _open(registry, scope="all", cursor=4812)stream = event_frames(@@ -962,19 +1419,58 @@ class TestAGapNamesTheRoomsThatLostEvents:assert frames[1][1]["all_rooms"] is Trueregistry.claim_room(conn, ROOM_B)- buffer.enqueue(AGENT, ROOM_B, _message("chatter", room=ROOM_B))- buffer.enqueue(AGENT, ROOM_B, _message("for you", addressed=True, room=ROOM_B))- delivered = await _take(stream, 3) # subscription_changed, then both+ await say(session_factory, ROOM_B, "chatter")+ await _addressed(session_factory, buffer, "for you", room=ROOM_B)+ # subscription_changed, the chatter (this connection reads the room's+ # conversation from where it opened), then the message.+ delivered = await _take(stream, 3)await stream.aclose()- assert delivered[-1][1]["missed"]["count"] is None- assert "restarted" in delivered[-1][1]["missed"]["reason"]+ assert [frame[1].get("payload", {}).get("body") for frame in delivered[1:]] == [+ "chatter",+ "for you",+ ]+ assert delivered[-1][1]["missed"] == {"count": 2, "reason": None}- async def test_a_dropped_event_gap_is_confined_to_the_rooms_it_names(self) -> None:+ async def test_a_place_past_the_end_of_a_room_names_that_room(+ self, db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A place further than the room has ever reached is from a history the+ room no longer has (a restored database). Kept, it would pass over that+ many of the room's next messages without a word, so the stream starts+ the room at its end and says so."""registry = AgentConnectionRegistry()- buffer = EventBuffer(max_events_per_agent=1, sequence_base=0)- buffer.enqueue(AGENT, ROOM_A, _message("dropped"))- buffer.enqueue(AGENT, ROOM_A, _message("kept"))+ buffer = db_buffer+ earlier = await say(session_factory, ROOM_A, "earlier")+ conn = _open(registry, position={OWN_EVENTS: 0, room_source(ROOM_A): 4812})+ registry.claim_room(conn, ROOM_A)++ stream = event_frames(+ conn=conn, registry=registry, buffer=buffer, approvals=None+ )+ (_, (kind, gap)) = await _take(stream, 2)++ assert kind == "gap"+ assert gap["rooms"] == [ROOM_A]+ assert gap["all_rooms"] is False+ assert gap["resumed_position"][room_source(ROOM_A)] == earlier.seq++ # What is said next is delivered, not passed over.+ await say(session_factory, ROOM_A, "next")+ ((_, data),) = await _take(stream, 1)+ await stream.aclose()++ assert data["payload"]["body"] == "next"++ async def test_a_dropped_event_gap_is_confined_to_the_rooms_it_names(+ self, db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ registry = AgentConnectionRegistry()+ buffer = db_buffer+ await _keep(buffer, _message("dropped"))+ await age_events(session_factory, AGENT, seconds=2 * 3600)+ await buffer.expire(TENANT_ZERO_ID)+ await _keep(buffer, _message("kept"))conn = _open(registry, cursor=0)registry.claim_room(conn, ROOM_A)@@ -989,13 +1485,13 @@ class TestAGapNamesTheRoomsThatLostEvents:assert frames[1][1]["all_rooms"] is False-async def test_a_delivered_event_names_no_session() -> None:+async def test_a_delivered_event_names_no_session(db_buffer: EventBuffer) -> None:"""Routing a room's events to a session is the watcher's, from its own placements."""registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry, scope="all")registry.place_session(AGENT, "session-1", ROOM_A, conn.id)- buffer.enqueue(AGENT, ROOM_A, _message("hello"))+ await _keep(buffer, _message("hello"))stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None)(_, (name, data)) = await _take(stream, 2)@@ -1004,10 +1500,12 @@ async def test_a_delivered_event_names_no_session() -> None:assert "session_id" not in data-async def test_new_boot_reports_gap_and_keeps_messages_when_old_cursor_is_below_head():+async def test_new_boot_reports_gap_and_keeps_messages_when_old_cursor_is_below_head(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=2 << 32)- sequences = [buffer.enqueue(AGENT, ROOM_A, _message(str(i))) for i in range(3)]+ buffer = db_buffer_on(session_factory, sequence_base=2 << 32)+ sequences = [await _keep(buffer, _message(str(i))) for i in range(3)]conn = _open(registry, cursor=(1 << 32) + 2)registry.claim_room(conn, ROOM_A)frames = await _take(@@ -1018,17 +1516,20 @@ async def test_new_boot_reports_gap_and_keeps_messages_when_old_cursor_is_below_assert [frame[1]["sequence"] for frame in frames[2:]] == sequences-async def test_each_delivered_event_counts_as_an_agent_bridge_event_out() -> None:+async def test_each_delivered_event_counts_as_an_agent_bridge_event_out(+ db_buffer: EventBuffer, session_factory: async_sessionmaker[AsyncSession]+) -> None:registry_metrics = MetricsRegistry()install(registry_metrics)try:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)- conn = _open(registry)+ buffer = db_buffer+ conn = _open(registry, position={OWN_EVENTS: 0, room_source(ROOM_B): 0})registry.claim_room(conn, ROOM_A)registry.claim_room(conn, ROOM_B)- buffer.enqueue(AGENT, ROOM_A, _message("one"))- buffer.enqueue(AGENT, ROOM_B, _message("two", room=ROOM_B))+ await _keep(buffer, _message("one"))+ # The conversation, read from the room's log, counts the same.+ await say(session_factory, ROOM_B, "two")stream = event_frames(conn=conn, registry=registry, buffer=buffer, approvals=None@@ -1072,9 +1573,11 @@ class TestBothTransportsEncodeTheSameFrames:def test_the_keepalive_is_a_comment_on_the_event_stream(self) -> None:assert encode_sse(KEEPALIVE) == b": keepalive\n\n"- async def test_closing_the_event_stream_detaches_its_connection(self) -> None:+ async def test_closing_the_event_stream_detaches_its_connection(+ self, db_buffer: EventBuffer+ ) -> None:registry = AgentConnectionRegistry()- buffer = EventBuffer(sequence_base=0)+ buffer = db_bufferconn = _open(registry)body = sse_stream(diff --git a/core/tests/switch_core/bridges/agent/protocol/test_unread_counts.py b/core/tests/switch_core/bridges/agent/protocol/test_unread_counts.pyindex 4a98c963a..8c2a942d3 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_unread_counts.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_unread_counts.py@@ -1,17 +1,24 @@"""Per-room unread accounting held by the buffer rather than by each client.-The counts a reader is told are derived here, from events the buffer already-holds, and they are per room: catching up in one room says nothing about any-other. What a reader must never be handed is a confident zero it has no reason-to doubt, so the absence of a count is itself an answer.+The counts a reader is told are derived here, from the room's own log+(`messages`), and they are per room: catching up in one room says nothing about+any other. Where a room was last caught up, and who is reading it, are rows, so+a count reads the same from every process. What a reader must never be handed+is a confident zero it has no reason to doubt, so the absence of a count is+itself an answer."""from __future__ import annotations+from datetime import UTC, datetime, timedelta++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.attachments import ATTACHMENT_GROUP_KEYfrom switch_core.bridges.agent.protocol.event_buffer import (- COUNTED_FROM_A_HOLE,+ COUNTED_FROM_WINDOW,NO_BASELINE,- RESTARTED,EventBuffer,Reader,Unread,@@ -21,12 +28,40 @@ from switch_core.bridges.agent.protocol.types import (CommandPayload,MessagePayload,)+from switch_core.db.models import TENANT_ZERO_ID+from tests.db_buffer import (+ age_events,+ db_buffer_on,+ say,+ seed_agent,+ seed_room,+ sender_of,+)AGENT = "agent-1"READER = "connection-1"ROOM_A = "room-a"ROOM_B = "room-b"+SessionFactory = async_sessionmaker[AsyncSession]++[email protected](autouse=True)+async def _rows(session_factory: SessionFactory) -> None:+ """The agent counted for and the rooms it is counted in: a room's count is+ kept against the room's own row."""+ await seed_agent(session_factory, AGENT)+ await seed_room(session_factory, ROOM_A)+ await seed_room(session_factory, ROOM_B)+++async def _expire_everything_so_far(+ buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """Age out every event queued so far, recording the drops a reader is told of."""+ await age_events(session_factory, AGENT, seconds=2 * 3600)+ await buffer.expire(TENANT_ZERO_ID)+def _session(session_id: str) -> Reader:return Reader(id=session_id, is_session=True)@@ -36,130 +71,173 @@ def _connection(connection_id: str) -> Reader:return Reader(id=connection_id, is_session=False)-def _message(room: str, *, addressed: bool = False, body: str = "hi") -> AgentEvent:+async def _chatter(session_factory: SessionFactory, room: str, times: int = 1) -> int:+ """Messages nobody addressed to the agent. The room position of the last."""+ seq = 0+ for index in range(times):+ seq = (await say(session_factory, room, f"{room}-{index}")).seq+ return seq+++def _asked(room: str, message_id: str) -> AgentEvent:+ """The agent's own event for a message addressed to it."""return AgentEvent(type="message",room_id=room,payload=MessagePayload(- addressed=addressed,- sender="@u:s",- sender_name="u",- message_id=f"$m-{body}",- body=body,+ addressed=True,+ sender="@alice:test",+ sender_name="Alice",+ message_id=message_id,+ body="@agent over to you",timestamp=0,),)-def _chatter(buffer: EventBuffer, room: str, times: int = 1) -> int:- seq = 0- for index in range(times):- seq = buffer.enqueue(AGENT, room, _message(room, body=f"{room}-{index}"))- return seq+async def _addressed(+ buffer: EventBuffer, session_factory: SessionFactory, room: str+) -> int:+ """A message addressed to the agent, as its consumer keeps it: the row in+ the room's log, and the agent's own event for that row. The row's room+ position."""+ row = await say(session_factory, room, "@agent over to you")+ await buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT,+ room,+ _asked(room, row.transport_event_id),+ room_seq=row.seq,+ message_key=row.transport_event_id,+ )+ return row.seq+++def _part(group: str, index: int, total: int) -> dict[str, object]:+ """The content of one of several files posted as one message."""+ return {ATTACHMENT_GROUP_KEY: {"id": group, "index": index, "total": total}}+++async def _head(buffer: EventBuffer, room: str) -> int:+ return (await buffer.room_heads(TENANT_ZERO_ID, {room}))[room]++async def _unread(buffer: EventBuffer, room: str) -> Unread:+ """What the agent is behind by in `room`, through everything said there."""+ return await buffer.unread(TENANT_ZERO_ID, AGENT, room, await _head(buffer, room))-async def test_a_room_counts_only_its_own_chatter() -> None:- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- buffer.ensure_counting(AGENT, READER, ROOM_B, 0)- _chatter(buffer, ROOM_A, times=3)- head = buffer.head(AGENT)+async def _caught_up(+ buffer: EventBuffer, reader: Reader, room: str, arrived_on: str | None+) -> None:+ """`reader` has read `room` through everything said there so far."""+ await buffer.caught_up(+ TENANT_ZERO_ID, AGENT, reader, room, await _head(buffer, room), arrived_on+ )+++async def test_a_room_counts_only_its_own_chatter(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_B)- assert buffer.unread(AGENT, ROOM_A, head).count == 3- assert buffer.unread(AGENT, ROOM_B, head).count == 0+ await _chatter(session_factory, ROOM_A, times=3)+ assert (await _unread(buffer, ROOM_A)).count == 3+ assert (await _unread(buffer, ROOM_B)).count == 0-async def test_catching_up_on_one_room_leaves_the_others_alone() -> None:- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- buffer.ensure_counting(AGENT, READER, ROOM_B, 0)- _chatter(buffer, ROOM_A, times=2)- _chatter(buffer, ROOM_B, times=1)- head = buffer.head(AGENT)- buffer.caught_up(AGENT, _connection(READER), ROOM_A, head, READER)+async def test_catching_up_on_one_room_leaves_the_others_alone(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_B)+ await _chatter(session_factory, ROOM_A, times=2)+ await _chatter(session_factory, ROOM_B, times=1)- assert buffer.unread(AGENT, ROOM_A, head).count == 0- assert buffer.unread(AGENT, ROOM_B, head).count == 1+ await _caught_up(buffer, _connection(READER), ROOM_A, READER)+ assert (await _unread(buffer, ROOM_A)).count == 0+ assert (await _unread(buffer, ROOM_B)).count == 1-async def test_a_second_connection_does_not_start_the_room_over() -> None:++async def test_a_second_connection_does_not_start_the_room_over(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""A room has one count: the agent is behind by one amount there."""- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- _chatter(buffer, ROOM_A, times=2)- buffer.ensure_counting(AGENT, "connection-2", ROOM_A, buffer.head(AGENT))+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await _chatter(session_factory, ROOM_A, times=2)+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, "connection-2", ROOM_A)- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 2+ assert (await _unread(buffer, ROOM_A)).count == 2-async def test_the_connection_that_takes_a_room_over_can_clear_it() -> None:+async def test_the_connection_that_takes_a_room_over_can_clear_it(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""A room slot changes hands on the stream and the subscribe door too.Connecting is not the only way in. A connection that takes the room fromanother is the one told how far behind it is, so it has to be the one whose- reading clears it — otherwise it reads everything and is told nothing+ reading clears it, otherwise it reads everything and is told nothinghappened."""- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- _chatter(buffer, ROOM_A, times=3)+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await _chatter(session_factory, ROOM_A, times=3)- buffer.take_counting(AGENT, "connection-2", ROOM_A, buffer.head(AGENT))- buffer.caught_up(- AGENT, _connection("connection-2"), ROOM_A, buffer.head(AGENT), "connection-2"- )+ await buffer.take_counting(TENANT_ZERO_ID, AGENT, "connection-2", ROOM_A)+ await _caught_up(buffer, _connection("connection-2"), ROOM_A, "connection-2")- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 0+ assert (await _unread(buffer, ROOM_A)).count == 0-async def test_delivering_a_room_does_not_take_it_from_a_session() -> None:+async def test_delivering_a_room_does_not_take_it_from_a_session(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""One connection carries every session, so it is not the caller in any room."""- buffer = EventBuffer(sequence_base=0)- buffer.hand_counting_to(AGENT, _session("session-a"), ROOM_A)- _chatter(buffer, ROOM_A, times=2)+ buffer = db_buffer+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-a"), ROOM_A)+ await _chatter(session_factory, ROOM_A, times=2)- buffer.ensure_counting(AGENT, "connection-shared", ROOM_A, buffer.head(AGENT))- buffer.caught_up(- AGENT,- _connection("connection-shared"),- ROOM_A,- buffer.head(AGENT),- "connection-shared",+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, "connection-shared", ROOM_A)+ await _caught_up(+ buffer, _connection("connection-shared"), ROOM_A, "connection-shared")- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 2+ assert (await _unread(buffer, ROOM_A)).count == 2- buffer.caught_up(- AGENT, _session("session-a"), ROOM_A, buffer.head(AGENT), "connection-shared"- )- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 0+ await _caught_up(buffer, _session("session-a"), ROOM_A, "connection-shared")+ assert (await _unread(buffer, ROOM_A)).count == 0-async def test_taking_a_room_does_take_it_from_a_session() -> None:+async def test_taking_a_room_does_take_it_from_a_session(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""A takeover is not coverage: the session it displaced is out of the room.A legacy client taking the slot is told how far behind the room is, so its- reading has to clear it — being told 3 and reading all three and still+ reading has to clear it. Being told 3 and reading all three and stillbeing told 3 is the count losing its meaning."""- buffer = EventBuffer(sequence_base=0)- buffer.hand_counting_to(AGENT, _session("session-a"), ROOM_A)- _chatter(buffer, ROOM_A, times=3)+ buffer = db_buffer+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-a"), ROOM_A)+ await _chatter(session_factory, ROOM_A, times=3)- buffer.take_counting(AGENT, "connection-legacy", ROOM_A, buffer.head(AGENT))- buffer.caught_up(- AGENT,- _connection("connection-legacy"),- ROOM_A,- buffer.head(AGENT),- "connection-legacy",+ await buffer.take_counting(TENANT_ZERO_ID, AGENT, "connection-legacy", ROOM_A)+ await _caught_up(+ buffer, _connection("connection-legacy"), ROOM_A, "connection-legacy")- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 0+ assert (await _unread(buffer, ROOM_A)).count == 0-async def test_a_displaced_session_cannot_adopt_the_count_it_lost() -> None:+async def test_a_displaced_session_cannot_adopt_the_count_it_lost(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""The other half of a takeover: the session that was there keeps reading.Its read was begun before it lost the room and lands afterwards. A session@@ -167,221 +245,253 @@ async def test_a_displaced_session_cannot_adopt_the_count_it_lost() -> None:back to it, and the client that actually holds the slot would be told it iscaught up on messages it has never been shown."""- buffer = EventBuffer(sequence_base=0)- buffer.hand_counting_to(AGENT, _session("session-a"), ROOM_A)- _chatter(buffer, ROOM_A, times=3)- in_flight = buffer.head(AGENT)-- buffer.take_counting(AGENT, "connection-legacy", ROOM_A, in_flight)- buffer.caught_up(- AGENT, _connection("connection-legacy"), ROOM_A, in_flight, "connection-legacy"- )- _chatter(buffer, ROOM_A, times=2)+ buffer = db_buffer+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-a"), ROOM_A)+ in_flight = await _chatter(session_factory, ROOM_A, times=3)- buffer.caught_up(- AGENT, _session("session-a"), ROOM_A, buffer.head(AGENT), "connection-a"+ await buffer.take_counting(TENANT_ZERO_ID, AGENT, "connection-legacy", ROOM_A)+ await buffer.caught_up(+ TENANT_ZERO_ID,+ AGENT,+ _connection("connection-legacy"),+ ROOM_A,+ in_flight,+ "connection-legacy",)+ await _chatter(session_factory, ROOM_A, times=2)++ await _caught_up(buffer, _session("session-a"), ROOM_A, "connection-a")- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 2+ assert (await _unread(buffer, ROOM_A)).count == 2-async def test_a_session_adopts_a_count_opened_in_its_connections_name() -> None:- """A session recovering after a restart is not a stranger to its own room.+async def test_a_session_adopts_a_count_opened_in_its_connections_name(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """A session is not a stranger to a room its own connection is counting.- The stream reopens before the session says anything, so what is recorded is- the connection. The session reads, and its read has to land somewhere: held- to the letter, it would clear nothing and the room would answer "unknown"- for as long as the session lived.+ The stream covers the room before the session says anything, so what is+ recorded is the connection. The session reads, and its read has to land+ somewhere: held to the letter, it would clear nothing, and the count would+ only grow for as long as the session lived."""- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- buffer.mark_restarted(AGENT)- _chatter(buffer, ROOM_A, times=2)- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).reason == RESTARTED+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await _chatter(session_factory, ROOM_A, times=2)- buffer.caught_up(AGENT, _session("session-a"), ROOM_A, buffer.head(AGENT), READER)- _chatter(buffer, ROOM_A, times=1)+ await _caught_up(buffer, _session("session-a"), ROOM_A, READER)+ await _chatter(session_factory, ROOM_A, times=1)- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)) == Unread(- count=1, reason=None- )+ assert await _unread(buffer, ROOM_A) == Unread(count=1, reason=None)-async def test_a_read_by_the_session_that_lost_the_room_clears_nothing() -> None:+async def test_a_read_by_the_session_that_lost_the_room_clears_nothing(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""The reproduction: siblings share a connection, so it cannot say who read.A read is begun before its history arrives. Another session of the agent- taking the room in between comes back to a count of its own — one it has- not read a word of — and the displaced session's answer must not be+ taking the room in between comes back to a count of its own, one it has+ not read a word of, and the displaced session's answer must not becredited to it."""- buffer = EventBuffer(sequence_base=0)+ buffer = db_buffershared = "connection-shared"- buffer.ensure_counting(AGENT, shared, ROOM_A, 0)- buffer.hand_counting_to(AGENT, _session("session-a"), ROOM_A)- _chatter(buffer, ROOM_A, times=3)- in_flight = buffer.head(AGENT)-- buffer.hand_counting_to(AGENT, _session("session-b"), ROOM_A)- _chatter(buffer, ROOM_A, times=2)- buffer.caught_up(AGENT, _session("session-a"), ROOM_A, in_flight, shared)+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, shared, ROOM_A)+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-a"), ROOM_A)+ in_flight = await _chatter(session_factory, ROOM_A, times=3)++ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-b"), ROOM_A)+ await _chatter(session_factory, ROOM_A, times=2)+ await buffer.caught_up(+ TENANT_ZERO_ID, AGENT, _session("session-a"), ROOM_A, in_flight, shared+ )- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 5+ assert (await _unread(buffer, ROOM_A)).count == 5-async def test_the_session_that_took_the_room_still_clears_it() -> None:+async def test_the_session_that_took_the_room_still_clears_it(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""The fence is about who is in the room, not about refusing reads."""- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- buffer.hand_counting_to(AGENT, _session("session-a"), ROOM_A)- _chatter(buffer, ROOM_A, times=2)+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-a"), ROOM_A)+ await _chatter(session_factory, ROOM_A, times=2)- buffer.hand_counting_to(AGENT, _session("session-b"), ROOM_A)- buffer.caught_up(AGENT, _session("session-b"), ROOM_A, buffer.head(AGENT), READER)+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-b"), ROOM_A)+ await _caught_up(buffer, _session("session-b"), ROOM_A, READER)- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 0+ assert (await _unread(buffer, ROOM_A)).count == 0-async def test_taking_a_room_inherits_what_went_past_unread_in_it() -> None:+async def test_taking_a_room_inherits_what_went_past_unread_in_it(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""Chatter nobody read stays unread when the room changes hands."""- buffer = EventBuffer(sequence_base=0)- buffer.hand_counting_to(AGENT, _session("session-a"), ROOM_A)- _chatter(buffer, ROOM_A, times=4)+ buffer = db_buffer+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-a"), ROOM_A)+ await _chatter(session_factory, ROOM_A, times=4)- buffer.hand_counting_to(AGENT, _session("session-b"), ROOM_A)+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-b"), ROOM_A)- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 4+ assert (await _unread(buffer, ROOM_A)).count == 4-async def test_a_room_counted_for_the_first_time_counts_what_is_retained() -> None:- """Arriving somewhere new, the most that can be said is what we still hold."""- buffer = EventBuffer(sequence_base=0)- _chatter(buffer, ROOM_A, times=2)+async def test_a_room_counted_for_the_first_time_counts_what_is_retained(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """Arriving somewhere new, the most that can be said is the retention+ window: the stretch of conversation the agent's own events are kept for."""+ buffer = db_buffer+ await say(+ session_factory,+ ROOM_A,+ "before the window",+ sent_at=datetime.now(UTC) - timedelta(hours=2),+ )+ await _chatter(session_factory, ROOM_A, times=2)- buffer.hand_counting_to(AGENT, _session("session-a"), ROOM_A)+ await buffer.hand_counting_to(TENANT_ZERO_ID, AGENT, _session("session-a"), ROOM_A)- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 2+ assert (await _unread(buffer, ROOM_A)).count == 2-async def test_a_room_nothing_recorded_a_baseline_for_has_no_count() -> None:- buffer = EventBuffer(sequence_base=0)- _chatter(buffer, ROOM_A, times=2)+async def test_a_room_nothing_recorded_a_baseline_for_has_no_count(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ buffer = db_buffer+ await _chatter(session_factory, ROOM_A, times=2)- unread = buffer.unread(AGENT, ROOM_A, buffer.head(AGENT))+ unread = await _unread(buffer, ROOM_A)assert unread.count is Noneassert unread.reason == NO_BASELINE-async def test_a_baseline_survives_the_room_being_covered_or_taken_again() -> None:+async def test_a_baseline_survives_the_room_being_covered_or_taken_again(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""Neither door may quietly discard what the reader is behind by."""- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- _chatter(buffer, ROOM_A, times=2)+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await _chatter(session_factory, ROOM_A, times=2)- buffer.ensure_counting(AGENT, READER, ROOM_A, buffer.head(AGENT))- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 2+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ assert (await _unread(buffer, ROOM_A)).count == 2- buffer.take_counting(AGENT, "connection-2", ROOM_A, buffer.head(AGENT))- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 2+ await buffer.take_counting(TENANT_ZERO_ID, AGENT, "connection-2", ROOM_A)+ assert (await _unread(buffer, ROOM_A)).count == 2-async def test_a_restart_leaves_a_room_unknown_rather_than_at_zero() -> None:- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- buffer.mark_restarted(AGENT)- _chatter(buffer, ROOM_A, times=1)+async def test_a_restart_keeps_what_a_room_is_behind_by(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """Nothing about a room's count is held by the process that counted it.- unread = buffer.unread(AGENT, ROOM_A, buffer.head(AGENT))-- assert unread.count is None- assert unread.reason == RESTARTED-- # And it stays unknown until the reader actually catches up, rather than- # being repaired by the room changing hands.- buffer.take_counting(AGENT, "connection-2", ROOM_A, buffer.head(AGENT))- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count is None---async def test_a_restart_covers_rooms_it_could_not_have_named() -> None:- """The loss is the whole buffer, not the rooms a connection had claimed.-- A connection watching every room claims none of them, and the rooms its- sessions work in are claimed after it reconnects. Marking only what was- named at the time would answer those rooms with a fresh zero — the exact- confident zero the count exists not to hand out.+ Where the room was last caught up is a row, so a restarted server reads+ the same count rather than an unknown or a zero, and the stream covering+ the room again when it reconnects does not start it over."""- buffer = EventBuffer(sequence_base=0)- buffer.mark_restarted(AGENT)- _chatter(buffer, ROOM_A, times=2)- _chatter(buffer, ROOM_B, times=1)-- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- buffer.hand_counting_to(AGENT, _session("session-b"), ROOM_B)-- for room in (ROOM_A, ROOM_B):- unread = buffer.unread(AGENT, room, buffer.head(AGENT))- assert unread.count is None- assert unread.reason == RESTARTED---async def test_reading_a_room_after_a_restart_makes_it_countable_again() -> None:- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- buffer.mark_restarted(AGENT)- buffer.caught_up(AGENT, _connection(READER), ROOM_A, buffer.head(AGENT), READER)-- _chatter(buffer, ROOM_A, times=1)- unread = buffer.unread(AGENT, ROOM_A, buffer.head(AGENT))-- assert unread == Unread(count=1, reason=None)---async def test_a_count_that_lost_history_is_a_floor_in_that_room_only() -> None:- buffer = EventBuffer(max_events_per_agent=2, sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- buffer.ensure_counting(AGENT, READER, ROOM_B, 0)-- _chatter(buffer, ROOM_A, times=3)- _chatter(buffer, ROOM_B, times=1)- head = buffer.head(AGENT)-- lost = buffer.unread(AGENT, ROOM_A, head)- assert lost.count == 1- assert lost.reason == COUNTED_FROM_A_HOLE-- intact = buffer.unread(AGENT, ROOM_B, head)- assert intact.count == 1- assert intact.reason is None---async def test_catching_up_past_a_hole_makes_the_count_exact_again() -> None:- buffer = EventBuffer(max_events_per_agent=2, sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- _chatter(buffer, ROOM_A, times=3)-- buffer.caught_up(AGENT, _connection(READER), ROOM_A, buffer.head(AGENT), READER)- _chatter(buffer, ROOM_A, times=1)-- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).reason is None---async def test_a_drop_names_the_rooms_that_lost_events() -> None:- buffer = EventBuffer(max_events_per_agent=2, sequence_base=0)- _chatter(buffer, ROOM_A, times=2)- _chatter(buffer, ROOM_B, times=2)+ await db_buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await _chatter(session_factory, ROOM_A, times=2)++ restarted = db_buffer_on(session_factory)+ await restarted.ensure_counting(TENANT_ZERO_ID, AGENT, "connection-2", ROOM_A)++ assert await _unread(restarted, ROOM_A) == Unread(count=2, reason=None)+++async def test_catching_up_only_moves_forward(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """A read is begun before its history arrives, so an older answer can land+ after a newer one. It must not hand back what the newer one cleared."""+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ older = await _chatter(session_factory, ROOM_A, times=2)+ newer = await _chatter(session_factory, ROOM_A, times=1)++ reader = _connection(READER)+ await buffer.caught_up(TENANT_ZERO_ID, AGENT, reader, ROOM_A, newer, READER)+ await buffer.caught_up(TENANT_ZERO_ID, AGENT, reader, ROOM_A, older, READER)+ await _chatter(session_factory, ROOM_A, times=1)++ assert await _unread(buffer, ROOM_A) == Unread(count=1, reason=None)+++async def test_retention_never_takes_from_what_a_room_counts(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """The agent's own events age out; the conversation they are counted+ against does not. A room whose events were dropped is told of the gap on+ its stream, and its count is still the whole of what went past."""+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_B)++ await _chatter(session_factory, ROOM_A, times=2)+ await buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT,+ ROOM_A,+ AgentEvent(+ type="command",+ room_id=ROOM_A,+ payload=CommandPayload(command="reset", user_id="@u:s", user_name="u"),+ ),+ room_seq=0,+ message_key=None,+ )+ await _expire_everything_so_far(buffer, session_factory)+ await _chatter(session_factory, ROOM_A, times=1)+ await _chatter(session_factory, ROOM_B, times=1)++ assert await buffer.rooms_dropped_after(TENANT_ZERO_ID, AGENT, 0) == (ROOM_A,)+ assert await _unread(buffer, ROOM_A) == Unread(count=3, reason=None)+ assert await _unread(buffer, ROOM_B) == Unread(count=1, reason=None)+++async def test_a_drop_names_the_rooms_that_lost_events(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ buffer = db_buffer+ await _addressed(buffer, session_factory, ROOM_A)+ await _addressed(buffer, session_factory, ROOM_A)+ await _expire_everything_so_far(buffer, session_factory)+ await _addressed(buffer, session_factory, ROOM_B)+ await _addressed(buffer, session_factory, ROOM_B)++ assert await buffer.rooms_dropped_after(TENANT_ZERO_ID, AGENT, 0) == (ROOM_A,)+ assert (+ await buffer.rooms_dropped_after(+ TENANT_ZERO_ID, AGENT, await buffer.head(TENANT_ZERO_ID, AGENT)+ )+ == ()+ )- assert buffer.rooms_dropped_after(AGENT, 0) == (ROOM_A,)- assert buffer.rooms_dropped_after(AGENT, buffer.head(AGENT)) == ()+async def test_only_unaddressed_messages_are_counted(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """The count exists to say what the reader was not woken for.-async def test_only_unaddressed_messages_are_counted() -> None:- """The count exists to say what the reader was not woken for."""- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)+ A message addressed to the agent woke it, a command is not conversation,+ and what the agent said itself it cannot have missed.+ """+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)- buffer.enqueue(AGENT, ROOM_A, _message(ROOM_A, addressed=True))- buffer.enqueue(+ await _addressed(buffer, session_factory, ROOM_A)+ command = await say(+ session_factory,+ ROOM_A,+ "!reset",+ event_type="com.switch.command",+ content={"command": "reset", "args": ""},+ )+ await buffer.enqueue(+ TENANT_ZERO_ID,AGENT,ROOM_A,AgentEvent(@@ -389,29 +499,73 @@ async def test_only_unaddressed_messages_are_counted() -> None:room_id=ROOM_A,payload=CommandPayload(command="reset", user_id="@u:s", user_name="u"),),+ room_seq=command.seq,+ message_key=command.transport_event_id,+ )+ await say(+ session_factory,+ ROOM_A,+ "on it",+ sender=await sender_of(session_factory, AGENT),+ )+ await _chatter(session_factory, ROOM_A)++ assert (await _unread(buffer, ROOM_A)).count == 1+++async def test_several_files_posted_as_one_message_count_once(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """Files posted together are a row each in the room's log, and one message+ to whoever posted them, so they are one message missed. Addressed to the+ agent, they are not missed at all."""+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)++ for index in range(3):+ await say(session_factory, ROOM_A, "chart", content=_part("posted", index, 3))+ # The agent's consumer keeps a group addressed to it as one event, under+ # the group's id, once its last part is in.+ for index in range(2):+ last = await say(+ session_factory, ROOM_A, "brief", content=_part("asked", index, 2)+ )+ await buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT,+ ROOM_A,+ _asked(ROOM_A, "asked"),+ room_seq=last.seq,+ message_key="asked",)- buffer.enqueue(AGENT, ROOM_A, _message(ROOM_A))- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 1+ assert (await _unread(buffer, ROOM_A)).count == 1-async def test_a_count_stops_at_the_event_it_is_reported_alongside() -> None:+async def test_a_count_stops_at_the_event_it_is_reported_alongside(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:"""Chatter that arrived after the woken-for event is not yet its business."""- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- _chatter(buffer, ROOM_A, times=2)- addressed = buffer.enqueue(AGENT, ROOM_A, _message(ROOM_A, addressed=True))- _chatter(buffer, ROOM_A, times=5)-- assert buffer.unread(AGENT, ROOM_A, addressed).count == 2---async def test_dropping_a_reader_leaves_the_room_behind_by_what_it_was() -> None:- """A reader going away is not the conversation it missed being read."""- buffer = EventBuffer(sequence_base=0)- buffer.ensure_counting(AGENT, READER, ROOM_A, 0)- _chatter(buffer, ROOM_A, times=1)-- buffer.drop_reader(AGENT, READER)-- assert buffer.unread(AGENT, ROOM_A, buffer.head(AGENT)).count == 1+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ await _chatter(session_factory, ROOM_A, times=2)+ addressed = await _addressed(buffer, session_factory, ROOM_A)+ await _chatter(session_factory, ROOM_A, times=5)++ assert (await buffer.unread(TENANT_ZERO_ID, AGENT, ROOM_A, addressed)).count == 2+++async def test_a_room_not_caught_up_on_for_longer_than_the_window_counts_over_it(+ db_buffer: EventBuffer, session_factory: SessionFactory+) -> None:+ """Past the retention window the agent's own events are gone, so a message+ addressed to it there could no longer be told from chatter and would be+ counted as missed. The count stops at the window and says it is a floor."""+ buffer = db_buffer+ await buffer.ensure_counting(TENANT_ZERO_ID, AGENT, READER, ROOM_A)+ long_ago = datetime.now(UTC) - timedelta(hours=2)+ await say(session_factory, ROOM_A, "@agent over to you", sent_at=long_ago)+ await say(session_factory, ROOM_A, "old chatter", sent_at=long_ago)+ await _chatter(session_factory, ROOM_A, times=2)++ assert await _unread(buffer, ROOM_A) == Unread(count=2, reason=COUNTED_FROM_WINDOW)diff --git a/core/tests/switch_core/bridges/agent/test_control_commands.py b/core/tests/switch_core/bridges/agent/test_control_commands.pyindex 52025963d..51506446b 100644--- a/core/tests/switch_core/bridges/agent/test_control_commands.py+++ b/core/tests/switch_core/bridges/agent/test_control_commands.py@@ -84,6 +84,10 @@ def _client() -> None:return None+ async def _enqueue(*a: Any, **k: Any) -> int:+ enqueue.append((a, k))+ return len(enqueue)+return SimpleNamespace(agent=agent,_fresh_agent=_fresh_agent,@@ -100,7 +104,7 @@ def _client(session_in_room=lambda _agent, _room: placed,relay_session_command=_relay,),- _event_buffer=SimpleNamespace(enqueue=lambda *a, **k: enqueue.append((a, k))),+ _event_buffer=SimpleNamespace(enqueue=_enqueue),)@@ -195,6 +199,8 @@ async def test_live_capable_session_acks_and_enqueues(assert len(reply.bodies) == 1assert "Resetting my session" in reply.bodies[0]assert len(enqueue) == 1+ # Queued in the agent's own tenant, which the buffer now takes first.+ assert enqueue[0][0][:3] == ("tenant-1", "agent-1", "room-1")# ── Admin-side usage feedback (_check_control_target) ─────────────────────────diff --git a/core/tests/switch_core/clients/test_agent_consumer_attachment_groups.py b/core/tests/switch_core/clients/test_agent_consumer_attachment_groups.pyindex cc8813d66..d902b58af 100644--- a/core/tests/switch_core/clients/test_agent_consumer_attachment_groups.py+++ b/core/tests/switch_core/clients/test_agent_consumer_attachment_groups.py@@ -6,11 +6,26 @@ from types import SimpleNamespacefrom typing import Anyimport pytest+from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerimport switch_core.clients.agent_consumer as ac+from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.types import AgentEventfrom switch_core.clients.agent_consumer import AgentConsumer, _GateOutcomefrom switch_core.clients.room_meta import RoomMeta+from switch_core.db.models import TENANT_ZERO_ID, AgentEventRow+from switch_core.db.session_scope import tenant_sessionfrom switch_core.transport import InboundMedia, RoomRef+from tests.db_buffer import seed_agent++AGENT = "agent-1"++[email protected](autouse=True)+async def _agent_row(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent the consumer queues for, so its events have a row to belong to."""+ await seed_agent(session_factory, AGENT)def _media_event(@@ -21,6 +36,7 @@ def _media_event(msgtype: str = "m.image",group: dict[str, Any] | None = None,event_id: str = "$evt",+ seq: int = 0,) -> InboundMedia:content: dict[str, Any] = {"msgtype": msgtype,@@ -47,6 +63,7 @@ def _media_event(mimetype=mimetype,size=5,group=group,+ seq=seq,)@@ -64,16 +81,18 @@ class _FakeMessageTelemetry:self.addressed.append(kwargs)-class _FakeQueue:- def __init__(self) -> None:- self.events: list[Any] = []+async def _events(client: SimpleNamespace) -> list[AgentEvent]:+ """What the consumer queued for its agent, read back from the db-buffer.- def enqueue(self, _agent_id: str, _room_id: str, event: Any) -> None:- self.events.append(event)+ Only what is for the agent is queued; the rest of the room is read from+ the room's log by whoever wants it. So a test about what a post becomes+ addresses the post to the agent, in its caption (part 0's body).+ """+ buffer: EventBuffer = client._event_buffer+ return [item.event for item in await buffer.read_from(TENANT_ZERO_ID, AGENT, 0)]-def _fake_client() -> SimpleNamespace:- queue = _FakeQueue()+def _fake_client(buffer: EventBuffer) -> SimpleNamespace:meta = RoomMeta(room_id="room-1", name="Room", bridge_id="bridge-1")async def _resolve_room_meta(_transport_room_id: str) -> RoomMeta:@@ -99,10 +118,10 @@ def _fake_client() -> SimpleNamespace:return Truens = SimpleNamespace(- agent=SimpleNamespace(id="agent-1", name="agent-a", metadata_=None),- tenant_id="tenant-1",+ agent=SimpleNamespace(id=AGENT, name="agent-a", metadata_=None),+ tenant_id=TENANT_ZERO_ID,session_factory=_session_factory,- _event_buffer=queue,+ _event_buffer=buffer,_message_telemetry=_FakeMessageTelemetry(),_triggered_by_auto_reply=AgentConsumer._triggered_by_auto_reply,_attachment_groups={},@@ -113,7 +132,6 @@ def _fake_client() -> SimpleNamespace:_gate_addressed=_gate_addressed,_is_available=_is_available,availability_checks=0,- queue=queue,)ns._emit_media = AgentConsumer._emit_media.__get__(ns)ns._report_addressed = AgentConsumer._report_addressed.__get__(ns)@@ -133,8 +151,8 @@ def _room() -> RoomRef:return RoomRef(room_id="!room:s")-async def test_grouped_media_coalesces_into_one_event() -> None:- client = _fake_client()+async def test_grouped_media_coalesces_into_one_event(db_buffer: EventBuffer) -> None:+ client = _fake_client(db_buffer)parts = [("cat.png", "image/png", "m.image"),("notes.md", "text/markdown", "m.file"),@@ -146,7 +164,7 @@ async def test_grouped_media_coalesces_into_one_event() -> None:client,_room(),_media_event(- body="three files" if index == 0 else name,+ body="@agent-a three files" if index == 0 else name,filename=name if index == 0 else None,mimetype=mimetype,msgtype=msgtype,@@ -155,22 +173,22 @@ async def test_grouped_media_coalesces_into_one_event() -> None:),)if index < 2:- assert client.queue.events == []+ assert await _events(client) == []- assert len(client.queue.events) == 1- payload = client.queue.events[0].payload+ assert len(await _events(client)) == 1+ payload = (await _events(client))[0].payloadassert [a.filename for a in payload.attachments] == ["cat.png","notes.md","data.csv",]- assert payload.body == "three files"+ assert payload.body == "@agent-a three files"assert client._attachment_groups == {}assert client._attachment_group_timers == {}-async def test_grouped_media_coalesces_out_of_order() -> None:- client = _fake_client()+async def test_grouped_media_coalesces_out_of_order(db_buffer: EventBuffer) -> None:+ client = _fake_client(db_buffer)order = [1, 0, 2]names = {0: "a.png", 1: "b.png", 2: "c.png"}@@ -179,61 +197,100 @@ async def test_grouped_media_coalesces_out_of_order() -> None:client,_room(),_media_event(- body="captioned" if index == 0 else names[index],+ body="@agent-a captioned" if index == 0 else names[index],filename=names[index] if index == 0 else None,event_id=f"$part-{index}",group={"id": "grp-2", "index": index, "total": 3},),)- assert len(client.queue.events) == 1- payload = client.queue.events[0].payload+ assert len(await _events(client)) == 1+ payload = (await _events(client))[0].payload# Sorted by group index, not arrival order.assert [a.filename for a in payload.attachments] == ["a.png", "b.png", "c.png"]- assert payload.body == "captioned"+ assert payload.body == "@agent-a captioned"assert client._attachment_groups == {}assert client._attachment_group_timers == {}-async def test_ungrouped_media_emits_immediately() -> None:- client = _fake_client()+async def test_a_group_is_kept_as_the_one_message_it_was_posted_as(+ session_factory: async_sessionmaker[AsyncSession], db_buffer: EventBuffer+) -> None:+ """Each part is a row of its own in the room's log, and the conversation+ read from there leaves out a row whose message the agent already has, by+ the id the message is known by: for a part, its group's. So the group is+ kept under the group's id, at the part furthest on in the room. Kept under+ one part's id, the other parts would reach the agent again as+ conversation."""+ client = _fake_client(db_buffer)+ # The part that completes the group is not the furthest on.+ for index, seq in [(0, 11), (2, 13), (1, 12)]:+ await AgentConsumer.on_media(+ client,+ _room(),+ _media_event(+ body="@agent-a three" if index == 0 else f"f{index}.png",+ filename="f0.png" if index == 0 else None,+ event_id=f"$part-{index}",+ group={"id": "grp-key", "index": index, "total": 3},+ seq=seq,+ ),+ )++ async with tenant_session(session_factory, TENANT_ZERO_ID) as session:+ kept = (+ await session.execute(+ select(AgentEventRow.room_seq, AgentEventRow.message_key).where(+ AgentEventRow.agent_id == AGENT+ )+ )+ ).all()+ assert [tuple(row) for row in kept] == [(13, "grp-key")]+++async def test_ungrouped_media_emits_immediately(db_buffer: EventBuffer) -> None:+ client = _fake_client(db_buffer)await AgentConsumer.on_media(- client, _room(), _media_event(body="cat.png", mimetype="image/png")+ client,+ _room(),+ _media_event(body="@agent-a a cat", filename="cat.png", mimetype="image/png"),)- assert len(client.queue.events) == 1- payload = client.queue.events[0].payload+ assert len(await _events(client)) == 1+ payload = (await _events(client))[0].payloadassert [a.filename for a in payload.attachments] == ["cat.png"]- assert payload.body == "cat.png"+ assert payload.body == "@agent-a a cat"assert client._attachment_groups == {}assert client._attachment_group_timers == {}-async def test_incomplete_group_flushes_with_disclosed_notice() -> None:+async def test_incomplete_group_flushes_with_disclosed_notice(+ db_buffer: EventBuffer,+) -> None:original = ac.ATTACHMENT_GROUP_TIMEOUT_SECONDSac.ATTACHMENT_GROUP_TIMEOUT_SECONDS = 0.01try:- client = _fake_client()+ client = _fake_client(db_buffer)for index, name in [(0, "cat.png"), (1, "notes.md")]:await AgentConsumer.on_media(client,_room(),_media_event(- body="two of three" if index == 0 else name,+ body="@agent-a two of three" if index == 0 else name,filename=name if index == 0 else None,event_id=f"$part-{index}",group={"id": "grp-3", "index": index, "total": 3},),)- assert client.queue.events == []+ assert await _events(client) == []await asyncio.sleep(0.15)finally:ac.ATTACHMENT_GROUP_TIMEOUT_SECONDS = original- assert len(client.queue.events) == 1- payload = client.queue.events[0].payload+ assert len(await _events(client)) == 1+ payload = (await _events(client))[0].payloadassert [a.filename for a in payload.attachments] == ["cat.png", "notes.md"]assert "two of three" in payload.bodyassert "incomplete attachment group: 2 of 3" in payload.body@@ -242,10 +299,12 @@ async def test_incomplete_group_flushes_with_disclosed_notice() -> None:assert client._attachment_group_timers == {}-async def test_group_is_anchored_on_part_zero_not_the_completing_part() -> None:+async def test_group_is_anchored_on_part_zero_not_the_completing_part(+ db_buffer: EventBuffer,+) -> None:"""The coalesced message must carry part 0's event id, so a reply threadsoff the canonical first event rather than whichever part landed last."""- client = _fake_client()+ client = _fake_client(db_buffer)# Part 0 arrives FIRST, so a later part completes the group — otherwise the# completing event happens to be part 0 and the assertion proves nothing.for index, name in [(0, "a.png"), (1, "b.md"), (2, "c.csv")]:@@ -253,29 +312,31 @@ async def test_group_is_anchored_on_part_zero_not_the_completing_part() -> None:client,_room(),_media_event(- body="three" if index == 0 else name,+ body="@agent-a three" if index == 0 else name,filename=name if index == 0 else None,event_id=f"$part-{index}",group={"id": "grp-anchor", "index": index, "total": 3},),)- assert len(client.queue.events) == 1+ assert len(await _events(client)) == 1# Part 2 completed the group, but part 0 anchors the payload.- assert client.queue.events[0].payload.message_id == "$part-0"+ assert (await _events(client))[0].payload.message_id == "$part-0"-async def test_incomplete_group_is_anchored_on_part_zero() -> None:+async def test_incomplete_group_is_anchored_on_part_zero(+ db_buffer: EventBuffer,+) -> None:original = ac.ATTACHMENT_GROUP_TIMEOUT_SECONDSac.ATTACHMENT_GROUP_TIMEOUT_SECONDS = 0.01try:- client = _fake_client()+ client = _fake_client(db_buffer)for index, name in [(0, "a.png"), (2, "c.csv")]:await AgentConsumer.on_media(client,_room(),_media_event(- body="anchored" if index == 0 else name,+ body="@agent-a anchored" if index == 0 else name,filename=name if index == 0 else None,event_id=f"$part-{index}",group={"id": "grp-anchor-2", "index": index, "total": 3},@@ -285,12 +346,12 @@ async def test_incomplete_group_is_anchored_on_part_zero() -> None:finally:ac.ATTACHMENT_GROUP_TIMEOUT_SECONDS = original- assert len(client.queue.events) == 1- assert client.queue.events[0].payload.message_id == "$part-0"+ assert len(await _events(client)) == 1+ assert (await _events(client))[0].payload.message_id == "$part-0"async def test_group_timeout_bounds_the_group_not_the_gap_between_parts(- monkeypatch: Any,+ monkeypatch: Any, db_buffer: EventBuffer) -> None:"""The safety-net timer is armed once per group. A batch dribbling in justunder the timeout must not be able to hold the buffer open indefinitely.@@ -310,12 +371,12 @@ async def test_group_timeout_bounds_the_group_not_the_gap_between_parts(return SimpleNamespace(cancel=lambda: None)monkeypatch.setattr(asyncio.get_running_loop(), "call_later", call_later)- client = _fake_client()+ client = _fake_client(db_buffer)await AgentConsumer.on_media(client,_room(),_media_event(- body="slow batch",+ body="@agent-a slow batch",filename="a.png",event_id="$part-0",group={"id": "grp-slow", "index": 0, "total": 4},@@ -344,8 +405,8 @@ async def test_group_timeout_bounds_the_group_not_the_gap_between_parts(await asyncio.gather(*(asyncio.all_tasks() - running))# Fired on the group's own deadline rather than being extended forever.- assert len(client.queue.events) == 1- payload = client.queue.events[0].payload+ assert len(await _events(client)) == 1+ payload = (await _events(client))[0].payloadassert "incomplete attachment group: 3 of 4" in payload.bodyassert client._attachment_groups == {}assert client._attachment_group_timers == {}@@ -361,8 +422,10 @@ class TestAddressingSurvivesCoalescing:consumer, correctly, ignored it."""- async def test_a_mention_on_part_zero_addresses_the_whole_group(self) -> None:- client = _fake_client()+ async def test_a_mention_on_part_zero_addresses_the_whole_group(+ self, db_buffer: EventBuffer+ ) -> None:+ client = _fake_client(db_buffer)for index, name in [(0, "one.png"), (1, "two.png")]:await AgentConsumer.on_media(client,@@ -375,16 +438,18 @@ class TestAddressingSurvivesCoalescing:),)- assert len(client.queue.events) == 1- payload = client.queue.events[0].payload+ assert len(await _events(client)) == 1+ payload = (await _events(client))[0].payloadassert payload.addressed is True# The text travels with the images rather than being left on the part# it arrived on.assert payload.body == "@agent-a look at these"assert [a.filename for a in payload.attachments] == ["one.png", "two.png"]- async def test_it_holds_when_the_captioned_part_arrives_last(self) -> None:- client = _fake_client()+ async def test_it_holds_when_the_captioned_part_arrives_last(+ self, db_buffer: EventBuffer+ ) -> None:+ client = _fake_client(db_buffer)for index, name in [(1, "two.png"), (0, "one.png")]:await AgentConsumer.on_media(client,@@ -397,11 +462,15 @@ class TestAddressingSurvivesCoalescing:),)- assert client.queue.events[0].payload.addressed is True+ assert (await _events(client))[0].payload.addressed is True- async def test_a_group_that_mentions_nobody_stays_unaddressed(self) -> None:- # The fix must carry addressing across the group, not assert it.- client = _fake_client()+ async def test_a_group_that_mentions_nobody_stays_unaddressed(+ self, db_buffer: EventBuffer+ ) -> None:+ # The fix must carry addressing across the group, not assert it. A+ # group for nobody is the room's conversation, so nothing is queued for+ # the agent: it is read from the room's log by a reader that wants it.+ client = _fake_client(db_buffer)for index, name in [(0, "one.png"), (1, "two.png")]:await AgentConsumer.on_media(client,@@ -414,15 +483,18 @@ class TestAddressingSurvivesCoalescing:),)- assert client.queue.events[0].payload.addressed is False+ assert await _events(client) == []+ assert client._attachment_groups == {}- async def test_an_incomplete_group_is_still_addressed(self) -> None:+ async def test_an_incomplete_group_is_still_addressed(+ self, db_buffer: EventBuffer+ ) -> None:# A batch that never completes is delivered by the safety net, and# losing a file is no reason to also lose who it was for.original = ac.ATTACHMENT_GROUP_TIMEOUT_SECONDSac.ATTACHMENT_GROUP_TIMEOUT_SECONDS = 0.01try:- client = _fake_client()+ client = _fake_client(db_buffer)await AgentConsumer.on_media(client,_room(),@@ -446,25 +518,29 @@ class TestAddressingSurvivesCoalescing:finally:ac.ATTACHMENT_GROUP_TIMEOUT_SECONDS = original- assert len(client.queue.events) == 1- payload = client.queue.events[0].payload+ assert len(await _events(client)) == 1+ payload = (await _events(client))[0].payloadassert payload.addressed is Trueassert "@agent-a two of three" in payload.body- async def test_a_single_attachment_is_unaffected(self) -> None:+ async def test_a_single_attachment_is_unaffected(+ self, db_buffer: EventBuffer+ ) -> None:# One screenshot always worked; it takes no group and no buffering.- client = _fake_client()+ client = _fake_client(db_buffer)await AgentConsumer.on_media(client, _room(), _media_event(body="@agent-a one picture"))- assert client.queue.events[0].payload.addressed is True+ assert (await _events(client))[0].payload.addressed is True-async def test_a_grouped_post_addressed_to_the_agent_is_reported_once() -> None:+async def test_a_grouped_post_addressed_to_the_agent_is_reported_once(+ db_buffer: EventBuffer,+) -> None:"""Three files in one post are one message asked of the agent, not three:the report follows the coalesced payload, not the parts."""- client = _fake_client()+ client = _fake_client(db_buffer)for index in range(3):await AgentConsumer.on_media(client,@@ -478,7 +554,7 @@ async def test_a_grouped_post_addressed_to_the_agent_is_reported_once() -> None:assert client._message_telemetry.addressed == [{- "tenant_id": "tenant-1",+ "tenant_id": TENANT_ZERO_ID,"room_id": "room-1","sender_transport_user_id": "@alice:s","from_platform": False,@@ -490,14 +566,16 @@ async def test_a_grouped_post_addressed_to_the_agent_is_reported_once() -> None:@pytest.mark.parametrize("late_index", [0, 2])-async def test_a_post_split_by_the_timeout_is_reported_once(late_index: int) -> None:+async def test_a_post_split_by_the_timeout_is_reported_once(+ late_index: int, db_buffer: EventBuffer+) -> None:"""A group that times out incomplete is delivered again when the restarrives. In a direct room both pieces address the agent, but it is onepost: counted with its first part, as the transport counts it."""original = ac.ATTACHMENT_GROUP_TIMEOUT_SECONDSac.ATTACHMENT_GROUP_TIMEOUT_SECONDS = 0.01try:- client = _fake_client()+ client = _fake_client(db_buffer)async def _direct_room(_event: Any, _meta: RoomMeta) -> bool:return True@@ -519,24 +597,28 @@ async def test_a_post_split_by_the_timeout_is_reported_once(late_index: int) ->finally:ac.ATTACHMENT_GROUP_TIMEOUT_SECONDS = original- assert len(client.queue.events) == 2+ assert len(await _events(client)) == 2assert len(client._message_telemetry.addressed) == 1-async def test_media_skips_the_availability_check_while_telemetry_is_off() -> None:+async def test_media_skips_the_availability_check_while_telemetry_is_off(+ db_buffer: EventBuffer,+) -> None:"""The media path reads it only to report it, so off means no query."""- client = _fake_client()+ client = _fake_client(db_buffer)client._message_telemetry.enabled = Falseawait AgentConsumer.on_media(client, _room(), _media_event(body="@agent-a look", event_id="$solo"))assert client.availability_checks == 0- assert len(client.queue.events) == 1+ assert len(await _events(client)) == 1-async def test_media_that_does_not_address_the_agent_is_not_reported() -> None:- client = _fake_client()+async def test_media_that_does_not_address_the_agent_is_not_reported(+ db_buffer: EventBuffer,+) -> None:+ client = _fake_client(db_buffer)await AgentConsumer.on_media(client, _room(), _media_event(body="just a picture", event_id="$solo"))diff --git a/core/tests/switch_core/clients/test_agent_consumer_pool_checkouts.py b/core/tests/switch_core/clients/test_agent_consumer_pool_checkouts.pyindex b43fee430..b8de4aff9 100644--- a/core/tests/switch_core/clients/test_agent_consumer_pool_checkouts.py+++ b/core/tests/switch_core/clients/test_agent_consumer_pool_checkouts.py@@ -7,9 +7,13 @@ turned one Slack message into twenty concurrent checkouts out of forty, and theaddressed client alone took up to nine more. That is the burst that pushed thepool to its ceiling and started failing heartbeats.-The contract is one checkout per client per message, and none at all for a-message that needs no lookup — plus, as with the room service, no session held-open while the client posts to Matrix.+The contract is one lookup checkout per client per message, and none at all+for a message that needs no lookup — plus, as with the room service, no session+held open while the client posts to Matrix. Queuing a message for the agent it+addresses is one more, its own short transaction on the db-buffer, taken after+the lookup has returned its connection rather than alongside it. Nothing else+is queued: the rest of the room is read from the room's log by whoever wants+it, so a client that is not addressed writes nothing."""from __future__ import annotations@@ -34,9 +38,15 @@ from switch_core.db.stores.room_role_store import RoomRoleStorefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.delivery.addressing import AddressingResolverfrom switch_core.transport import InboundMessage, RoomRef+from tests.db_buffer import db_buffer_onTRANSPORT_ROOM_ID = "!r:test"+# The db-buffer's write, in a transaction of its own: made only by the client+# whose agent the message addresses. Chatter, a message for somebody else and a+# refused one stay in the room's log and cost the client no write.+ENQUEUE = 1+class _CountingSessionFactory:"""The real factory, counting sessions opened and tracking how many are@@ -46,6 +56,7 @@ class _CountingSessionFactory:self._inner = innerself.opened = 0self.live = 0+ self.peak = 0def __call__(self) -> Any:self.opened += 1@@ -59,6 +70,7 @@ class _Tracked:async def __aenter__(self) -> AsyncSession:self._tracker.live += 1+ self._tracker.peak = max(self._tracker.peak, self._tracker.live)return await self._inner.__aenter__() # type: ignore[no-any-return]async def __aexit__(self, *exc: object) -> bool:@@ -163,9 +175,7 @@ def _client(return "$sent"actor.send_message = _send_message # type: ignore[assignment, method-assign]- client._event_buffer = SimpleNamespace( # type: ignore[assignment]- enqueue=lambda *_a, **_k: None- )+ client._event_buffer = db_buffer_on(counting) # type: ignore[arg-type]return client@@ -191,7 +201,8 @@ class TestInboundMessageCheckouts:) -> None:# The common case in a busy room, and the one multiplied by every agent# in it: no `@`, so there is nothing an alias or a role lease could- # match and no reason to touch the database at all.+ # match and no lookup to make. Nor is it queued: it addresses nobody,+ # so it is the room's conversation, read from the room's log.room_id, agents = await _seed(session_factory, names=["member"])counting = _CountingSessionFactory(session_factory)client = _client(counting, agents["member"], room_id)@@ -200,10 +211,11 @@ class TestInboundMessageCheckouts:assert counting.opened == 0- async def test_an_at_message_for_somebody_else_costs_one(+ async def test_an_at_message_for_somebody_else_costs_one_lookup(self, session_factory: async_sessionmaker[AsyncSession]) -> None:- # Was two: the room alias and the role lease each took a session.+ # Was two: the room alias and the role lease each took a session. The+ # lookup finds the message is not for this agent, so nothing is queued.room_id, agents = await _seed(session_factory, names=["member", "other"])counting = _CountingSessionFactory(session_factory)client = _client(counting, agents["member"], room_id)@@ -212,7 +224,7 @@ class TestInboundMessageCheckouts:assert counting.opened == 1- async def test_being_addressed_and_offline_still_costs_one(+ async def test_being_addressed_and_offline_still_costs_one_lookup(self, session_factory: async_sessionmaker[AsyncSession]) -> None:# The expensive path: addressing policy, liveness, and the whole@@ -223,7 +235,7 @@ class TestInboundMessageCheckouts:await client.on_message(_room(), _message("@member can you look at this"))- assert counting.opened == 1+ assert counting.opened == 1 + ENQUEUEassert len(client.sent) == 1 # type: ignore[attr-defined]async def test_no_session_is_open_while_the_auto_reply_is_posted(@@ -240,7 +252,7 @@ class TestInboundMessageCheckouts:assert [live for _body, live in client.sent] == [0] # type: ignore[attr-defined]- async def test_a_restricted_agent_refusing_a_sender_costs_one(+ async def test_a_restricted_agent_refusing_a_sender_costs_one_lookup(self, session_factory: async_sessionmaker[AsyncSession]) -> None:room_id, agents = await _seed(session_factory, names=["member"])@@ -256,10 +268,11 @@ class TestInboundMessageCheckouts:await client.on_message(_room(), _message("@member you there?"))+ # The refusal leaves the message as chatter, so nothing is queued.assert counting.opened == 1assert [live for _body, live in client.sent] == [0] # type: ignore[attr-defined]- async def test_an_alias_tag_costs_one(+ async def test_an_alias_tag_costs_one_lookup(self, session_factory: async_sessionmaker[AsyncSession]) -> None:# Reached only after the alias lookup misses on name, so this is the@@ -273,15 +286,17 @@ class TestInboundMessageCheckouts:await client.on_message(_room(), _message("@fixer please look"))- assert counting.opened == 1+ assert counting.opened == 1 + ENQUEUEassert len(client.sent) == 1 # type: ignore[attr-defined]- async def test_a_ten_agent_room_costs_ten(+ async def test_a_ten_agent_room_costs_ten_lookups(self, session_factory: async_sessionmaker[AsyncSession]) -> None:# The burst, end to end. One message, every client in the room handling- # it at once: ten slots out of forty, where it used to be twenty plus- # the addressed client's own handful.+ # it at once: ten lookups, where it used to be twenty plus the addressed+ # client's own handful. Only the client the message addresses queues+ # it for its agent, after its lookup has let go, so it never holds two+ # slots; the other nine leave it in the room's log.names = [f"a{i}" for i in range(10)]room_id, agents = await _seed(session_factory, names=names)counting = _CountingSessionFactory(session_factory)@@ -290,4 +305,5 @@ class TestInboundMessageCheckouts:for client in clients:await client.on_message(_room(), _message("@a3 can you take this"))- assert counting.opened == 10+ assert counting.opened == 10 + ENQUEUE+ assert counting.peak == 1diff --git a/core/tests/switch_core/clients/test_agent_consumer_reports_addressed.py b/core/tests/switch_core/clients/test_agent_consumer_reports_addressed.pyindex 01467be1a..67e9153fc 100644--- a/core/tests/switch_core/clients/test_agent_consumer_reports_addressed.py+++ b/core/tests/switch_core/clients/test_agent_consumer_reports_addressed.py@@ -13,7 +13,9 @@ from types import SimpleNamespacefrom typing import Anyimport pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+from switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.clients import agent_consumer as agent_consumer_modulefrom switch_core.clients.admin_messages import PLATFORM_MARKERfrom switch_core.clients.agent_consumer import (@@ -22,9 +24,19 @@ from switch_core.clients.agent_consumer import (_GateOutcome,)from switch_core.clients.room_meta import RoomMeta+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.observability.metrics import MetricsRegistry, install, uninstallfrom switch_core.observability.throttle import WarningThrottlefrom switch_core.transport import InboundMessage, RoomRef+from tests.db_buffer import seed_agent++AGENT = "agent-1"++[email protected](autouse=True)+async def _agent_row(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent the consumer queues for, so its events have a row to belong to."""+ await seed_agent(session_factory, AGENT)@asynccontextmanager@@ -46,6 +58,7 @@ class _BrokenMessageTelemetry:def _consumer(+ buffer: EventBuffer,*,addressed: bool,allowed: bool = True,@@ -81,9 +94,9 @@ def _consumer(ns = SimpleNamespace(agent=SimpleNamespace(- id="agent-1", name="agent-a", metadata_={"known_agent_type": "codex"}+ id=AGENT, name="agent-a", metadata_={"known_agent_type": "codex"}),- tenant_id="tenant-1",+ tenant_id=TENANT_ZERO_ID,session_factory=_session_factory,_resolve_room_meta=_resolve_room_meta,_addressed_without_lookup=lambda _e, _m: None,@@ -95,8 +108,7 @@ def _consumer(_post_auto_reply=_ignore_post,_sender_handle=lambda _e: "@alice",_triggered_by_auto_reply=AgentConsumer._triggered_by_auto_reply,- _event_buffer=SimpleNamespace(enqueue=lambda *a, **k: ns.enqueued.append(a)),- enqueued=[],+ _event_buffer=buffer,_message_telemetry=_FakeMessageTelemetry(),)ns._report_addressed = AgentConsumer._report_addressed.__get__(ns)@@ -123,14 +135,14 @@ async def _deliver(consumer: SimpleNamespace, event: InboundMessage) -> None:await AgentConsumer.on_message(consumer, RoomRef(room_id="!room:s"), event) # type: ignore[arg-type]-async def test_an_addressed_message_is_reported_once() -> None:- consumer = _consumer(addressed=True)+async def test_an_addressed_message_is_reported_once(db_buffer: EventBuffer) -> None:+ consumer = _consumer(db_buffer, addressed=True)await _deliver(consumer, _message())assert consumer._message_telemetry.addressed == [{- "tenant_id": "tenant-1",+ "tenant_id": TENANT_ZERO_ID,"room_id": "room-1","sender_transport_user_id": "@alice:s","from_platform": False,@@ -141,32 +153,36 @@ async def test_an_addressed_message_is_reported_once() -> None:]-async def test_room_chatter_is_not_reported() -> None:- consumer = _consumer(addressed=False)+async def test_room_chatter_is_not_reported(db_buffer: EventBuffer) -> None:+ consumer = _consumer(db_buffer, addressed=False)await _deliver(consumer, _message())assert consumer._message_telemetry.addressed == []-async def test_a_message_the_policy_turned_away_is_not_reported() -> None:- consumer = _consumer(addressed=True, allowed=False)+async def test_a_message_the_policy_turned_away_is_not_reported(+ db_buffer: EventBuffer,+) -> None:+ consumer = _consumer(db_buffer, addressed=True, allowed=False)await _deliver(consumer, _message())assert consumer._message_telemetry.addressed == []-async def test_an_auto_reply_is_not_reported() -> None:- consumer = _consumer(addressed=True)+async def test_an_auto_reply_is_not_reported(db_buffer: EventBuffer) -> None:+ consumer = _consumer(db_buffer, addressed=True)await _deliver(consumer, _message(**{AUTO_REPLY_FLAG: True}))assert consumer._message_telemetry.addressed == []-async def test_a_platform_message_says_it_came_from_the_platform() -> None:- consumer = _consumer(addressed=True)+async def test_a_platform_message_says_it_came_from_the_platform(+ db_buffer: EventBuffer,+) -> None:+ consumer = _consumer(db_buffer, addressed=True)await _deliver(consumer, _message(**{PLATFORM_MARKER: {}}))@@ -174,8 +190,10 @@ async def test_a_platform_message_says_it_came_from_the_platform() -> None:assert report["from_platform"] is True-async def test_a_message_to_an_offline_agent_is_reported_as_not_live() -> None:- consumer = _consumer(addressed=True, live=False)+async def test_a_message_to_an_offline_agent_is_reported_as_not_live(+ db_buffer: EventBuffer,+) -> None:+ consumer = _consumer(db_buffer, addressed=True, live=False)await _deliver(consumer, _message())@@ -184,11 +202,13 @@ async def test_a_message_to_an_offline_agent_is_reported_as_not_live() -> None:async def test_a_telemetry_failure_does_not_cost_the_agent_the_message(- monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture+ monkeypatch: pytest.MonkeyPatch,+ caplog: pytest.LogCaptureFixture,+ db_buffer: EventBuffer,) -> None:"""Caught, so it is counted, and logged once rather than once permessage."""- consumer = _consumer(addressed=True)+ consumer = _consumer(db_buffer, addressed=True)consumer._message_telemetry = _BrokenMessageTelemetry()registry = MetricsRegistry()install(registry)@@ -208,7 +228,7 @@ async def test_a_telemetry_failure_does_not_cost_the_agent_the_message(finally:uninstall()- assert len(consumer.enqueued) == 2+ assert len(await db_buffer.read_from(TENANT_ZERO_ID, AGENT, 0)) == 2assert failures.numbers[0].value == 2.0assert dict(failures.numbers[0].attributes) == {"actor": "agent"}assert (diff --git a/core/tests/switch_core/clients/test_enqueue_debug_logging.py b/core/tests/switch_core/clients/test_enqueue_debug_logging.pyindex 2dfd54cce..7787236af 100644--- a/core/tests/switch_core/clients/test_enqueue_debug_logging.py+++ b/core/tests/switch_core/clients/test_enqueue_debug_logging.py@@ -8,33 +8,75 @@ server, thousands of serialisations a second for a line nobody was logging.from __future__ import annotationsimport logging+from contextlib import asynccontextmanagerfrom types import SimpleNamespaceimport pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+from switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.protocol.types import AgentEvent-from switch_core.clients.agent_consumer import AgentConsumer+from switch_core.clients.agent_consumer import AgentConsumer, _GateOutcome+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.transport import InboundMedia, InboundMessage, RoomRef+from tests.db_buffer import seed_agent_LOGGER = "switch_core.clients.agent_consumer"+AGENT = "agent-1"-def _consumer(enqueued: list[AgentEvent]) -> SimpleNamespace:- """An unaddressed delivery: no store is consulted, the event is enqueued."""[email protected](autouse=True)+async def _agent_row(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent the consumer queues for, so its events have a row to belong to."""+ await seed_agent(session_factory, AGENT)+++async def _enqueued(buffer: EventBuffer) -> list[AgentEvent]:+ return [item.event for item in await buffer.read_from(TENANT_ZERO_ID, AGENT, 0)]+++@asynccontextmanager+async def _session_factory(): # type: ignore[no-untyped-def]+ yield object()+++def _consumer(buffer: EventBuffer) -> SimpleNamespace:+ """A delivery addressed to a live agent, every lookup answered in place.++ Addressed because only an event for the agent is enqueued: the rest of the+ room stays in the room's log and never reaches the line under test.+ """async def _resolve_room_meta(_room_id: str) -> SimpleNamespace:return SimpleNamespace(room_id="room-1", bridge_id=None, channel_type="channel_public")- return SimpleNamespace(- agent=SimpleNamespace(id="agent-1", name="helper"),+ async def _yes(*_args: object) -> bool:+ return True++ async def _fresh_agent(_session: object) -> object:+ return ns.agent++ async def _gate_addressed(*_args: object) -> _GateOutcome:+ return _GateOutcome(addressed=True, refusal=None)++ ns = SimpleNamespace(+ agent=SimpleNamespace(id=AGENT, name="helper"),+ tenant_id=TENANT_ZERO_ID,+ session_factory=_session_factory,_resolve_room_meta=_resolve_room_meta,- _addressed_without_lookup=lambda _event, _meta: False,- _event_buffer=SimpleNamespace(- enqueue=lambda _agent, _room, event: enqueued.append(event)- ),+ _addressed_without_lookup=lambda _event, _meta: True,+ _compute_addressed=_yes,+ _fresh_agent=_fresh_agent,+ _gate_addressed=_gate_addressed,+ _triggered_by_auto_reply=AgentConsumer._triggered_by_auto_reply,+ _is_available=_yes,+ _message_telemetry=SimpleNamespace(enabled=False),+ _report_addressed=lambda *_a, **_k: None,+ _event_buffer=buffer,)+ return nsdef _message() -> InboundMessage:@@ -43,8 +85,8 @@ def _message() -> InboundMessage:event_id="$evt",sender="@someone:switch.local",timestamp=1,- content={"body": "hello"},- body="hello",+ content={"body": "@helper hello"},+ body="@helper hello",sender_name="someone",)@@ -63,44 +105,47 @@ def dumps(monkeypatch: pytest.MonkeyPatch) -> list[int]:@pytest.mark.asyncio-async def test_an_event_is_not_serialised_for_a_debug_line_nobody_logs(dumps, caplog):+async def test_an_event_is_not_serialised_for_a_debug_line_nobody_logs(+ dumps, caplog, db_buffer+):caplog.set_level(logging.INFO, logger=_LOGGER)- enqueued: list[AgentEvent] = []await AgentConsumer.on_message(- _consumer(enqueued), # type: ignore[arg-type]+ _consumer(db_buffer), # type: ignore[arg-type]RoomRef(room_id="!room:server"),_message(),)- assert len(enqueued) == 1+ assert len(await _enqueued(db_buffer)) == 1assert dumps == []assert not [r for r in caplog.records if "Enqueuing event" in r.getMessage()]@pytest.mark.asyncio-async def test_the_debug_line_is_still_logged_when_debug_is_on(dumps, caplog):+async def test_the_debug_line_is_still_logged_when_debug_is_on(+ dumps, caplog, db_buffer+):caplog.set_level(logging.DEBUG, logger=_LOGGER)- enqueued: list[AgentEvent] = []await AgentConsumer.on_message(- _consumer(enqueued), # type: ignore[arg-type]+ _consumer(db_buffer), # type: ignore[arg-type]RoomRef(room_id="!room:server"),_message(),)- assert len(enqueued) == 1+ assert len(await _enqueued(db_buffer)) == 1assert dumps == [1]lines = [r for r in caplog.records if "Enqueuing event" in r.getMessage()]assert len(lines) == 1- assert '"body": "hello"' in lines[0].getMessage()+ assert '"body": "@helper hello"' in lines[0].getMessage()@pytest.mark.parametrize("level", [logging.INFO, logging.DEBUG])@pytest.mark.asyncio-async def test_a_media_event_is_serialised_only_when_debug_is_on(dumps, caplog, level):+async def test_a_media_event_is_serialised_only_when_debug_is_on(+ dumps, caplog, level, db_buffer+):caplog.set_level(level, logger=_LOGGER)- enqueued: list[AgentEvent] = []media = InboundMedia(room_id="!room:server",event_id="$media",@@ -112,20 +157,22 @@ async def test_a_media_event_is_serialised_only_when_debug_is_on(dumps, caplog,)await AgentConsumer._emit_media(- _consumer(enqueued), # type: ignore[arg-type]+ _consumer(db_buffer), # type: ignore[arg-type]RoomRef(room_id="!room:server"),media,SimpleNamespace( # type: ignore[arg-type]room_id="room-1", bridge_id=None, channel_type="channel_public"),- False,+ True,"someone",None,[],"a file",+ room_seq=1,+ message_key="$media",)- assert len(enqueued) == 1+ assert len(await _enqueued(db_buffer)) == 1logged = [r for r in caplog.records if "Enqueuing media event" in r.getMessage()]if level == logging.DEBUG:assert dumps == [1]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.pyindex c4acb6ed7..e6464f497 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@@ -12,6 +12,7 @@ from switch_core.clients.agent_consumer import (AgentConsumer,_GateOutcome,)+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.transport import InboundMessage, RoomRef@@ -20,6 +21,11 @@ async def _session_factory(): # type: ignore[no-untyped-def]yield object()+async def _ignore_enqueue(*_args: object, **_kwargs: object) -> int:+ # What the agent is sent is not under test here, only where the reply goes.+ return 0++class _Recorder:"""Captures the send_message call so we can assert on thread_root_id."""@@ -76,6 +82,7 @@ def _fake_self(ns = SimpleNamespace(agent=SimpleNamespace(id="agent-1", name="cc-bug-fixing"),+ tenant_id=TENANT_ZERO_ID,session_factory=_session_factory,_resolve_room_meta=_resolve_room_meta,_addressed_without_lookup=_addressed_without_lookup,@@ -86,7 +93,7 @@ def _fake_self(_reply_when_unavailable_here=_reply_when_unavailable_here,_triggered_by_auto_reply=AgentConsumer._triggered_by_auto_reply,actor=SimpleNamespace(send_message=send_message),- _event_buffer=SimpleNamespace(enqueue=lambda *a, **k: None),+ _event_buffer=SimpleNamespace(enqueue=_ignore_enqueue),_report_addressed=lambda *a, **k: None,)# Exercise the real sender-tagging and auto-reply helpers.diff --git a/core/tests/switch_core/clients/test_removed_from_room.py b/core/tests/switch_core/clients/test_removed_from_room.pyindex c4845a1b3..6308928f2 100644--- a/core/tests/switch_core/clients/test_removed_from_room.py+++ b/core/tests/switch_core/clients/test_removed_from_room.py@@ -12,23 +12,35 @@ from __future__ import annotationsfrom types import SimpleNamespace+import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+from switch_core.bridges.agent.protocol.agent_connections import (PROTOCOL_VERSION,AgentConnectionRegistry,ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayloadfrom switch_core.clients.actor import Actorfrom switch_core.clients.agent_consumer import AgentConsumer, RoomMetafrom switch_core.clients.consumer import Consumer+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.transport import InboundMembership, RoomRef+from tests.db_buffer import seed_agentAGENT = "agent-1"LEFT = "room-left"KEPT = "room-kept"[email protected](autouse=True)+async def _agent_row(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent whose events are retained, so they have a row to belong to."""+ await seed_agent(session_factory, AGENT)++def _message(room_id: str, body: str) -> AgentEvent:return AgentEvent(type="message",@@ -44,6 +56,18 @@ def _message(room_id: str, body: str) -> AgentEvent:)+async def _keep(buffer: EventBuffer, room_id: str, body: str) -> None:+ """A message addressed to the agent in `room_id`, kept as one of its own."""+ await buffer.enqueue(+ TENANT_ZERO_ID,+ AGENT,+ room_id,+ _message(room_id, body),+ room_seq=1,+ message_key=f"$m-{body}",+ )++def _leave(transport_room_id: str) -> InboundMembership:return InboundMembership(room_id=transport_room_id,@@ -76,6 +100,7 @@ def _client(_event_buffer=buffer,_connections=connections,agent=SimpleNamespace(id=AGENT),+ tenant_id=TENANT_ZERO_ID,_resolve_room_meta=_resolve_room_meta,)@@ -88,20 +113,22 @@ async def _removed(stub: SimpleNamespace, transport_room_id: str) -> None:)-async def test_the_rooms_retained_events_are_forgotten() -> None:- buffer = EventBuffer(sequence_base=0)- buffer.enqueue(AGENT, LEFT, _message(LEFT, "said in the old room"))- buffer.enqueue(AGENT, KEPT, _message(KEPT, "said in this one"))+async def test_the_rooms_retained_events_are_forgotten(db_buffer: EventBuffer) -> None:+ buffer = db_buffer+ await _keep(buffer, LEFT, "said in the old room")+ await _keep(buffer, KEPT, "said in this one")await _removed(_client(buffer, AgentConnectionRegistry()), "!left:test")# Read at the level every reader is built on, filter or no filter: this is# what closes it for the stream, which has no membership of its own to# apply and would otherwise replay the room on every resume.- assert [item.room_id for item in buffer.read_from(AGENT, 0)] == [KEPT]+ assert [+ item.room_id for item in await buffer.read_from(TENANT_ZERO_ID, AGENT, 0)+ ] == [KEPT]-async def test_the_rooms_claim_is_released() -> None:+async def test_the_rooms_claim_is_released(db_buffer: EventBuffer) -> None:connections = AgentConnectionRegistry()conn = connections.open(agent_id=AGENT,@@ -109,25 +136,29 @@ async def test_the_rooms_claim_is_released() -> None:scope="single",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)connections.claim_room(conn, LEFT)- await _removed(_client(EventBuffer(sequence_base=0), connections), "!left:test")+ await _removed(_client(db_buffer, connections), "!left:test")assert conn.rooms == set()-async def test_a_room_that_cannot_be_resolved_drops_nothing() -> None:+async def test_a_room_that_cannot_be_resolved_drops_nothing(+ db_buffer: EventBuffer,+) -> None:"""Rather than guessing which room was meant and emptying the wrong one."""- buffer = EventBuffer(sequence_base=0)- buffer.enqueue(AGENT, LEFT, _message(LEFT, "still here"))+ buffer = db_buffer+ await _keep(buffer, LEFT, "still here")await _removed(_client(buffer, AgentConnectionRegistry()), "!unknown:test")- assert [item.room_id for item in buffer.read_from(AGENT, 0)] == [LEFT]+ assert [+ item.room_id for item in await buffer.read_from(TENANT_ZERO_ID, AGENT, 0)+ ] == [LEFT]class _CapturingTransport:diff --git a/core/tests/switch_core/clients/test_room_join_events.py b/core/tests/switch_core/clients/test_room_join_events.pyindex 8c49d1cb0..fbcc54708 100644--- a/core/tests/switch_core/clients/test_room_join_events.py+++ b/core/tests/switch_core/clients/test_room_join_events.py@@ -3,17 +3,34 @@ from __future__ import annotationsfrom contextlib import asynccontextmanagerfrom types import SimpleNamespace+import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.protocol.types import AgentEvent, RoomJoinPayloadfrom switch_core.clients.agent_consumer import AgentConsumer, RoomMeta+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.transport import InboundMembership, RoomRef+from tests.db_buffer import seed_agent++AGENT = "agent-1"+[email protected](autouse=True)+async def _agent_row(session_factory: async_sessionmaker[AsyncSession]) -> None:+ """The agent the consumer queues for, so its events have a row to belong to."""+ await seed_agent(session_factory, AGENT)-class _FakeQueue:- def __init__(self) -> None:- self.enqueued: list[tuple[str, str, AgentEvent]] = []- def enqueue(self, agent_id: str, room_id: str, event: AgentEvent) -> None:- self.enqueued.append((agent_id, room_id, event))+async def _enqueued(client: SimpleNamespace) -> list[tuple[str, AgentEvent]]:+ """What the consumer queued for its agent, read back from the db-buffer as+ (room, event). Reading under the agent's id is what checks which agent it+ was queued for."""+ buffer: EventBuffer = client._event_buffer+ return [+ (item.room_id, item.event)+ for item in await buffer.read_from(TENANT_ZERO_ID, AGENT, 0)+ ]class _FakeClientStore:@@ -40,6 +57,7 @@ class _FakeRoomStore:def _client(+ buffer: EventBuffer,meta: RoomMeta | None = None,*,receives: bool = True,@@ -47,7 +65,7 @@ def _client() -> SimpleNamespace:"""A minimal fake `self` for the unbound AgentConsumer.on_member_event.- Stubs the event queue, agent identity, room-meta resolution, and the room+ Queues on the db-buffer; stubs agent identity, room-meta resolution, and the roomstore / session factory so the handler can run without a DB or live Matrixclient. `receives` is what the stubbed store reports for this agent'sper-room join-event setting.@@ -67,8 +85,9 @@ def _client(yield SimpleNamespace()stub = SimpleNamespace(- _event_buffer=_FakeQueue(),- agent=SimpleNamespace(id="agent-1"),+ _event_buffer=buffer,+ agent=SimpleNamespace(id=AGENT),+ tenant_id=TENANT_ZERO_ID,_resolve_room_meta=_resolve_room_meta,_room_store=_FakeRoomStore(receives),client_store=_FakeClientStore(@@ -112,13 +131,12 @@ async def _run(client: SimpleNamespace, event: InboundMembership) -> None:class TestRoomJoinEnqueue:- async def test_join_enqueues_room_join_event(self) -> None:- client = _client()+ async def test_join_enqueues_room_join_event(self, db_buffer: EventBuffer) -> None:+ client = _client(db_buffer)await _run(client, _member_event())- assert len(client._event_buffer.enqueued) == 1- agent_id, room_id, event = client._event_buffer.enqueued[0]- assert agent_id == "agent-1"+ assert len(await _enqueued(client)) == 1+ room_id, event = (await _enqueued(client))[0]assert room_id == "room-1"assert event.type == "room_join"assert event.bridge_id == "bridge-1"@@ -130,57 +148,64 @@ class TestRoomJoinEnqueue:# Stubbed store opts this agent in → listening is True.assert event.payload.listening is True- async def test_listening_reflects_store_setting(self) -> None:- # The event is delivered regardless, but `listening` mirrors the- # per-room, per-agent receives_join_events setting (off here).- client = _client(receives=False)+ async def test_listening_reflects_store_setting(+ self, db_buffer: EventBuffer+ ) -> None:+ # The per-room, per-agent receives_join_events setting (off here)+ # decides whether the arrival is one of the agent's own events. Off, it+ # is the room's conversation: nothing is queued, and a reader that+ # wants the conversation reads the arrival from the room's log, with+ # `listening` False.+ client = _client(db_buffer, receives=False)await _run(client, _member_event())- assert len(client._event_buffer.enqueued) == 1- _, _, event = client._event_buffer.enqueued[0]- assert event.payload.listening is False+ assert await _enqueued(client) == []- async def test_the_member_is_named_the_way_switch_knows_them(self) -> None:+ async def test_the_member_is_named_the_way_switch_knows_them(+ self, db_buffer: EventBuffer+ ) -> None:"""A profile carries the source platform's spelling of a name; the logrecords the Switch one. Delivering the profile name would make liveevents and history disagree about the same person."""- client = _client(known={"@alice:switch.local": "alice"})+ client = _client(db_buffer, known={"@alice:switch.local": "alice"})await _run(client, _member_event(displayname="Alice \U0001f495"))- _, _, event = client._event_buffer.enqueued[0]+ _, event = (await _enqueued(client))[0]assert event.payload.member_name == "alice"async def test_a_member_no_switch_client_owns_falls_back_to_the_event(- self,+ self, db_buffer: EventBuffer) -> None:- client = _client(known={})+ client = _client(db_buffer, known={})await _run(client, _member_event(displayname=None, state_key="@bob:switch.local"))- assert len(client._event_buffer.enqueued) == 1- _, _, event = client._event_buffer.enqueued[0]+ assert len(await _enqueued(client)) == 1+ _, event = (await _enqueued(client))[0]assert event.payload.member_name == "bob"- async def test_leave_does_not_enqueue(self) -> None:- client = _client()+ async def test_leave_does_not_enqueue(self, db_buffer: EventBuffer) -> None:+ client = _client(db_buffer)await _run(client, _member_event(membership="leave", prev_membership="join"))- assert client._event_buffer.enqueued == []+ assert await _enqueued(client) == []- async def test_profile_update_does_not_enqueue(self) -> None:+ async def test_profile_update_does_not_enqueue(+ self, db_buffer: EventBuffer+ ) -> None:# membership-preserving update (e.g. display-name change): join -> join.- client = _client()+ client = _client(db_buffer)await _run(client, _member_event(membership="join", prev_membership="join"))- assert client._event_buffer.enqueued == []+ assert await _enqueued(client) == []- async def test_no_room_meta_does_not_enqueue(self) -> None:+ async def test_no_room_meta_does_not_enqueue(self, db_buffer: EventBuffer) -> None:async def _none(_transport_room_id: str) -> RoomMeta | None:return None- client = _client()+ client = _client(db_buffer)client._resolve_room_meta = _noneawait _run(client, _member_event())- assert client._event_buffer.enqueued == []+ assert await _enqueued(client) == []class TestRoomJoinPayloadRegistry:diff --git a/core/tests/switch_core/management/harness.py b/core/tests/switch_core/management/harness.pyindex e3a64c8b5..de215534c 100644--- a/core/tests/switch_core/management/harness.py+++ b/core/tests/switch_core/management/harness.py@@ -44,7 +44,6 @@ from switch_core.bridges.agent.protocol.controller_presence import (ControllerConnectionError,)from switch_core.bridges.agent.protocol.controller_stream import IDLE-from switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.config import ControllerReleasefrom switch_core.connections.broker import ServiceBrokerfrom switch_core.db.models import (@@ -68,6 +67,7 @@ from switch_core.keys import Keyringfrom switch_core.management import controller_routesfrom switch_core.management.errors import ManagementErrorfrom switch_core.management.wiring import Management, build_management+from tests.db_buffer import db_buffer_onfrom tests.switch_core.connections.fake_vendor import FakeVendorfrom tests.switch_core.connections.github_seed import github_broker@@ -149,7 +149,7 @@ def protocol_service(keyring=TEST_KEYRING, third_party_avatars_enabled=True)svc.telemetry = None- svc.event_buffer = EventBuffer(sequence_base=0)+ svc.event_buffer = db_buffer_on(session_factory)svc.connections = AgentConnectionRegistry()svc.approval_outcomes = None # type: ignore[assignment]svc.room_store = RoomStore()@@ -644,7 +644,7 @@ async def attach(return Answer(200, {})-def beat(+async def beat(harness: Harness,controller: EnrolledController,*,@@ -655,7 +655,7 @@ def beat("""A pong, answered as the socket would: the agents on success, therefusal its `evicted` frame would name otherwise."""try:- agents = controller_routes.record_beat(+ agents = await controller_routes.record_beat(principal=_principal(controller),protocol=harness.protocol,connection_id=connection_id,diff --git a/core/tests/switch_core/management/test_act_as.py b/core/tests/switch_core/management/test_act_as.pyindex 42e0d5b60..b0301f13c 100644--- a/core/tests/switch_core/management/test_act_as.py+++ b/core/tests/switch_core/management/test_act_as.py@@ -30,6 +30,7 @@ from switch_core.bridges.agent.operations.callctx import (from switch_core.bridges.agent.operations.definitions import connect_to_roomfrom switch_core.bridges.agent.protocol.agent_connections import ClientDeclarationfrom switch_core.bridges.agent.protocol.controller_presence import Binding+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.db.models import (TENANT_ZERO_ID,Agent,@@ -373,7 +374,7 @@ class TestTheAgentsOwnCredential:scope="all",delivery_filter="all",spawn_capable=True,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(),expected_generation=None,)diff --git a/core/tests/switch_core/management/test_connection_socket.py b/core/tests/switch_core/management/test_connection_socket.pyindex 6ab15a04f..dc31807ff 100644--- a/core/tests/switch_core/management/test_connection_socket.py+++ b/core/tests/switch_core/management/test_connection_socket.py@@ -82,7 +82,7 @@ def client(calls: _Calls, monkeypatch: pytest.MonkeyPatch) -> Iterator[TestClienreturn frames()- def record_beat(**kwargs: Any) -> list[str]:+ async def record_beat(**kwargs: Any) -> list[str]:calls.beats.append(kwargs)if calls.beat_refusal is not None:raise calls.beat_refusaldiff --git a/core/tests/switch_core/management/test_connection_state.py b/core/tests/switch_core/management/test_connection_state.pyindex 90e29dfdb..1e379a656 100644--- a/core/tests/switch_core/management/test_connection_state.py+++ b/core/tests/switch_core/management/test_connection_state.py@@ -256,7 +256,7 @@ class TestTheMachineState:presence.attach_stream(conn)await ledger.flush_all()for _ in range(20):- answer = beat(+ answer = await beat(harness,controller,connection_id=opened["connection_id"],diff --git a/core/tests/switch_core/management/test_contract_fixtures.py b/core/tests/switch_core/management/test_contract_fixtures.pyindex cbcf5d011..ced812daf 100644--- a/core/tests/switch_core/management/test_contract_fixtures.py+++ b/core/tests/switch_core/management/test_contract_fixtures.py@@ -22,9 +22,9 @@ import pytestfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.commands import room_control_frame-from switch_core.bridges.agent.protocol.event_buffer import Readerfrom switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayloadfrom switch_core.config import ControllerRelease+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.management import controller_routesfrom switch_core.management.schemas import (@@ -35,6 +35,7 @@ from switch_core.management.schemas import (StatusReport,TokenRequest,)+from tests.db_buffer import sayfrom tests.switch_core.management.harness import (FIXTURES,Harness,@@ -289,7 +290,7 @@ class TestTheControllerConnection:stream = await open_stream(harness, controller, opened.json())await take(stream, 2)pong = _fixture("controller_pong.json")- beaten = beat(+ beaten = await beat(harness,controller,connection_id=opened.json()["connection_id"],@@ -362,19 +363,19 @@ class TestStreamFrames:# before a restart), agent.approval_outcomeprovoked += await take(stream, 4)- # The restart left the room's count unknown; a read through the- # head gives it a baseline again, as `read_context` would.- binding = presence.binding(agent_id)- assert binding is not None- buffer = harness.protocol.event_buffer- buffer.caught_up(- agent_id,- Reader(id=presence.holder_id(binding), is_session=False),+ # Addressed to the agent: the row in the room's log, and the+ # agent's own event for it. Its missed count runs from where+ # attaching the agent began counting the room.+ asked = await say(+ harness.session_factory,room_id,- buffer.head(agent_id),- None,+ "@reviewer can you look at this?",+ sender="@ada:test",+ sender_name="Ada",+ event_id="$event-1",)- harness.protocol.event_buffer.enqueue(+ await harness.protocol.event_buffer.enqueue(+ TENANT_ZERO_ID,agent_id,room_id,AgentEvent(@@ -389,6 +390,8 @@ class TestStreamFrames:timestamp=0,),),+ room_seq=asked.seq,+ message_key=asked.transport_event_id,)provoked += await take(stream, 1)diff --git a/core/tests/switch_core/management/test_middleware.py b/core/tests/switch_core/management/test_middleware.pyindex fe135f151..b86851811 100644--- a/core/tests/switch_core/management/test_middleware.py+++ b/core/tests/switch_core/management/test_middleware.py@@ -301,7 +301,7 @@ class TestTheFlagOff:room_service=object(), # type: ignore[arg-type]client_lifecycle=object(), # type: ignore[arg-type]collab_lifecycle=object(), # type: ignore[arg-type]- event_buffer=EventBuffer(sequence_base=0),+ event_buffer=EventBuffer(object(), sequence_base=0), # type: ignore[arg-type]task_store=object(), # type: ignore[arg-type]resource_service=object(), # type: ignore[arg-type]api_key_store=object(), # type: ignore[arg-type]diff --git a/core/tests/switch_core/management/test_stream.py b/core/tests/switch_core/management/test_stream.pyindex 8dd54f166..753a7301e 100644--- a/core/tests/switch_core/management/test_stream.py+++ b/core/tests/switch_core/management/test_stream.py@@ -15,7 +15,6 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.commands import room_control_framefrom switch_core.bridges.agent.protocol.agent_detail import assemble_agent_detail-from switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.bridges.agent.protocol.liveness import HEARTBEAT_TTL_SECONDSfrom switch_core.bridges.agent.protocol.presence import (agents_present_in,@@ -35,6 +34,7 @@ from switch_core.management.notifier import (OPERATION_PENDING,ControllerNotifier,)+from tests.db_buffer import age_events, sayfrom tests.switch_core.management.harness import (Harness,add_member,@@ -59,21 +59,38 @@ def harness(session_factory: async_sessionmaker[AsyncSession]) -> Harness:return build_harness(session_factory)-def _message(room_id: str, body: str, *, addressed: bool) -> AgentEvent:+def _message(room_id: str, body: str, *, message_id: str) -> AgentEvent:return AgentEvent(type="message",room_id=room_id,payload=MessagePayload(- addressed=addressed,+ addressed=True,sender="@ada:test",sender_name="Ada",- message_id=f"$event-{body}",+ message_id=message_id,body=body,timestamp=0,),)+async def _ask(harness: Harness, agent_id: str, room_id: str, body: str) -> int:+ """A message addressed to the agent, as its consumer keeps it: the row in+ the room's log, and the agent's own event for that row. The event's number+ in the agent's own events, which is what the controller is sent."""+ row = await say(+ harness.session_factory, room_id, body, sender="@ada:test", sender_name="Ada"+ )+ return await harness.protocol.event_buffer.enqueue(+ TENANT_ZERO_ID,+ agent_id,+ room_id,+ _message(room_id, body, message_id=row.transport_event_id),+ room_seq=row.seq,+ message_key=row.transport_event_id,+ )++class TestTheNotifier:def test_signals_coalesce_and_revocation_comes_last(self) -> None:notifier = ControllerNotifier()@@ -149,15 +166,14 @@ class TestOpening:self, harness: Harness) -> None:owner = await add_member(harness.session_factory, "ada")- buffer = harness.protocol.event_bufferasync with harness.client() as client:controller = await enroll_console(harness, client, owner)first = await place_agent(client, controller, name="first")second = await place_agent(client, controller, name="second")room_id = await add_room(harness.session_factory, first, second)for body in ("one", "two", "three"):- buffer.enqueue(first, room_id, _message(room_id, body, addressed=False))- buffer.enqueue(second, room_id, _message(room_id, "hi", addressed=True))+ await _ask(harness, first, room_id, body)+ await _ask(harness, second, room_id, "hi")opened = await open_connection(client, controller, {first: 1})stream = await open_stream(harness, controller, opened)@@ -185,7 +201,6 @@ class TestOpening:self, harness: Harness) -> None:owner = await add_member(harness.session_factory, "ada")- buffer = harness.protocol.event_bufferasync with harness.client() as client:controller = await enroll_console(harness, client, owner)agent_id = await place_agent(client, controller, name="reviewer")@@ -194,17 +209,17 @@ class TestOpening:stream = await open_stream(harness, controller, opened)await take(stream, 2)- buffer.enqueue(agent_id, room_id, _message(room_id, "chatter", addressed=False))- buffer.enqueue(agent_id, room_id, _message(room_id, "more", addressed=False))- buffer.enqueue(agent_id, room_id, _message(room_id, "@you", addressed=True))- frames = await take(stream, 3)+ await say(harness.session_factory, room_id, "chatter", sender="@ada:test")+ await say(harness.session_factory, room_id, "more", sender="@ada:test")+ await _ask(harness, agent_id, room_id, "@you")+ [(name, data)] = await take(stream, 1)await stream.aclose()- assert [data["event"].get("missed") for _, data in frames] == [- None,- None,- {"count": 2, "reason": None},- ]+ # The chatter itself is not sent: the controller is sent the agent's+ # own events, and told on the next of them how much went past.+ assert name == "agent.event"+ assert data["event"]["payload"]["body"] == "@you"+ assert data["event"]["missed"] == {"count": 2, "reason": None}async def test_a_cursor_from_before_a_restart_is_a_gap(self, harness: Harness@@ -230,22 +245,21 @@ class TestOpening:assert gap["all_rooms"] is Trueassert gap["rooms"] == [room_id]- async def test_an_overflowed_cursor_is_a_gap_naming_the_rooms(+ async def test_an_expired_cursor_is_a_gap_naming_the_rooms(self, harness: Harness) -> None:- harness.protocol.event_buffer = EventBuffer(- sequence_base=0, max_events_per_agent=2- )buffer = harness.protocol.event_bufferowner = await add_member(harness.session_factory, "ada")async with harness.client() as client:controller = await enroll_console(harness, client, owner)agent_id = await place_agent(client, controller, name="reviewer")room_id = await add_room(harness.session_factory, agent_id)- for body in ("a", "b", "c", "d"):- buffer.enqueue(- agent_id, room_id, _message(room_id, body, addressed=False)- )+ for body in ("a", "b"):+ await _ask(harness, agent_id, room_id, body)+ await age_events(harness.session_factory, agent_id, seconds=2 * 3600)+ await buffer.expire(TENANT_ZERO_ID)+ for body in ("c", "d"):+ await _ask(harness, agent_id, room_id, body)opened = await open_connection(client, controller, {agent_id: 0})stream = await open_stream(harness, controller, opened)@@ -415,28 +429,28 @@ class TestTheConnection:evicted = await take(old_stream, 1)with pytest.raises(StopAsyncIteration):await anext(old_stream)- stale = beat(+ stale = await beat(harness,controller,connection_id=old["connection_id"],generation=old["generation"],cursors={},)- wrong_generation = beat(+ wrong_generation = await beat(harness,controller,connection_id=new["connection_id"],generation=new["generation"] + 1,cursors={},)- unknown = beat(+ unknown = await beat(harness,controller,connection_id="nope",generation=1,cursors={},)- no_stream = beat(+ no_stream = await beat(harness,controller,connection_id=new["connection_id"],@@ -476,56 +490,55 @@ class TestTheConnection:) -> None:owner = await add_member(harness.session_factory, "ada")presence = harness.protocol.connections.controllers- buffer = harness.protocol.event_bufferasync with harness.client() as client:controller = await enroll_console(harness, client, owner)agent_id = await place_agent(client, controller, name="reviewer")room_id = await add_room(harness.session_factory, agent_id)- buffer.enqueue(agent_id, room_id, _message(room_id, "one", addressed=False))- opened = await open_connection(client, controller)+ await _ask(harness, agent_id, room_id, "one")+ # From before the event, so where the beat leaves the agent is+ # told apart from where the stream attached it.+ opened = await open_connection(client, controller, {agent_id: 0})assert not presence.is_live(agent_id)stream = await open_stream(harness, controller, opened)- await take(stream, 2)- beaten = beat(+ await take(stream, 3)+ beaten = await beat(harness,controller,connection_id=opened["connection_id"],generation=opened["generation"],cursors={agent_id: 99, "not-mine": 3},)+ conn = presence.current_connection(controller.controller_id)live = presence.is_live(agent_id)await stream.aclose()assert beaten.status_code == 200, beaten.textassert beaten.json() == {"agents": [agent_id]}assert live- binding = presence.binding(agent_id)- assert binding is not None- assert buffer._cursors[agent_id][presence.holder_id(binding)] == 1+ # Confirmed where a reattached stream resumes: lowered to what this+ # connection has sent the agent, and nothing for an agent that is not+ # this controller's.+ assert conn is not None+ assert conn.resume_cursors == {agent_id: 1}assert not presence.is_live(agent_id)async def test_a_reattached_stream_resumes_from_the_confirmed_cursors(self, harness: Harness) -> None:owner = await add_member(harness.session_factory, "ada")- buffer = harness.protocol.event_bufferasync with harness.client() as client:controller = await enroll_console(harness, client, owner)confirmed = await place_agent(client, controller, name="confirmed")unconfirmed = await place_agent(client, controller, name="unconfirmed")room_id = await add_room(harness.session_factory, confirmed, unconfirmed)for body in ("one", "two", "three"):- buffer.enqueue(- confirmed, room_id, _message(room_id, body, addressed=False)- )- buffer.enqueue(- unconfirmed, room_id, _message(room_id, "x", addressed=False)- )+ await _ask(harness, confirmed, room_id, body)+ await _ask(harness, unconfirmed, room_id, "x")opened = await open_connection(client, controller, {confirmed: 0})first = await open_stream(harness, controller, opened)# state, two attaches, three events for `confirmed`await take(first, 6)- beaten = beat(+ beaten = await beat(harness,controller,connection_id=opened["connection_id"],@@ -535,9 +548,7 @@ class TestTheConnection:assert beaten.status_code == 200, beaten.text# The socket drops; events keep arriving; the same connection is# streamed again.- buffer.enqueue(- unconfirmed, room_id, _message(room_id, "y", addressed=False)- )+ await _ask(harness, unconfirmed, room_id, "y")second = await open_stream(harness, controller, opened)# The first stream may finish the pass it was on, then sees it# was displaced and ends.@@ -645,7 +656,7 @@ class TestTheConnection:conn.last_beat = time.monotonic() - HEARTBEAT_TTL_SECONDS - 1assert not presence.is_live(agent_id)evicted = await take(stream, 1)- beaten = beat(+ beaten = await beat(harness,controller,connection_id=opened["connection_id"],@@ -709,9 +720,7 @@ async def test_a_waiting_stream_wakes_promptly_for_an_event(harness: Harness) ->await take(stream, 2)pending = asyncio.ensure_future(anext(stream))await asyncio.sleep(0.01)- harness.protocol.event_buffer.enqueue(- agent_id, room_id, _message(room_id, "now", addressed=True)- )+ await _ask(harness, agent_id, room_id, "now")raw = await asyncio.wait_for(pending, timeout=2)await stream.aclose()assert raw["event"] == "agent.event"diff --git a/core/tests/switch_core/observability/test_agent_protocol_metrics.py b/core/tests/switch_core/observability/test_agent_protocol_metrics.pyindex 35b7a1a74..983d52955 100644--- a/core/tests/switch_core/observability/test_agent_protocol_metrics.py+++ b/core/tests/switch_core/observability/test_agent_protocol_metrics.py@@ -11,6 +11,7 @@ import time as time_modulefrom collections.abc import Iteratorimport pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.protocol import agent_connections as conn_modulefrom switch_core.bridges.agent.protocol.agent_connections import (@@ -19,8 +20,11 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.db.models import TENANT_ZERO_IDfrom switch_core.observability.metrics import MetricsRegistry, install, uninstall+from tests.db_buffer import age_events, seed_agent@pytest.fixture@@ -56,39 +60,45 @@ def _event(index: int) -> AgentEvent:)-def test_events_dropped_for_overflow_are_counted(registry):- buffer = EventBuffer(- max_events_per_agent=3, retention_seconds=3600, sequence_base=0+async def _keep(buffer: EventBuffer, index: int) -> None:+ """Message `index`, addressed to the agent and kept as one of its own."""+ await buffer.enqueue(+ TENANT_ZERO_ID,+ "agent-1",+ "room-1",+ _event(index),+ room_seq=index + 1,+ message_key=f"m{index}",)- for index in range(6):- buffer.enqueue("agent-1", "room-1", _event(index))- # Three over the cap. The agent is told it missed them when it next reads,- # so the loss is disclosed — it simply was not countable.- assert _counts(registry, "switch.agent.events_dropped") == {- (("reason", "overflow"),): 3.0- }+async def test_events_dropped_for_retention_are_counted(+ registry, session_factory: async_sessionmaker[AsyncSession], db_buffer: EventBuffer+):+ """Each event retention deletes is counted, under its reason.-def test_events_dropped_for_retention_are_counted_separately(registry):- """An agent that cannot keep up and one that was away are different faults."""- buffer = EventBuffer(- max_events_per_agent=1000, retention_seconds=-1, sequence_base=0- )- buffer.enqueue("agent-1", "room-1", _event(0))- buffer.enqueue("agent-1", "room-1", _event(1))+ There is no per-agent cap any more, so retention is the only way an event+ leaves the buffer unread. The reader is told it missed them when it next+ reads, so the loss is disclosed; this is what makes it countable too.+ """+ await seed_agent(session_factory, "agent-1")+ for index in range(3):+ await _keep(db_buffer, index)+ await age_events(session_factory, "agent-1", seconds=7200)- counts = _counts(registry, "switch.agent.events_dropped")- assert set(counts) == {(("reason", "retention"),)}- assert counts[(("reason", "retention"),)] >= 1.0+ assert await db_buffer.expire(TENANT_ZERO_ID) == 3+ assert _counts(registry, "switch.agent.events_dropped") == {+ (("reason", "retention"),): 3.0+ }-def test_nothing_is_counted_when_nothing_is_dropped(registry):- buffer = EventBuffer(- max_events_per_agent=100, retention_seconds=3600, sequence_base=0- )- buffer.enqueue("agent-1", "room-1", _event(0))+async def test_nothing_is_counted_when_nothing_is_dropped(+ registry, session_factory: async_sessionmaker[AsyncSession], db_buffer: EventBuffer+):+ await seed_agent(session_factory, "agent-1")+ await _keep(db_buffer, 0)+ assert await db_buffer.expire(TENANT_ZERO_ID) == 0assert _counts(registry, "switch.agent.events_dropped") == {}@@ -101,7 +111,7 @@ def test_expired_connections_are_counted(registry, monkeypatch):scope="single", # type: ignore[arg-type]delivery_filter="all", # type: ignore[arg-type]spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -126,7 +136,7 @@ def test_a_quiet_sweep_counts_nothing(registry):scope="single", # type: ignore[arg-type]delivery_filter="all", # type: ignore[arg-type]spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -142,7 +152,7 @@ def _open(connections: AgentConnectionRegistry, connection_id: str = "c1") -> Noscope="single", # type: ignore[arg-type]delivery_filter="all", # type: ignore[arg-type]spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)diff --git a/core/tests/switch_core/observability/test_connection_metrics.py b/core/tests/switch_core/observability/test_connection_metrics.pyindex a4dd62d50..07c5cb86f 100644--- a/core/tests/switch_core/observability/test_connection_metrics.py+++ b/core/tests/switch_core/observability/test_connection_metrics.py@@ -31,6 +31,7 @@ from switch_core.bridges.agent.protocol.agent_connections import ()from switch_core.bridges.agent.protocol.controller_presence import Bindingfrom switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.db.models import Agentfrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.api_key_store import ApiKeyStore@@ -72,7 +73,7 @@ def _open(scope="all",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION, artifact=artifact, version=version),@@ -226,7 +227,7 @@ def test_a_stream_attached_over_sse_is_counted_as_sse() -> None:scope="all",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=6, accepts=1, artifact="agent-runtime"),expected_generation=None,transport="sse",@@ -239,9 +240,25 @@ def test_a_stream_attached_over_sse_is_counted_as_sse() -> None:assert readings[(("client", "agent-runtime"), ("transport", "websocket"))] == 1.0+class _EmptyBuffer(EventBuffer):+ """A buffer with nothing queued, answered without a database.++ A socket resolves where its events start, by reading the head, before its+ declaration is checked, so even one that is refused asks. The app runs on+ the test client's own event loop, where the test's database connections+ cannot follow, and nothing here is about what is queued.+ """++ def __init__(self) -> None:+ super().__init__(object(), sequence_base=0) # type: ignore[arg-type]++ async def head(self, tenant_id: str, agent_id: str) -> int:+ return self.sequence_floor - 1++class _Protocol:def __init__(self) -> None:- self.event_buffer = EventBuffer(sequence_base=0)+ self.event_buffer = _EmptyBuffer()self.connections = AgentConnectionRegistry()self.approval_outcomes = Noneself.sessions = SessionReporter(None)diff --git a/core/tests/switch_core/observability/test_log_context_bindings.py b/core/tests/switch_core/observability/test_log_context_bindings.pyindex b50a13f79..f17fafa46 100644--- a/core/tests/switch_core/observability/test_log_context_bindings.py+++ b/core/tests/switch_core/observability/test_log_context_bindings.py@@ -22,8 +22,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)-from switch_core.bridges.agent.protocol.event_buffer import EventBuffer-from switch_core.bridges.agent.protocol.types import AgentEvent, MessagePayload+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.collaboration.collaboration_core import CollaborationCorefrom switch_core.logging_context import LogContextFilter, current_log_contextfrom switch_core.transport.postgres import PostgresTransport@@ -115,10 +114,14 @@ class TestTheDeliveryLoopBindsItsRoom:class TestTheProtocolBindsItsAgent:- """Both of these are swept by the registry's own bookkeeping rather than- called by an agent, so there is no request context to inherit — and both- are exactly the line somebody goes looking for when one agent will not stay- connected or keeps missing events."""+ """A close is swept by the registry's own bookkeeping rather than called+ by an agent, so there is no request context to inherit — and it is exactly+ the line somebody goes looking for when one agent will not stay connected.++ The buffer's overflow warning used to be tested here too. The db-buffer has+ no per-agent cap, so that warning is gone; what replaced it, retention, is+ a per-tenant sweep that counts what it deletes rather than logging it per+ agent (see test_agent_protocol_metrics)."""def test_a_closing_connection_carries_the_agent(self, captured: _Capture) -> None:registry = AgentConnectionRegistry()@@ -128,7 +131,7 @@ class TestTheProtocolBindsItsAgent:scope="single", # type: ignore[arg-type]delivery_filter="all", # type: ignore[arg-type]spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)@@ -139,32 +142,6 @@ class TestTheProtocolBindsItsAgent:assert closed, "the registry did not report the close at all"assert all(getattr(r, "agent_id", None) == "agent-42" for r in closed)- def test_an_overflowing_buffer_carries_the_agent(self, captured: _Capture) -> None:- buffer = EventBuffer(- max_events_per_agent=2, retention_seconds=3600, sequence_base=0- )- for index in range(5):- buffer.enqueue(- "agent-99",- "room-1",- AgentEvent(- type="message",- room_id="room-1",- payload=MessagePayload(- addressed=True,- sender="@u:s",- sender_name="u",- message_id=f"$m{index}",- body="hi",- timestamp=0,- ),- ),- )-- overflow = [r for r in captured.records if "exceeded" in r.getMessage()]- assert overflow, "the buffer did not report an overflow at all"- assert all(getattr(r, "agent_id", None) == "agent-99" for r in overflow)-class TestTheBridgeInboundPathBindsItsRoom:"""`_traced` already resolves the channel's room to find the tenant, so thediff --git a/core/tests/switch_core/session_activity/test_command_relay.py b/core/tests/switch_core/session_activity/test_command_relay.pyindex c87790e9f..87405ce97 100644--- a/core/tests/switch_core/session_activity/test_command_relay.py+++ b/core/tests/switch_core/session_activity/test_command_relay.py@@ -12,6 +12,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.agent.protocol.stream import event_framesfrom switch_core.db.models import Userfrom switch_core.gateway.agent_sessions import router@@ -32,7 +33,11 @@ class _Protocol:def _watcher(- registry: AgentConnectionRegistry, *, speaks: int | None, scope: str = "all"+ registry: AgentConnectionRegistry,+ buffer: EventBuffer,+ *,+ speaks: int | None,+ scope: str = "all",):conn = registry.open(agent_id=AGENT,@@ -40,14 +45,14 @@ def _watcher(scope=scope,delivery_filter="addressed",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=speaks),expected_generation=None,)stream = event_frames(conn=conn,registry=registry,- buffer=EventBuffer(sequence_base=0),+ buffer=buffer,approvals=None,)return conn, stream@@ -73,9 +78,11 @@ async def owner(session_factory, people) -> str:return await make_agent(db, AGENT)-async def test_a_relayed_session_command_reaches_the_watcher_stream() -> None:+async def test_a_relayed_session_command_reaches_the_watcher_stream(+ db_buffer: EventBuffer,+) -> None:registry = AgentConnectionRegistry()- _, stream = _watcher(registry, speaks=PROTOCOL_VERSION)+ _, stream = _watcher(registry, db_buffer, speaks=PROTOCOL_VERSION)try:await anext(stream) # connection_statewaiting = asyncio.create_task(anext(stream))@@ -95,9 +102,11 @@ async def test_a_relayed_session_command_reaches_the_watcher_stream() -> None:(PROTOCOL_VERSION, "single"),],)-async def test_a_command_nobody_can_take_is_not_relayed(speaks, scope) -> None:+async def test_a_command_nobody_can_take_is_not_relayed(+ speaks, scope, db_buffer: EventBuffer+) -> None:registry = AgentConnectionRegistry()- conn, stream = _watcher(registry, speaks=speaks, scope=scope)+ conn, stream = _watcher(registry, db_buffer, speaks=speaks, scope=scope)conn.stream_attached = Trueassert registry.relay_session_command(AGENT, FRAME) is Falseassert conn.session_commands == []@@ -105,11 +114,11 @@ async def test_a_command_nobody_can_take_is_not_relayed(speaks, scope) -> None:async def test_switch_does_not_answer_where_an_agents_sessions_are(- session_factory, owner+ session_factory, owner, db_buffer: EventBuffer) -> None:"""The agent's room watcher owns its connection and placements; Console asks it."""registry = AgentConnectionRegistry()- _watcher(registry, speaks=PROTOCOL_VERSION)+ _watcher(registry, db_buffer, speaks=PROTOCOL_VERSION)registry.place_session(AGENT, "session-1", "room-1", f"conn-all-{PROTOCOL_VERSION}")async with _client(session_factory, registry, owner) as client:assert (await client.get("/agent-sessions/room-health")).status_code == 404diff --git a/core/tests/switch_core/session_activity/test_stop_press.py b/core/tests/switch_core/session_activity/test_stop_press.pyindex 6c8653d6c..36a37f7d3 100644--- a/core/tests/switch_core/session_activity/test_stop_press.py+++ b/core/tests/switch_core/session_activity/test_stop_press.py@@ -11,6 +11,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (AgentConnectionRegistry,ClientDeclaration,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.collaboration.collaboration_core import CollaborationCorefrom switch_core.bridges.collaboration.models import InboundInteractionfrom switch_core.bridges.collaboration.session.renderers import INTERRUPT_ACTION@@ -48,7 +49,7 @@ def _watching(registry: AgentConnectionRegistry):scope="all",delivery_filter="addressed",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=PROTOCOL_VERSION),expected_generation=None,)diff --git a/core/tests/switch_core/session_activity/test_stream_outcomes.py b/core/tests/switch_core/session_activity/test_stream_outcomes.pyindex 44e5b796c..182e844bc 100644--- a/core/tests/switch_core/session_activity/test_stream_outcomes.py+++ b/core/tests/switch_core/session_activity/test_stream_outcomes.py@@ -16,6 +16,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.bridges.agent.protocol.stream import Frame, event_framesfrom switch_core.db.models import ApprovalRequestfrom switch_core.session_activity.listener import AgentSessionActivityListener@@ -47,7 +48,14 @@ async def approvals(service, postgres_url) -> AsyncIterator[ApprovalOutcomes]:await listener.stop()-def _open_stream(approvals, *, agent_id=AGENT, scope="all", speaks=PROTOCOL_VERSION):+def _open_stream(+ approvals,+ buffer: EventBuffer,+ *,+ agent_id=AGENT,+ scope="all",+ speaks=PROTOCOL_VERSION,+):registry = AgentConnectionRegistry()conn = registry.open(agent_id=agent_id,@@ -55,14 +63,14 @@ def _open_stream(approvals, *, agent_id=AGENT, scope="all", speaks=PROTOCOL_VERSscope=scope,delivery_filter="addressed",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(speaks=speaks),expected_generation=None,)return event_frames(conn=conn,registry=registry,- buffer=EventBuffer(sequence_base=0),+ buffer=buffer,approvals=approvals,)@@ -98,9 +106,11 @@ async def _open(service, request_id="req-1", **overrides):return await service.open_approval(AGENT, SESSION, **values)-async def test_an_answer_is_pushed_down_the_open_stream(service, approvals, people):+async def test_an_answer_is_pushed_down_the_open_stream(+ service, approvals, people, db_buffer+):await _open(service)- stream = _open_stream(approvals)+ stream = _open_stream(approvals, db_buffer)try:await anext(stream) # connection_statewaiting = asyncio.create_task(anext(stream))@@ -126,7 +136,7 @@ async def test_an_answer_is_pushed_down_the_open_stream(service, approvals, peopasync def test_an_outcome_owed_from_before_the_stream_opened_is_sent_first(- service, approvals, people+ service, approvals, people, db_buffer):await _open(service)await service.answer_approval(@@ -136,7 +146,7 @@ async def test_an_outcome_owed_from_before_the_stream_opened_is_sent_first(answer=pick("deny"),answerer=PlatformPerson(people.owner),)- stream = _open_stream(approvals)+ stream = _open_stream(approvals, db_buffer)try:await anext(stream) # connection_stateoutcome = _outcome(await asyncio.wait_for(anext(stream), 5))@@ -145,7 +155,9 @@ async def test_an_outcome_owed_from_before_the_stream_opened_is_sent_first(await stream.aclose()-async def test_an_acknowledged_outcome_is_not_sent_again(service, approvals, people):+async def test_an_acknowledged_outcome_is_not_sent_again(+ service, approvals, people, db_buffer+):await _open(service)await service.answer_approval(AGENT,@@ -155,7 +167,7 @@ async def test_an_acknowledged_outcome_is_not_sent_again(service, approvals, peoanswerer=PlatformPerson(people.owner),)await service.mark_delivered(AGENT, SESSION, "req-1")- stream = _open_stream(approvals)+ stream = _open_stream(approvals, db_buffer)try:await anext(stream) # connection_stateawait _no_frame_within(stream, 0.5)@@ -163,9 +175,9 @@ async def test_an_acknowledged_outcome_is_not_sent_again(service, approvals, peoawait stream.aclose()-async def test_an_expiry_is_pushed(service, approvals, session_factory):+async def test_an_expiry_is_pushed(service, approvals, session_factory, db_buffer):await _open(service, expires_at=datetime.now(UTC) + timedelta(minutes=5))- stream = _open_stream(approvals)+ stream = _open_stream(approvals, db_buffer)try:await anext(stream) # connection_statewaiting = asyncio.create_task(anext(stream))@@ -184,13 +196,13 @@ async def test_an_expiry_is_pushed(service, approvals, session_factory):async def test_only_the_agents_own_watcher_stream_hears_its_outcomes(- service, approvals, people, session_factory+ service, approvals, people, session_factory, db_buffer):async with session_factory() as db, db.begin():await make_agent(db, "other-agent")await _open(service)- other = _open_stream(approvals, agent_id="other-agent")- session_stream = _open_stream(approvals, scope="single")+ other = _open_stream(approvals, db_buffer, agent_id="other-agent")+ session_stream = _open_stream(approvals, db_buffer, scope="single")try:await anext(other)await anext(session_stream)@@ -208,7 +220,7 @@ async def test_only_the_agents_own_watcher_stream_hears_its_outcomes(await session_stream.aclose()-async def test_a_stream_without_approvals_carries_none(service, people):+async def test_a_stream_without_approvals_carries_none(service, people, db_buffer):await _open(service)await service.answer_approval(AGENT,@@ -217,7 +229,7 @@ async def test_a_stream_without_approvals_carries_none(service, people):answer=pick("allow"),answerer=PlatformPerson(people.owner),)- stream = _open_stream(None)+ stream = _open_stream(None, db_buffer)try:await anext(stream)await _no_frame_within(stream, 0.3)@@ -226,7 +238,7 @@ async def test_a_stream_without_approvals_carries_none(service, people):async def test_a_client_that_declared_no_revision_is_sent_none(- service, approvals, people+ service, approvals, people, db_buffer):# An older client hands unknown frames to its room-event path and breaks.await _open(service)@@ -237,7 +249,7 @@ async def test_a_client_that_declared_no_revision_is_sent_none(answer=pick("allow"),answerer=PlatformPerson(people.owner),)- stream = _open_stream(approvals, speaks=None)+ stream = _open_stream(approvals, db_buffer, speaks=None)try:await anext(stream)await _no_frame_within(stream, 0.3)diff --git a/core/tests/switch_core/telemetry/test_emitters_are_live.py b/core/tests/switch_core/telemetry/test_emitters_are_live.pyindex 466c266ae..4ed0d087d 100644--- a/core/tests/switch_core/telemetry/test_emitters_are_live.py+++ b/core/tests/switch_core/telemetry/test_emitters_are_live.py@@ -52,7 +52,7 @@ def _build(telemetry: TelemetryService) -> Any:room_service=object(), # type: ignore[arg-type]client_lifecycle=object(), # type: ignore[arg-type]collab_lifecycle=object(), # type: ignore[arg-type]- event_buffer=EventBuffer(sequence_base=0),+ event_buffer=EventBuffer(object(), sequence_base=0), # type: ignore[arg-type]task_store=object(), # type: ignore[arg-type]resource_service=object(), # type: ignore[arg-type]api_key_store=object(), # type: ignore[arg-type]diff --git a/core/tests/switch_core/telemetry/test_merge_fixes.py b/core/tests/switch_core/telemetry/test_merge_fixes.pyindex 1f0784b69..09aef5a8d 100644--- a/core/tests/switch_core/telemetry/test_merge_fixes.py+++ b/core/tests/switch_core/telemetry/test_merge_fixes.py@@ -25,6 +25,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (ClientDeclaration,Closure,)+from switch_core.bridges.agent.protocol.positions import OWN_EVENTSfrom switch_core.telemetry.service import TelemetryServicefrom switch_core.telemetry.sink import TelemetryRecord@@ -154,7 +155,7 @@ class TestASessionIsTheAgentNotTheConnection:scope="all",delivery_filter="all",spawn_capable=False,- cursor=0,+ position={OWN_EVENTS: 0},declaration=ClientDeclaration(),expected_generation=None,)diff --git a/core/tests/switch_core/test_ingress_agent_api_paths.py b/core/tests/switch_core/test_ingress_agent_api_paths.pyindex 0f3d08dcb..fdd063dbf 100644--- a/core/tests/switch_core/test_ingress_agent_api_paths.py+++ b/core/tests/switch_core/test_ingress_agent_api_paths.py@@ -53,7 +53,7 @@ def _served_prefixes() -> set[str]:room_service=object(), # type: ignore[arg-type]client_lifecycle=object(), # type: ignore[arg-type]collab_lifecycle=object(), # type: ignore[arg-type]- event_buffer=EventBuffer(sequence_base=0),+ event_buffer=EventBuffer(object(), sequence_base=0), # type: ignore[arg-type]task_store=object(), # type: ignore[arg-type]resource_service=object(), # type: ignore[arg-type]api_key_store=object(), # type: ignore[arg-type]