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
"""`/chats`: Switch Console's view of the rooms a person is a member of.
Every route except creating a chat requires the caller's membership of the
room (`ChatService.require_member`); adding a member or adding or removing
an agent requires managing it.
With `agent_chats` on, owning an agent in a chat one started keeps one a
member of it (`sync_owned_rooms`), so the list, the event stream and the room
routes bring that up to date first.
Refusals are `ChatError`s, answered as `{"detail": {"code", "message"}}`.
"""
from __future__ import annotations
import asyncio
import contextlib
import json
import logging
import time
from collections.abc import AsyncIterator, Awaitable, Callable
from datetime import datetime
from typing import Annotated, Any, Literal
from fastapi import (
APIRouter,
Depends,
File,
Form,
HTTPException,
Query,
Request,
Response,
UploadFile,
)
from fastapi.responses import JSONResponse, StreamingResponse
from sqlalchemy.ext.asyncio import AsyncSession
from switch_core.bridges.agent.commands import COMMANDS
from switch_core.chats.service import (
ChatError,
ChatService,
RemovalReason,
RoomControl,
)
from switch_core.chats.views import (
CamelModel,
ChatMember,
ChatMention,
ChatMessage,
ChatSummary,
chat_messages,
chat_summaries,
)
from switch_core.db.models import (
AgentSessionActivityItem,
Room,
User,
require_tenant_id,
)
from switch_core.db.session_scope import tenant_session
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway.agent_sessions import ApprovalRequestView
from switch_core.gateway.auth import get_current_user, session_is_current
from switch_core.gateway.dependencies import get_user_store
from switch_core.session_activity.listener import Change, RoomSubscription
logger = logging.getLogger(__name__)
router = APIRouter()
PING_SECONDS = 20.0
ACTIVITY_QUEUE_MAX = 256
RECHECK_SECONDS = 30.0
_CATCH_UP_PAGE = 200
# Revisions one activity stream remembers before forgetting them all.
_ACTIVITY_SENT_MAX = 10_000
# Activity stream wake-ups that are not a change: reload everything, or
# re-read the caller's rooms.
_RESYNC = object()
_MEMBERSHIPS = object()
MAX_PAGE = 200
def get_chat_service(request: Request) -> ChatService:
return request.app.state.chat_service # type: ignore[no-any-return]
async def chat_error_response(_request: Request, exc: Exception) -> JSONResponse:
assert isinstance(exc, ChatError)
return JSONResponse(
status_code=exc.status,
content={"detail": {"code": exc.code, "message": exc.message}},
)
class ChatList(CamelModel):
chats: list[ChatSummary]
class ChatEnvelope(CamelModel):
chat: ChatSummary
class CreateChatRequest(CamelModel):
"""`agentIds` names the chat's agents, none or more; `agentId` is the
one-agent form earlier clients send. Exactly one of the two is given.
`memberUserIds` are the other people to add."""
agent_id: str | None = None
agent_ids: list[str] | None = None
member_user_ids: list[str] = []
name: str | None = None
request_id: str
# What the agent says as it joins, instead of its usual line; older
# clients send none.
greeting: str | None = None
# "group" makes a group even of one agent and nobody else, which would
# otherwise be a direct chat; older clients send none.
kind: Literal["group"] | None = None
# Makes the direct chat a private channel on this collaboration bridge
# (Slack), with the caller's own linked account; older clients send none.
bridge_id: str | None = None
# Only finishes the create this request id already started: 404 when it
# started none; older clients send none.
resume_only: bool = False
def chosen_agents(self) -> list[str]:
if (self.agent_id is None) == (self.agent_ids is None):
raise ChatError(
422,
"AGENTS_REQUIRED",
"Name the chat's agents in agentIds, or one in agentId; not both.",
)
ids = [self.agent_id] if self.agent_id is not None else self.agent_ids or []
return list(dict.fromkeys(ids))
class MessagePage(CamelModel):
messages: list[ChatMessage]
head_seq: int
has_more: bool
class SendRequest(CamelModel):
request_id: str
body: str
thread_root_id: str | None = None
upload_ids: list[str] = []
mention_agent_id: str | None = None
mention_agent_ids: list[str] = []
mention_user_ids: list[str] = []
mention_spans: list[ChatMention] = []
class ControlRequest(CamelModel):
request_id: str
agent_id: str
command: RoomControl
# The message whose turn a `retry` runs again; absent for every other control.
message_id: str | None = None
class ControlAccepted(CamelModel):
"""The command is posted, not done: the agent answers it in the room,
in a thread rooted at `commandId`."""
command_id: str
class SentMessages(CamelModel):
messages: list[ChatMessage]
class StagedUploadResponse(CamelModel):
upload_id: str
uri: str
filename: str
mimetype: str
size: int
class MemberList(CamelModel):
members: list[ChatMember]
class ChatCommand(CamelModel):
name: str
description: str
# How it is typed, with its arguments: `!reset <target>`.
usage: str
class ChatCommands(CamelModel):
commands: list[ChatCommand]
class AddMemberRequest(CamelModel):
user_id: str
class AddAgentRequest(CamelModel):
agent_id: str
class ActivityItemView(CamelModel):
"""One step of a turn; `revision` only grows, so a lower one is stale."""
agent_id: str
session_id: str
turn_id: str
item_id: str
kind: str
revision: int
status: str
title: str
text: str
command_id: str | None
room_id: str | None
thread_id: str | None
message_id: str | None
occurred_at: datetime
created_at: datetime
updated_at: datetime
@classmethod
def of(cls, row: AgentSessionActivityItem) -> ActivityItemView:
return cls(
agent_id=row.agent_id,
session_id=row.session_id,
turn_id=row.turn_id,
item_id=row.item_id,
kind=row.kind,
revision=row.revision,
status=row.status,
title=row.title,
text=row.text,
command_id=row.command_id,
room_id=row.room_id,
thread_id=row.thread_id,
message_id=row.message_id,
occurred_at=row.occurred_at,
created_at=row.created_at,
updated_at=row.updated_at,
)
class RoomActivity(CamelModel):
items: list[ActivityItemView]
approvals: list[ApprovalRequestView]
Service = Annotated[ChatService, Depends(get_chat_service)]
CurrentUser = Annotated[User, Depends(get_current_user)]
async def _summary(
service: ChatService, session: AsyncSession, tenant_id: str, user: User, room: Room
) -> ChatSummary:
[summary] = await _summaries(service, session, tenant_id, user, [room])
return summary
async def _summaries(
service: ChatService,
session: AsyncSession,
tenant_id: str,
user: User,
rooms: list[Room],
) -> list[ChatSummary]:
"""The rooms' summaries, read in a fixed number of queries."""
if not rooms:
return []
administers = await service.administers(session, tenant_id, user)
return await chat_summaries(
session,
rooms,
viewer_id=user.id,
can_manage={
room.id: administers
or (room.owner_id is not None and room.owner_id == user.id)
for room in rooms
},
)
async def _member_list(
service: ChatService, session: AsyncSession, room: Room
) -> MemberList:
return MemberList(
members=[
ChatMember(user_id=member.id, name=member.name, is_owner=is_owner)
for member, is_owner in await service.members(session, room)
]
)
@router.get("", response_model=ChatList)
async def list_chats(user: CurrentUser, service: Service) -> ChatList:
tenant_id = require_tenant_id()
await service.sync_owned_rooms(tenant_id, user.id)
async with tenant_session(service.session_factory, tenant_id) as session:
if not await service.has_tenant_role(session, tenant_id, user.id):
return ChatList(chats=[])
rooms = await service.list_chats(session, user.id)
return ChatList(
chats=await _summaries(service, session, tenant_id, user, rooms)
)
@router.get("/archived", response_model=ChatList)
async def list_archived_chats(user: CurrentUser, service: Service) -> ChatList:
"""The caller's archived chats: those `GET /chats` would list were they
not archived, hidden ones included."""
tenant_id = require_tenant_id()
async with tenant_session(service.session_factory, tenant_id) as session:
if not await service.has_tenant_role(session, tenant_id, user.id):
return ChatList(chats=[])
rooms = await service.archived_chats(session, user.id)
return ChatList(
chats=await _summaries(service, session, tenant_id, user, rooms)
)
@router.post("", response_model=ChatEnvelope)
async def create_chat(
req: CreateChatRequest, user: CurrentUser, service: Service
) -> ChatEnvelope:
tenant_id = require_tenant_id()
room = await service.create_chat(
tenant_id,
user,
agent_ids=req.chosen_agents(),
member_user_ids=req.member_user_ids,
name=req.name,
request_id=req.request_id,
greeting=req.greeting,
kind=req.kind,
bridge_id=req.bridge_id,
resume_only=req.resume_only,
)
async with tenant_session(service.session_factory, tenant_id) as session:
return ChatEnvelope(
chat=await _summary(service, session, tenant_id, user, room)
)
def _session_check(
service: ChatService, user_store: UserStore, user: User
) -> Callable[[], Awaitable[bool]]:
"""What a stream asks at each re-read: whether the session it was opened
with still stands, or the account's sessions have been ended since."""
session_version = user.session_version
async def still_current() -> bool:
return await session_is_current(
service.session_factory, user_store, user.id, session_version
)
return still_current
@router.get("/events")
async def chat_events_stream(
user: CurrentUser,
service: Service,
user_store: Annotated[UserStore, Depends(get_user_store)],
after: Annotated[str | None, Query()] = None,
) -> StreamingResponse:
tenant_id = require_tenant_id()
return StreamingResponse(
chat_events(
service,
tenant_id,
user,
parse_after(after),
ping_seconds=PING_SECONDS,
recheck_seconds=RECHECK_SECONDS,
session_current=_session_check(service, user_store, user),
),
media_type="text/event-stream",
headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
)
class AgentCandidates(CamelModel):
agent_ids: list[str]
@router.get("/agent-candidates", response_model=AgentCandidates)
async def agent_candidates(
user: CurrentUser,
service: Service,
room_id: Annotated[str | None, Query(alias="roomId")] = None,
) -> AgentCandidates:
"""The agents the caller could add to a new chat, or with `roomId` to
that chat, which they must manage."""
tenant_id = require_tenant_id()
async with tenant_session(service.session_factory, tenant_id) as session:
return AgentCandidates(
agent_ids=await service.agent_candidates(session, tenant_id, user, room_id)
)
@router.get("/activity/events")
async def chat_activity_stream(
user: CurrentUser,
service: Service,
user_store: Annotated[UserStore, Depends(get_user_store)],
) -> StreamingResponse:
tenant_id = require_tenant_id()
return StreamingResponse(
chat_activity_events(
service,
tenant_id,
user,
ping_seconds=PING_SECONDS,
recheck_seconds=RECHECK_SECONDS,
queue_max=ACTIVITY_QUEUE_MAX,
session_current=_session_check(service, user_store, user),
),
media_type="text/event-stream",
headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
)
@router.get("/{room_id}/activity", response_model=RoomActivity)
async def room_activity(
room_id: str, user: CurrentUser, service: Service
) -> RoomActivity:
tenant_id = require_tenant_id()
async with tenant_session(service.session_factory, tenant_id) as session:
room, _ = await service.require_member(session, tenant_id, user, room_id)
items, approvals = await service.room_activity(session, room.id)
return RoomActivity(
items=[ActivityItemView.of(row) for row in items],
approvals=[ApprovalRequestView.of(row) for row in approvals],
)
@router.get("/{room_id}/messages", response_model=MessagePage)
async def list_messages(
room_id: str,
user: CurrentUser,
service: Service,
before_seq: Annotated[int | None, Query(alias="beforeSeq")] = None,
limit: Annotated[int, Query(ge=1, le=MAX_PAGE)] = 50,
) -> MessagePage:
tenant_id = require_tenant_id()
async with tenant_session(service.session_factory, tenant_id) as session:
room, _ = await service.require_member(session, tenant_id, user, room_id)
rows, head_seq, has_more = await service.page(
session, room.id, before_seq, limit
)
return MessagePage(
messages=await chat_messages(session, room, rows),
head_seq=head_seq,
has_more=has_more,
)
@router.get("/{room_id}/threads/{root_id}/messages", response_model=MessagePage)
async def list_thread_messages(
room_id: str,
root_id: str,
user: CurrentUser,
service: Service,
before_seq: Annotated[int | None, Query(alias="beforeSeq")] = None,
limit: Annotated[int, Query(ge=1, le=MAX_PAGE)] = 50,
) -> MessagePage:
"""The thread's replies, paged like `/messages`; the root is not one."""
tenant_id = require_tenant_id()
async with tenant_session(service.session_factory, tenant_id) as session:
room, _ = await service.require_member(session, tenant_id, user, room_id)
rows, head_seq, has_more = await service.thread_page(
session, room, root_id, before_seq, limit
)
return MessagePage(
messages=await chat_messages(session, room, rows),
head_seq=head_seq,
has_more=has_more,
)
@router.post("/{room_id}/attachments", response_model=StagedUploadResponse)
async def upload_attachment(
room_id: str,
user: CurrentUser,
service: Service,
file: Annotated[UploadFile, File()],
upload_id: Annotated[str, Form(alias="uploadId")],
) -> StagedUploadResponse:
tenant_id = require_tenant_id()
staged = await service.stage_upload(
tenant_id,
user,
room_id,
upload_id=upload_id,
data=await file.read(),
filename=file.filename or "attachment",
mimetype=file.content_type or "application/octet-stream",
)
return StagedUploadResponse(
upload_id=staged.upload_id,
uri=staged.uri,
filename=staged.filename,
mimetype=staged.mimetype,
size=staged.size,
)
@router.post("/{room_id}/messages", response_model=SentMessages)
async def send_message(
room_id: str, req: SendRequest, user: CurrentUser, service: Service
) -> SentMessages:
tenant_id = require_tenant_id()
room, posted = await service.send(
tenant_id,
user,
room_id,
request_id=req.request_id,
body=req.body,
thread_root_id=req.thread_root_id,
upload_ids=req.upload_ids,
mention_agent_id=req.mention_agent_id,
mention_agent_ids=req.mention_agent_ids,
mention_user_ids=req.mention_user_ids,
mention_spans=req.mention_spans,
)
async with tenant_session(service.session_factory, tenant_id) as session:
return SentMessages(messages=await chat_messages(session, room, posted))
@router.post("/{room_id}/controls", response_model=ControlAccepted, status_code=202)
async def send_control(
room_id: str, req: ControlRequest, user: CurrentUser, service: Service
) -> ControlAccepted:
command_id = await service.control(
require_tenant_id(),
user,
room_id,
request_id=req.request_id,
agent_id=req.agent_id,
command=req.command,
message_id=req.message_id,
)
return ControlAccepted(command_id=command_id)
class WarmRequest(CamelModel):
agent_id: str
@router.post("/{room_id}/warm", status_code=202)
async def warm_agent(
room_id: str, req: WarmRequest, user: CurrentUser, service: Service
) -> Response:
await service.warm(require_tenant_id(), user, room_id, agent_id=req.agent_id)
return Response(status_code=202)
@router.get("/{room_id}/media")
async def get_media(
room_id: str,
user: CurrentUser,
service: Service,
uri: Annotated[str, Query()],
) -> Response:
tenant_id = require_tenant_id()
async with tenant_session(service.session_factory, tenant_id) as session:
room, _ = await service.require_member(session, tenant_id, user, room_id)
blob = await service.media(session, room, uri)
return Response(
content=blob.data,
media_type=blob.content_type or "application/octet-stream",
headers={"Cache-Control": "private, no-store"},
)
@router.get("/{room_id}/members", response_model=MemberList)
async def list_members(room_id: str, user: CurrentUser, service: Service) -> MemberList:
tenant_id = require_tenant_id()
async with tenant_session(service.session_factory, tenant_id) as session:
room, _ = await service.require_member(session, tenant_id, user, room_id)
return await _member_list(service, session, room)
@router.get("/{room_id}/commands", response_model=ChatCommands)
async def list_commands(
room_id: str, user: CurrentUser, service: Service
) -> ChatCommands:
"""The room commands a member can type here (`!name`), as the platforms'
command lists show them: those that do something and are not hidden."""
tenant_id = require_tenant_id()
async with tenant_session(service.session_factory, tenant_id) as session:
await service.require_member(session, tenant_id, user, room_id)
return ChatCommands(
commands=[
ChatCommand(
name=command.name,
description=command.description,
usage=" ".join(
[
f"!{command.name}",
*(f"<{arg.name}>" for arg in command.args_spec),
]
),
)
for command in COMMANDS
if command.handler is not None
and not command.hidden
and command.description.strip()
]
)
@router.post("/{room_id}/members", response_model=MemberList)
async def add_member(
room_id: str, req: AddMemberRequest, user: CurrentUser, service: Service
) -> MemberList:
"""Manager only, and the one route a non-member may call: a manager may
add themselves to a room they manage."""
tenant_id = require_tenant_id()
room = await service.add_member(tenant_id, user, room_id, req.user_id)
async with tenant_session(service.session_factory, tenant_id) as session:
return await _member_list(service, session, room)
@router.delete("/{room_id}/members/{member_user_id}", status_code=204)
async def remove_member(
room_id: str, member_user_id: str, user: CurrentUser, service: Service
) -> Response:
await service.remove_member(require_tenant_id(), user, room_id, member_user_id)
return Response(status_code=204)
@router.post("/{room_id}/agents", response_model=ChatEnvelope)
async def add_agent(
room_id: str, req: AddAgentRequest, user: CurrentUser, service: Service
) -> ChatEnvelope:
"""Manager only, and only an agent the manager may use in this room."""
tenant_id = require_tenant_id()
room = await service.add_agent(tenant_id, user, room_id, req.agent_id)
async with tenant_session(service.session_factory, tenant_id) as session:
return ChatEnvelope(
chat=await _summary(service, session, tenant_id, user, room)
)
@router.delete("/{room_id}/agents/{agent_id}", status_code=204)
async def remove_agent(
room_id: str, agent_id: str, user: CurrentUser, service: Service
) -> Response:
await service.remove_agent(require_tenant_id(), user, room_id, agent_id)
return Response(status_code=204)
class ReadRequest(CamelModel):
seq: int
@router.put("/{room_id}/read", status_code=204)
async def mark_read(
room_id: str, req: ReadRequest, user: CurrentUser, service: Service
) -> Response:
"""The caller has been shown the chat up to `seq`; never moves back."""
await service.mark_read(require_tenant_id(), user, room_id, req.seq)
return Response(status_code=204)
@router.put("/{room_id}/hidden", status_code=204)
async def hide_chat(room_id: str, user: CurrentUser, service: Service) -> Response:
await service.set_hidden(require_tenant_id(), user, room_id, True)
return Response(status_code=204)
@router.delete("/{room_id}/hidden", status_code=204)
async def unhide_chat(room_id: str, user: CurrentUser, service: Service) -> Response:
await service.set_hidden(require_tenant_id(), user, room_id, False)
return Response(status_code=204)
@router.post("/{room_id}/archive", status_code=204)
async def archive_chat(room_id: str, user: CurrentUser, service: Service) -> Response:
await service.archive(require_tenant_id(), user, room_id)
return Response(status_code=204)
@router.post("/{room_id}/unarchive", status_code=204)
async def unarchive_chat(room_id: str, user: CurrentUser, service: Service) -> Response:
await service.unarchive(require_tenant_id(), user, room_id)
return Response(status_code=204)
# ── Live updates ─────────────────────────────────────────────────────────────
def parse_after(raw: str | None) -> dict[str, int]:
"""`roomId:seq,roomId:seq` → `{roomId: seq}`."""
cursors: dict[str, int] = {}
for item in (raw or "").split(","):
if not item:
continue
room_id, sep, seq = item.rpartition(":")
if not sep or not room_id:
raise HTTPException(422, f"Malformed cursor: {item!r}")
try:
cursors[room_id] = int(seq)
except ValueError as exc:
raise HTTPException(422, f"Malformed cursor: {item!r}") from exc
return cursors
def _frame(event: str, data: object) -> bytes:
return f"event: {event}\ndata: {json.dumps(data)}\n\n".encode()
def _removed(room_id: str, reason: RemovalReason) -> bytes:
"""`chat.removed`: "access" when the caller lost the room (membership,
tenant role), "unlisted" when they are still a member but it no longer
qualifies for the list (no agents left, archived)."""
return _frame("chat.removed", {"roomId": room_id, "reason": reason})
class _ChatStream:
"""One caller's live view of their chats.
Every wake-up re-reads what the caller may see before reading anything
else, so a removal from a room or from the tenant ends that room's events
at once. Database sessions are opened per pass and closed before waiting.
"""
def __init__(
self, service: ChatService, tenant_id: str, user: User, after: dict[str, int]
) -> None:
self.service = service
self.tenant_id = tenant_id
self.user = user
self.after = after
self.cursors: dict[str, int] = {}
self.announced: set[str] = set()
self.sent: dict[str, dict[str, Any]] = {}
self.resummarize = False
self.resummarize_rooms: set[str] = set()
self.dirty: set[str] = set()
self.wake = asyncio.Event()
async def on_room(self, room_id: str) -> None:
self.dirty.add(room_id)
self.wake.set()
def on_memberships(self, room_ids: list[str] | None) -> None:
if room_ids is None:
self.resummarize = True
else:
self.resummarize_rooms.update(room_ids)
self.wake.set()
def close(self) -> None:
for room_id in self.cursors:
self.service.listener.unsubscribe(room_id, self.on_room)
self.cursors.clear()
def _untrack(self, room_id: str, reason: RemovalReason) -> bytes:
self.service.listener.unsubscribe(room_id, self.on_room)
self.cursors.pop(room_id, None)
self.sent.pop(room_id, None)
return _removed(room_id, reason)
async def refresh(
self, read: set[str] | None, initial: bool
) -> tuple[list[bytes], bool]:
"""Frames for what changed, and whether the stream may continue.
`read` names the rooms to read new messages from; None reads all,
and first brings the caller's agent-owner memberships up to date.
"""
frames: list[bytes] = []
service = self.service
resummarize, self.resummarize = self.resummarize, False
resummarize_rooms, self.resummarize_rooms = self.resummarize_rooms, set()
if read is None:
await service.sync_owned_rooms(self.tenant_id, self.user.id)
async with tenant_session(service.session_factory, self.tenant_id) as session:
if not await service.has_tenant_role(session, self.tenant_id, self.user.id):
frames.extend(
self._untrack(room_id, "access") for room_id in list(self.cursors)
)
frames.extend(
_removed(room_id, "access") for room_id in self.after if initial
)
return frames, False
rooms = await service.readable_and_listed(session, self.user.id)
readable = {room.id: room for room, _ in rooms}
listed = {room.id: room for room, is_listed in rooms if is_listed}
for room_id in [r for r in self.cursors if r not in readable]:
frames.append(self._untrack(room_id, "access"))
if initial:
for room_id in self.after:
if room_id not in readable:
frames.append(_removed(room_id, "access"))
elif room_id not in listed:
frames.append(_removed(room_id, "unlisted"))
for room_id in [
r for r in self.announced if r in readable and r not in listed
]:
frames.append(_removed(room_id, "unlisted"))
self.announced.discard(room_id)
self.sent.pop(room_id, None)
new = [room_id for room_id in readable if room_id not in self.cursors]
heads = (
await service.head_seqs(
session, [r for r in new if r not in self.after]
)
if initial
else {}
)
announce: list[Room] = []
for room_id in new:
room = readable[room_id]
if initial and room_id in self.after:
self.cursors[room_id] = self.after[room_id]
if room_id in listed:
self.announced.add(room_id)
else:
if room_id in listed:
announce.append(room)
# A room joined since the stream opened is followed from
# where the caller joined it, so whatever was said before
# the stream noticed it is still sent.
self.cursors[room_id] = (
heads[room_id]
if initial
else await service.read_position(session, self.user.id, room_id)
)
service.listener.subscribe(room_id, self.on_room)
for room_id, room in listed.items():
if room not in announce and (
room_id not in self.announced
or resummarize
or room_id in resummarize_rooms
):
announce.append(room)
frames.extend(await self._announce(session, announce))
self.announced.update(room.id for room in announce)
to_read = [
room_id
for room_id in (list(self.cursors) if read is None else read)
if room_id in readable
]
# One look at which rooms moved past their cursors, then reads only
# those: a recheck of quiet rooms costs one query, and fetches none.
moved = await service.moved_rooms(
session, {room_id: self.cursors[room_id] for room_id in to_read}
)
for room_id in to_read:
if room_id in moved:
frames.extend(await self._read(session, readable[room_id]))
return frames, True
async def _announce(self, session: AsyncSession, rooms: list[Room]) -> list[bytes]:
"""`chat` frames for the rooms whose summary differs from the last sent."""
frames: list[bytes] = []
for room, summary in zip(
rooms,
await _summaries(self.service, session, self.tenant_id, self.user, rooms),
strict=True,
):
dump = summary.model_dump(by_alias=True)
if self.sent.get(room.id) == dump:
continue
self.sent[room.id] = dump
frames.append(_frame("chat", dump))
return frames
async def _read(self, session: AsyncSession, room: Room) -> list[bytes]:
frames: list[bytes] = []
while True:
rows = await self.service.messages_after(
session, room.id, self.cursors[room.id], _CATCH_UP_PAGE
)
if not rows:
return frames
self.cursors[room.id] = rows[-1].seq
frames.extend(
_frame("message", message.model_dump(by_alias=True))
for message in await chat_messages(session, room, rows)
)
if len(rows) < _CATCH_UP_PAGE:
return frames
async def chat_events(
service: ChatService,
tenant_id: str,
user: User,
after: dict[str, int],
*,
ping_seconds: float,
recheck_seconds: float,
session_current: Callable[[], Awaitable[bool]],
) -> AsyncIterator[bytes]:
"""The caller's chat events as SSE frames.
Catches every member room up from its cursor in `after`, says `ready`,
then pushes as rooms move. A room the caller joined since is announced as
`chat` and followed from its head; one that leaves the list is `chat.removed`.
A change to the caller's chats wakes the stream at once, whichever process
made it (`chats/signals.py`). A re-read every `recheck_seconds` recovers
anything a missed notification or a missed signal left behind, and ends
the stream once the caller's session no longer `session_current`.
"""
stream = _ChatStream(service, tenant_id, user, after)
service.watch_memberships(tenant_id, user.id, stream.on_memberships)
try:
frames, alive = await stream.refresh(None, initial=True)
for frame in frames:
yield frame
if not alive:
return
yield _frame("ready", {})
now = time.monotonic()
next_ping = now + ping_seconds
next_recheck = now + recheck_seconds
while True:
timeout = max(0.0, min(next_ping, next_recheck) - time.monotonic())
try:
await asyncio.wait_for(stream.wake.wait(), timeout=timeout)
except TimeoutError:
pass
now = time.monotonic()
if now >= next_ping:
next_ping = now + ping_seconds
yield b": ping\n\n"
read: set[str] | None
if now >= next_recheck:
if not await session_current():
return
next_recheck = now + recheck_seconds
read = None
elif stream.wake.is_set():
read = set(stream.dirty)
else:
continue
stream.wake.clear()
stream.dirty.clear()
frames, alive = await stream.refresh(read, initial=False)
for frame in frames:
yield frame
if not alive:
return
finally:
service.unwatch_memberships(tenant_id, user.id, stream.on_memberships)
stream.close()
async def chat_activity_events(
service: ChatService,
tenant_id: str,
user: User,
*,
ping_seconds: float,
recheck_seconds: float,
queue_max: int,
session_current: Callable[[], Awaitable[bool]],
) -> AsyncIterator[bytes]:
"""Turn steps and approval requests of the rooms the caller may read, as SSE.
Says `ready` once subscribed, so a snapshot fetched after it misses
nothing. Only changes in the caller's rooms wake the stream; the rooms are
re-read when the caller's chats change, on a resync and every
`recheck_seconds`. Readability is still checked on every change, so
leaving a room stops its frames at once. `resync` means changes may have
been missed (the listener reconnected, this connection fell behind, or the
caller joined a room): reload snapshots. Each re-read first ends the
stream if the caller's session no longer `session_current`.
"""
queue: asyncio.Queue[object] = asyncio.Queue(maxsize=queue_max)
def resync() -> None:
while not queue.empty():
queue.get_nowait()
queue.put_nowait(_RESYNC)
def put(item: object) -> None:
try:
queue.put_nowait(item)
except asyncio.QueueFull:
resync()
async def on_change(change: Change) -> None:
put(change)
async def on_resync() -> None:
resync()
def on_memberships(_room_ids: list[str] | None) -> None:
# Whichever rooms changed, the readable set is read again.
put(_MEMBERSHIPS)
service.watch_memberships(tenant_id, user.id, on_memberships)
subscription: RoomSubscription | None = None
# Per-connection, so a turn reread on every change resends only moved steps.
sent: dict[tuple[str, str, str, str], int] = {}
try:
await service.sync_owned_rooms(tenant_id, user.id)
rooms = await _readable_room_ids(service, tenant_id, user)
if rooms is None:
return
subscription = service.activity_listener.subscribe_rooms(
tenant_id, rooms, on_change, on_resync
)
yield _frame("ready", {})
now = time.monotonic()
next_ping = now + ping_seconds
next_recheck = now + recheck_seconds
while True:
timeout = max(0.0, min(next_ping, next_recheck) - time.monotonic())
item: object = None
with contextlib.suppress(TimeoutError):
item = await asyncio.wait_for(queue.get(), timeout=timeout)
now = time.monotonic()
if now >= next_ping:
next_ping = now + ping_seconds
yield b": ping\n\n"
recheck = now >= next_recheck
if recheck:
if not await session_current():
return
next_recheck = now + recheck_seconds
if recheck or item is _RESYNC or item is _MEMBERSHIPS:
current = await _readable_room_ids(service, tenant_id, user)
if current is None:
return
subscription.set_rooms(current)
added = current - rooms
rooms = current
if item is _RESYNC or added:
sent.clear()
yield _frame("resync", {})
if isinstance(item, Change):
if len(sent) > _ACTIVITY_SENT_MAX:
# Forgetting only resends steps the client already holds.
sent.clear()
frames = await _activity_frames(service, tenant_id, user, item, sent)
if frames is None:
return
for frame in frames:
yield frame
finally:
if subscription is not None:
subscription.close()
service.unwatch_memberships(tenant_id, user.id, on_memberships)
async def _readable_room_ids(
service: ChatService, tenant_id: str, user: User
) -> set[str] | None:
"""The rooms the caller may read now; None once the caller has no tenant
role, which ends the stream."""
async with tenant_session(service.session_factory, tenant_id) as session:
if not await service.has_tenant_role(session, tenant_id, user.id):
return None
return {room.id for room in await service.readable_rooms(session, user.id)}
async def _activity_frames(
service: ChatService,
tenant_id: str,
user: User,
change: Change,
sent: dict[tuple[str, str, str, str], int],
) -> list[bytes] | None:
"""Frames for one change, if the caller may read its room now; None once
the caller has no tenant role, which ends the stream.
Reads only what moved: an announcement naming its step reads that one
row, and none at all when a revision at least as new was already sent, so
a burst of updates to a step is coalesced into the first read of it. An
announcement from before steps were named rereads the turn."""
if change.kind == "activity" and change.item_id is not None:
key = (change.agent_id, change.session_id, change.key, change.item_id)
if change.revision is not None and sent.get(key, -1) >= change.revision:
return []
async with tenant_session(service.session_factory, tenant_id) as session:
member, reads = await service.reads_room(
session, tenant_id, user.id, change.room_id
)
if not member:
return None
if not reads:
return []
if change.kind == "activity":
if change.item_id is not None:
item = await service.turn_item(
session,
change.agent_id,
change.session_id,
change.key,
change.item_id,
)
rows = [item] if item is not None else []
else:
rows = await service.turn_items(
session, change.agent_id, change.session_id, change.key
)
frames = []
for row in rows:
key = (row.agent_id, row.session_id, row.turn_id, row.item_id)
if row.room_id == change.room_id and sent.get(key, -1) < row.revision:
sent[key] = row.revision
view = ActivityItemView.of(row)
frames.append(
_frame("activity", view.model_dump(mode="json", by_alias=True))
)
return frames
request = await service.approval(
session, change.agent_id, change.session_id, change.key
)
if request is None or request.room_id != change.room_id:
return []
approval = ApprovalRequestView.of(request)
return [_frame("approval", approval.model_dump(mode="json", by_alias=True))]