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
"""Puts session activity and requests on one bridge's platform.
Pushed, not scanned: `AgentSessionActivityListener` hands every change for the
bridge's tenant to `_on_change`, which only queues a key. A task of this
bridge's own drains the queue and does the platform work, so a slow or rate
limited platform never holds up the listener's other subscribers.
The queue has three lanes, drained most urgent first. A change just announced
is somebody waiting: a new turn's card and its π, a step. Retries, a resync's
catch-up and an agent going offline or coming back are owed but older. A
running turn's clock is cosmetic, so it waits behind both, and one the
platform refuses is dropped rather than retried: the next minute draws it.
A key queued while the same key is still waiting is dropped, and each key is
handled by reading the rows as they are now. So a burst of steps in one turn
costs one redraw rather than one per step, and a request answered before its
card was posted is posted already answered β or, if it is no longer open, not
at all.
**Requests** (approvals and questions). The card lives in
`approval_request_posts`: `token` rides in the controls and `handle` (`A<n>`)
is what a person types. The reservation is committed before the platform call,
with `external_post_id` null, so a process that dies mid-post leaves a card
marked unconfirmed rather than one posted twice; the card is then searched for
where the platform can be searched, and the channel told once where it cannot
and the platform may say so. An approval answered by a person is taken off a
platform that removes answered cards.
**Turns.** Each turn is drawn in one message, from its rows, with the adapter's
own activity rendering: every step, the stop control while it runs, and how
long it took. The asking message carries a queued or working marker while the
turn waits or runs β put on before the message is posted, so a platform short
of room for the message does not hold it back β and a platform that says a
turn is stuck in a message of its own gets one, cleared again once it no
longer applies. All of it sits in `turn_status_posts`.
Failures of a key are retried on a widening interval; a platform that asks for
a wait gets exactly that wait.
"""
from __future__ import annotations
import asyncio
import logging
import secrets
from collections import OrderedDict, deque
from collections.abc import Callable
from dataclasses import dataclass, field, replace
from datetime import UTC, datetime, timedelta
from typing import Literal, cast
from sqlalchemy import and_, exists, func, or_, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.bridges.collaboration.adapter import (
ActivityMarkRefused,
ActivitySnapshot,
PlatformAdapter,
RemovalFailed,
RichContentFailed,
RichContentFailedAfterPost,
RichContentThrottled,
RichContentWedged,
ThreadUnavailable,
TurnActivity,
)
from switch_core.bridges.collaboration.session.renderers import RUNNING_CLOCK_SECONDS
from switch_core.db.models import (
Agent,
AgentSessionActivityItem,
ApprovalRequest,
ApprovalRequestPost,
BridgeMessageMap,
Message,
Room,
TurnStatusPost,
)
from switch_core.db.session_scope import tenant_session
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.session_activity_post_store import (
ApprovalRequestPostStore,
TurnStatusPostStore,
)
from switch_core.db.stores.session_activity_store import (
TURN_ITEM_ID,
AgentSessionActivityStore,
ApprovalRequestStore,
)
from switch_core.delivery.addressing import AddressingResolver
from switch_core.session_activity.bridge_turns import (
TurnView,
status_state,
turn_view,
)
from switch_core.session_activity.cards import (
answerer_of,
approval_card,
approval_request,
)
from switch_core.session_activity.listener import AgentSessionActivityListener, Change
from switch_core.sessions.contract import DecidedBy, decided
from switch_core.sessions.presentation import (
activity_error_summary,
notification_recipient,
request_card_recipient,
)
logger = logging.getLogger(__name__)
HANDLE_PREFIX = "A"
_MINT_ATTEMPTS = 5
_HANDLE_CONSTRAINT = "uq_approval_request_posts_handle"
# An inbound message and the card answering it can race: the platform post a
# thread hangs off is mapped only once the inbound relay commits. Waited out a
# few times before the card goes to the channel root instead.
_THREAD_WAIT_SECONDS = 1.0
_THREAD_WAIT_ATTEMPTS = 5
# How far back a resync redraws settled cards and ended turns. A resync means
# announcements may have been lost; one lost a while ago has had its message
# corrected by a later resync already, and redrawing everything on each start
# would spend a platform's rate budget on messages nobody is looking at.
_RESYNC_WINDOW = timedelta(minutes=15)
# How often running turns are looked at again: for their agent going offline
# or coming back, and, where the platform redraws for it, for a clock that has
# moved on a minute.
_TICK_SECONDS = 5.0
# How long after a platform closes a turn's message on its own the redraw that
# repairs it is due, so that the redraw finds it closed.
_AFTER_PLATFORM_CLOSE = timedelta(seconds=2)
_RETRY_MIN_SECONDS = 5.0
_RETRY_MAX_SECONDS = 600.0
# How many turns' drawn state one bridge remembers. Forgetting one costs a
# redraw nobody needed if that turn changes again, not a wrong one.
_MAX_REMEMBERED_TURNS = 4096
# A card that froze in the last hour is plausibly still on someone's screen and
# misleading them; under an older one a notice reaches nobody.
_WEDGE_NOTICE_MAX_AGE = timedelta(hours=1)
_WEDGE_NOTICE = (
"β οΈ This platform dropped the live stream behind the message above, so that "
"card is frozen and cannot be updated, finished, or removed. Whatever it is "
"showing is the last thing the stream wrote, not where the turn got to β "
"the turn itself was unaffected."
)
_HOST_OFFLINE = "Host offline. Answers are unavailable until the session reconnects."
Mark = Literal["queued", "working"]
# The queue's lanes, most urgent first; see the module docstring.
_NOW = 0
_SOON = 1
_CLOCK = 2
@dataclass(frozen=True)
class _Target:
channel_id: str
thread_ref: str | None
agent: Agent
@property
def agent_name(self) -> str:
return self.agent.name
@dataclass(frozen=True)
class StopTarget:
"""What a Stop control on one of this bridge's messages would stop."""
agent_id: str
session_id: str
room_id: str
thread_id: str | None
# The session's running turn now, which the pressed control must still name.
running_turn_id: str | None
@dataclass
class _TurnDrawn:
"""What this process last showed of a turn, so an unchanged redraw is skipped."""
status_state: str | None = None
attention_state: str | None = None
status: str | None = None
final: bool = False
wedged: bool = False
# When a running turn's message is next due a redraw without a change of
# its own: its clock showing another minute, or the platform closing it.
clock_due: datetime | None = None
# When the platform closes the turn's message on its own, if it does.
platform_closes_at: datetime | None = None
@dataclass
class _Backoff:
"""A key's waits between failed attempts: doubling, capped, cleared on success."""
waits: dict[tuple[str, ...], float] = field(default_factory=dict)
def next(self, key: tuple[str, ...]) -> float:
wait = self.waits.get(key, _RETRY_MIN_SECONDS)
self.waits[key] = min(wait * 2, _RETRY_MAX_SECONDS)
return wait
def clear(self, key: tuple[str, ...]) -> None:
self.waits.pop(key, None)
class _ThreadNotMappedYet(Exception):
pass
_Key = tuple[str, ...]
_RESYNC: _Key = ("resync",)
class AgentSessionActivityPublisher:
def __init__(
self,
*,
adapter: PlatformAdapter,
bridge_id: str,
bridge_type: str,
tenant_id: str,
listener: AgentSessionActivityListener,
session_factory: async_sessionmaker[AsyncSession],
agent_online: Callable[[str], bool],
) -> None:
self._adapter = adapter
self._bridge_id = bridge_id
self._bridge_type = bridge_type
self._tenant_id = tenant_id
self._listener = listener
self._sessions = session_factory
self._agent_online = agent_online
self._approvals = ApprovalRequestStore()
self._rooms = RoomStore()
self._addressing = AddressingResolver(
room_store=self._rooms,
room_role_store=RoomRoleStore(),
client_store=ClientStore(),
agent_store=AgentStore(),
external_user_store=ExternalUserStore(),
# Only role mentions consult liveness; a permission check never does.
live_connection_ids=set,
)
self._activity = AgentSessionActivityStore()
self._card_posts = ApprovalRequestPostStore()
self._turn_posts = TurnStatusPostStore()
self._lanes: tuple[deque[_Key], ...] = (deque(), deque(), deque())
self._pending: dict[_Key, int] = {}
self._wake = asyncio.Event()
self._thread_waits: dict[_Key, int] = {}
self._retries = _Backoff()
self._drawn: OrderedDict[_Key, _TurnDrawn] = OrderedDict()
self._live_turns: dict[_Key, str] = {}
# A turn's row before its message is posted, holding the marker
# already on the asking message until the row can be stored. Only in
# memory: a restart in that window forgets the marker, and the turn
# takes it off only if it is still running when the publisher is back.
self._unposted: dict[_Key, TurnStatusPost] = {}
self._open_cards: dict[_Key, str] = {}
self._online_seen: dict[str, bool] = {}
self._unsure_marks: set[_Key] = set()
self._card_edit_failures: dict[str, tuple[str, str | None]] = {}
self._noted_unconfirmed: set[str] = set()
self._tasks: list[asyncio.Task[None]] = []
self._unsubscribe: Callable[[], None] | None = None
# ββ Lifecycle βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
def start(self) -> None:
if self._tasks:
raise RuntimeError("AgentSessionActivityPublisher is already started")
self._unsubscribe = self._listener.subscribe(
self._tenant_id, self._on_change, self._on_resync
)
self._tasks = [
asyncio.create_task(
self._run(), name=f"session-activity-bridge-{self._bridge_id}"
),
asyncio.create_task(
self._tick_forever(),
name=f"session-activity-bridge-tick-{self._bridge_id}",
),
]
# The listener resyncs its subscribers when it connects, which may have
# happened before this bridge started. The resync itself only reads and
# queues, so it goes first and what it finds owed waits its turn.
self._enqueue(_RESYNC, _NOW)
async def stop(self) -> None:
if self._unsubscribe is not None:
self._unsubscribe()
self._unsubscribe = None
tasks, self._tasks = self._tasks, []
for task in tasks:
task.cancel()
# A task that had already died is logged rather than raised: the
# bridge stopping this publisher goes on to close its platform
# connection, and a second stop has nothing left to raise.
results = await asyncio.gather(*tasks, return_exceptions=True)
for task, result in zip(tasks, results, strict=True):
if isinstance(result, Exception):
logger.error(
"Session activity task %s had stopped on an error",
task.get_name(),
exc_info=result,
)
# ββ Listener callbacks: queue only ββββββββββββββββββββββββββββββββββββββββ
async def _on_change(self, change: Change) -> None:
if change.kind.startswith("approval."):
self._enqueue(
("approval", change.agent_id, change.session_id, change.key), _NOW
)
elif change.kind == "activity":
self._enqueue(
("turn", change.agent_id, change.session_id, change.key), _NOW
)
async def _on_resync(self) -> None:
self._enqueue(_RESYNC, _NOW)
def _enqueue(self, key: _Key, lane: int) -> None:
"""Queue a key in a lane, or move it up to one if it waits in a lower one."""
queued = self._pending.get(key)
if queued is not None and queued <= lane:
return
self._pending[key] = lane
self._lanes[lane].append(key)
self._wake.set()
def _enqueue_later(self, key: _Key, delay: float, lane: int) -> None:
asyncio.get_running_loop().call_later(delay, self._enqueue, key, lane)
def _retry_later(self, key: _Key) -> None:
self._enqueue_later(key, self._retries.next(key), _SOON)
async def _next(self) -> tuple[_Key, int]:
"""The first key in the most urgent lane holding one, and that lane.
A key moved up a lane leaves its old entry behind, which is passed over
here because the key is no longer pending in that lane.
"""
while True:
for lane, queue in enumerate(self._lanes):
while queue:
key = queue.popleft()
if self._pending.get(key) == lane:
del self._pending[key]
return key, lane
self._wake.clear()
await self._wake.wait()
# ββ The bridge's own tasks ββββββββββββββββββββββββββββββββββββββββββββββββ
async def _run(self) -> None:
while True:
key, lane = await self._next()
try:
await self._handle(key)
except asyncio.CancelledError:
raise
except RichContentThrottled as throttled:
if lane == _CLOCK:
continue
logger.warning(
"%s asked bridge %s to wait %.1fs; retrying %s then.",
self._adapter.platform_name,
self._bridge_id,
throttled.retry_after,
key,
)
self._enqueue_later(key, throttled.retry_after, _SOON)
except _ThreadNotMappedYet:
self._enqueue_later(key, _THREAD_WAIT_SECONDS, lane)
except Exception:
# The delivery loop: one key failing must not stop the rest.
delay = self._retries.next(key)
logger.exception(
"Could not publish %s on bridge %s; trying again in %.0fs.",
key,
self._bridge_id,
delay,
)
self._enqueue_later(key, delay, _SOON)
async def _tick_forever(self) -> None:
while True:
await asyncio.sleep(_TICK_SECONDS)
self._tick(datetime.now(UTC))
def _tick(self, now: datetime) -> None:
"""Queue what moved without a change of its own: an agent going offline
or coming back, and a running turn's clock once it shows another minute.
No clock while the platform is holding edits back. Each redraw would
only be refused, and the first tick after the wait draws whichever
clocks are due by then.
"""
clock = (
self._adapter.redraws_for_elapsed_time
and self._adapter.rich_updates_held_for() <= 0
)
for keys in (self._live_turns, self._open_cards):
for key, agent_id in list(keys.items()):
online = self._agent_online(agent_id)
if self._online_seen.get(agent_id) != online:
self._enqueue(key, _SOON)
elif (
clock
and online
and keys is self._live_turns
and self._clock_due(key, now)
):
self._enqueue(key, _CLOCK)
def _clock_due(self, key: _Key, now: datetime) -> bool:
drawn = self._drawn.get(key)
return drawn is None or drawn.clock_due is None or drawn.clock_due <= now
async def _handle(self, key: _Key) -> None:
kind = key[0]
if kind == "resync":
await self._resync()
elif kind == "approval":
await self._publish_approval(key, key[1], key[2], key[3])
elif kind == "turn":
await self._publish_turn(key, key[1], key[2], key[3])
else:
raise ValueError(f"Unknown publication key {key!r}")
async def _resync(self) -> None:
since = datetime.now(UTC) - _RESYNC_WINDOW
async with tenant_session(self._sessions, self._tenant_id) as db:
posted = exists().where(
ApprovalRequestPost.bridge_id == self._bridge_id,
ApprovalRequestPost.agent_id == ApprovalRequest.agent_id,
ApprovalRequestPost.session_id == ApprovalRequest.session_id,
ApprovalRequestPost.request_id == ApprovalRequest.request_id,
)
requests = (
await db.execute(
select(
ApprovalRequest.agent_id,
ApprovalRequest.session_id,
ApprovalRequest.request_id,
)
.join(Room, Room.id == ApprovalRequest.room_id)
.where(
Room.bridge_id == self._bridge_id,
or_(
ApprovalRequest.state == "open",
and_(ApprovalRequest.updated_at >= since, posted),
),
)
)
).all()
unended = and_(
AgentSessionActivityItem.item_id == TURN_ITEM_ID,
AgentSessionActivityItem.status.in_(("queued", "running")),
)
turns = (
await db.execute(
select(
AgentSessionActivityItem.agent_id,
AgentSessionActivityItem.session_id,
AgentSessionActivityItem.turn_id,
func.max(AgentSessionActivityItem.updated_at),
func.bool_or(unended),
TurnStatusPost.updated_at,
)
.join(Room, Room.id == AgentSessionActivityItem.room_id)
.outerjoin(
TurnStatusPost,
and_(
TurnStatusPost.bridge_id == self._bridge_id,
TurnStatusPost.agent_id
== AgentSessionActivityItem.agent_id,
TurnStatusPost.session_id
== AgentSessionActivityItem.session_id,
TurnStatusPost.turn_id == AgentSessionActivityItem.turn_id,
),
)
.where(
Room.bridge_id == self._bridge_id,
or_(AgentSessionActivityItem.updated_at >= since, unended),
)
.group_by(
AgentSessionActivityItem.agent_id,
AgentSessionActivityItem.session_id,
AgentSessionActivityItem.turn_id,
TurnStatusPost.updated_at,
)
)
).all()
marked = await self._turn_posts.marked(db, self._bridge_id)
for agent_id, session_id, request_id in requests:
self._enqueue(("approval", agent_id, session_id, request_id), _SOON)
for agent_id, session_id, turn_id, changed, running, drawn_at in turns:
# An ended turn whose message was last drawn after its last change
# already shows how it ended.
if running or drawn_at is None or drawn_at < changed:
self._enqueue(("turn", agent_id, session_id, turn_id), _SOON)
for post in marked:
self._enqueue(("turn", post.agent_id, post.session_id, post.turn_id), _SOON)
# ββ Where a room's publications go ββββββββββββββββββββββββββββββββββββββββ
async def _target(
self,
db: AsyncSession,
key: _Key,
agent_id: str,
room_id: str,
thread_id: str | None,
) -> _Target | None:
"""The channel and thread for a room on this bridge, or None if it is not on it."""
found = await self._rooms.get_with_membership(db, room_id, agent_id)
if found is None or found[0].bridge_id != self._bridge_id:
return None
room, member = found
if not room.external_channel_id:
logger.warning(
"Room %s is on bridge %s but has no channel; nothing is published there.",
room_id,
self._bridge_id,
)
return None
agent = await db.get(Agent, agent_id)
if agent is None:
return None
if not member:
logger.warning(
"Not publishing for agent %s in room %s: it is no longer a member.",
agent.name,
room_id,
)
return None
return _Target(
channel_id=room.external_channel_id,
thread_ref=await self._thread_ref(
db, key, room.external_channel_id, thread_id
),
agent=agent,
)
async def _platform_ref(
self, db: AsyncSession, channel_id: str, switch_id: str | None
) -> str | None:
"""The platform's post for a Switch message in this channel, if it has one."""
if switch_id is None:
return None
external_post_id: str | None = await db.scalar(
select(BridgeMessageMap.external_post_id).where(
BridgeMessageMap.bridge_id == self._bridge_id,
BridgeMessageMap.external_channel_id == channel_id,
BridgeMessageMap.transport_event_id == switch_id,
)
)
return external_post_id
async def _thread_ref(
self, db: AsyncSession, key: _Key, channel_id: str, thread_id: str | None
) -> str | None:
if thread_id is None:
return None
external_post_id = await self._platform_ref(db, channel_id, thread_id)
if external_post_id is not None:
self._thread_waits.pop(key, None)
return external_post_id
waited = self._thread_waits.get(key, 0)
if waited < _THREAD_WAIT_ATTEMPTS:
self._thread_waits[key] = waited + 1
raise _ThreadNotMappedYet(thread_id)
self._thread_waits.pop(key, None)
logger.warning(
"Switch message %s has no post in channel %s on bridge %s; "
"publishing %s at the channel root instead of in its thread.",
thread_id,
channel_id,
self._bridge_id,
key,
)
return None
async def _recipient(
self,
db: AsyncSession,
room_id: str,
agent: Agent,
turn_row: AgentSessionActivityItem | None,
thread_ref: str | None,
) -> str | None:
"""Who a post asking someone to act names: whoever asked, else the owner."""
return await notification_recipient(
db,
bridge_id=self._bridge_id,
room_id=room_id,
surface=self._bridge_type,
actor_id=await self._asker(db, turn_row),
agent=agent,
thread_id=thread_ref,
)
async def _card_recipient(
self,
db: AsyncSession,
room_id: str,
agent: Agent,
turn_row: AgentSessionActivityItem | None,
thread_ref: str | None,
) -> str | None:
"""Who a new request card names: in a thread, somebody who may answer it."""
if thread_ref is None:
return await self._recipient(db, room_id, agent, turn_row, None)
async def may_answer(sender: str) -> bool:
decision = await self._addressing.permitted(
db, agent=agent, room_id=room_id, sender=sender
)
return decision.allowed
return await request_card_recipient(
db,
bridge_id=self._bridge_id,
room_id=room_id,
actor_id=await self._asker(db, turn_row),
agent=agent,
may_answer=may_answer,
)
async def _asker(
self, db: AsyncSession, turn_row: AgentSessionActivityItem | None
) -> str | None:
"""The room identity of whoever sent the message a turn answers, if known."""
if turn_row is None or turn_row.message_id is None:
return None
sender: str | None = await db.scalar(
select(Message.sender_id).where(
Message.transport_event_id == turn_row.message_id
)
)
return sender
async def _turn_row(
self, db: AsyncSession, agent_id: str, session_id: str, turn_id: str
) -> AgentSessionActivityItem | None:
return await db.get(
AgentSessionActivityItem,
(self._tenant_id, agent_id, session_id, turn_id, TURN_ITEM_ID),
)
# ββ Request cards βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
async def _publish_approval(
self, key: _Key, agent_id: str, session_id: str, request_id: str
) -> None:
async with tenant_session(self._sessions, self._tenant_id) as db:
row = await self._approvals.get(
db, agent_id, session_id, request_id, for_update=False
)
if row is None or row.room_id is None:
self._open_cards.pop(key, None)
return
post = await self._card_posts.get(
db, self._bridge_id, agent_id, session_id, request_id, for_update=False
)
if (post is None and row.state != "open") or (
post is not None and post.removed_at is not None
):
self._open_cards.pop(key, None)
return
target = await self._target(db, key, agent_id, row.room_id, row.thread_id)
if target is None:
self._open_cards.pop(key, None)
return
decided_by, responder = await answerer_of(db, row, self._bridge_id)
turn_row = await self._turn_row(db, agent_id, session_id, row.turn_id)
online = self._agent_online(agent_id)
asking = post is None and row.state == "open"
recipient = (
await self._card_recipient(
db, row.room_id, target.agent, turn_row, target.thread_ref
)
if asking
else None
)
db.expunge_all()
self._online_seen[agent_id] = online
if row.state == "open":
self._open_cards[key] = agent_id
else:
self._open_cards.pop(key, None)
unavailable = _HOST_OFFLINE if not online and row.state == "open" else None
if post is None:
await self._post_card(
row,
target,
asked_at_root=_asked_at_root(turn_row),
broadcast=_known_root_turn(turn_row),
unavailable_reason=unavailable,
notify_external_id=recipient,
notify_unreachable=recipient is None
and self._adapter.notifies_only_by_mention,
)
self._retries.clear(key)
return
if post.external_post_id is None:
recovered = await self._unconfirmed(key, post)
if recovered is None:
return
post = recovered
if getattr(self._adapter, "removes_answered_cards", False) and decided(
approval_request(row, decided_by)
):
if await self._remove_card(key, post):
return
await self._refresh_card(
row,
post,
target,
decided_by=decided_by,
responder=responder,
unavailable_reason=unavailable,
)
self._retries.clear(key)
async def _post_card(
self,
row: ApprovalRequest,
target: _Target,
*,
asked_at_root: bool,
broadcast: bool,
unavailable_reason: str | None,
notify_external_id: str | None,
notify_unreachable: bool,
) -> None:
post = await self._reserve(row, target)
if post is None:
return
card = approval_card(
row,
post,
decided_by=None,
responder_external_id=None,
unavailable_reason=unavailable_reason,
notify_external_id=notify_external_id,
notify_unreachable=notify_unreachable,
)
card = replace(card, asked_at_root=broadcast)
thread_ref = target.thread_ref
try:
try:
ref = await self._adapter.post_rich(
target.channel_id, target.agent_name, card, thread_ref
)
except ThreadUnavailable as missing:
if not asked_at_root:
# Asked in a thread the platform no longer has: the channel
# root is people who were never in that conversation.
raise
logger.warning(
"No thread for request %s in channel %s (%s); posting its "
"card at the channel root, where it was asked.",
row.request_id,
target.channel_id,
missing,
)
thread_ref = None
ref = await self._adapter.post_rich(
target.channel_id, target.agent_name, card, None
)
except RichContentFailed:
await self._release(post)
raise
async with tenant_session(self._sessions, self._tenant_id) as db, db.begin():
stored = await self._card_posts.get(
db,
self._bridge_id,
post.agent_id,
post.session_id,
post.request_id,
for_update=True,
)
if stored is None:
logger.error(
"Posted card %s for request %s in channel %s, but its "
"reservation is gone, so the card answers nothing.",
post.handle,
post.request_id,
target.channel_id,
)
return
stored.external_post_id = ref
stored.thread_ref = thread_ref
logger.info(
"Posted card %s for request %s of session %s in channel %s",
post.handle,
row.request_id,
row.session_id,
target.channel_id,
)
async def _refresh_card(
self,
row: ApprovalRequest,
post: ApprovalRequestPost,
target: _Target,
*,
decided_by: DecidedBy | None,
responder: str | None,
unavailable_reason: str | None,
) -> None:
"""Redraw a card; a redraw that fails says so under the card, once per state.
A stale card goes on offering buttons for a request that has settled,
and a reader cannot tell that pressing one will do nothing.
"""
assert post.external_post_id is not None
card = approval_card(
row,
post,
decided_by=decided_by,
responder_external_id=responder,
unavailable_reason=unavailable_reason,
notify_external_id=None,
notify_unreachable=False,
)
try:
await self._adapter.update_rich(
post.external_channel_id,
target.agent_name,
post.external_post_id,
card,
post.thread_ref,
)
except RichContentThrottled:
raise
except RichContentFailed as error:
logger.error(
"Could not update the card for request %s in channel %s: %s. "
"Posting the outcome as a reply instead.",
post.request_id,
post.external_channel_id,
error,
)
state = (row.state, unavailable_reason)
if self._card_edit_failures.get(post.token) != state:
await self._adapter.admin_message(
post.external_channel_id,
f"The card for request {post.handle} above could not be "
"updated, so it may still be offering buttons that no "
"longer work.",
self._adapter.notice_address(
post.external_post_id, post.thread_ref
),
drawn=error.text,
)
self._card_edit_failures[post.token] = state
raise
self._card_edit_failures.pop(post.token, None)
async def _remove_card(self, key: _Key, post: ApprovalRequestPost) -> bool:
"""Take an answered card off the platform. True once it is gone.
Nothing is written until the platform says the card is gone; a
deletion whose acknowledgement was lost is settled by asking again,
which the platform answers as already gone. A refusal leaves the card
settled and readable, and is tried again later.
"""
assert post.external_post_id is not None
try:
await self._adapter.remove_publication(
post.external_channel_id, post.external_post_id
)
except RichContentThrottled:
raise
except RemovalFailed as refusal:
delay = self._retries.next(key)
logger.warning(
"Card %s for request %s was answered but %s would not take it "
"back: %s. It stays in channel %s showing the decision; trying "
"again in %.0fs.",
post.handle,
post.request_id,
self._adapter.platform_name,
refusal,
post.external_channel_id,
delay,
)
self._enqueue_later(key, delay, _SOON)
return False
async with tenant_session(self._sessions, self._tenant_id) as db, db.begin():
stored = await self._card_posts.get(
db,
self._bridge_id,
post.agent_id,
post.session_id,
post.request_id,
for_update=True,
)
if stored is not None and stored.removed_at is None:
stored.removed_at = datetime.now(UTC)
self._retries.clear(key)
return True
async def _reserve(
self, row: ApprovalRequest, target: _Target
) -> ApprovalRequestPost | None:
"""Hold a handle nobody else in the channel has. None if another poster got there first."""
token = secrets.token_urlsafe(16)
async with tenant_session(self._sessions, self._tenant_id) as db:
start = await self._card_posts.count_in_channel(
db, self._bridge_id, target.channel_id
)
for attempt in range(_MINT_ATTEMPTS):
post = ApprovalRequestPost(
tenant_id=self._tenant_id,
bridge_id=self._bridge_id,
agent_id=row.agent_id,
session_id=row.session_id,
request_id=row.request_id,
token=token,
handle=f"{HANDLE_PREFIX}{start + 1 + attempt}",
external_channel_id=target.channel_id,
external_post_id=None,
thread_ref=target.thread_ref,
)
try:
async with db.begin_nested():
await self._card_posts.create(db, post)
except IntegrityError as error:
if _HANDLE_CONSTRAINT in str(error.orig):
continue
existing = await self._card_posts.get(
db,
self._bridge_id,
row.agent_id,
row.session_id,
row.request_id,
for_update=False,
)
if existing is None:
raise
return None
await db.commit()
return post
raise RuntimeError(
f"No free handle for request {row.request_id} in channel "
f"{target.channel_id} after {_MINT_ATTEMPTS} tries; it has no card, "
"because a card nobody can name cannot be answered by typing."
)
async def _release(self, post: ApprovalRequestPost) -> None:
async with tenant_session(self._sessions, self._tenant_id) as db, db.begin():
stored = await self._card_posts.get(
db,
self._bridge_id,
post.agent_id,
post.session_id,
post.request_id,
for_update=True,
)
if stored is not None and stored.external_post_id is None:
await db.delete(stored)
async def _unconfirmed(
self, key: _Key, post: ApprovalRequestPost
) -> ApprovalRequestPost | None:
"""A card whose post was never confirmed: find it, or say so; never repost."""
if post.unconfirmed_notice_at is not None:
return None
if not self._adapter.recovers_uncertain_posts:
if self._adapter.discloses_unconfirmed_posts:
await self._disclose_unconfirmed(post)
elif post.token not in self._noted_unconfirmed:
self._noted_unconfirmed.add(post.token)
logger.error(
"Delivery of card %s in channel %s was never confirmed, and "
"%s can neither search for it nor say so in the channel. The "
"reservation is held and request %s can still be answered in "
"Console.",
post.handle,
post.external_channel_id,
self._adapter.platform_name,
post.request_id,
)
return None
ref = await self._adapter.find_request_card(
post.external_channel_id,
post.thread_ref,
post.token,
post.created_at,
post.handle,
)
if ref is None:
delay = self._retries.next(key)
logger.warning(
"Card %s for request %s in channel %s was never confirmed and is "
"not on %s yet. It is not posted again, to avoid asking twice; "
"looking again in %.0fs.",
post.handle,
post.request_id,
post.external_channel_id,
self._adapter.platform_name,
delay,
)
self._enqueue_later(key, delay, _SOON)
return None
async with tenant_session(self._sessions, self._tenant_id) as db, db.begin():
stored = await self._card_posts.get(
db,
self._bridge_id,
post.agent_id,
post.session_id,
post.request_id,
for_update=True,
)
if stored is None:
return None
stored.external_post_id = ref
post.external_post_id = ref
return post
async def _disclose_unconfirmed(self, post: ApprovalRequestPost) -> None:
"""Say once in the channel that this card cannot be answered there.
The row is stamped before the message is sent: a second notice would
say nothing the first did not, so losing the notice to a crash
mid-send is the cheaper mistake.
"""
async with tenant_session(self._sessions, self._tenant_id) as db, db.begin():
stored = await self._card_posts.get(
db,
self._bridge_id,
post.agent_id,
post.session_id,
post.request_id,
for_update=True,
)
if stored is None or stored.unconfirmed_notice_at is not None:
return
stored.unconfirmed_notice_at = datetime.now(UTC)
sent = await self._adapter.admin_message(
post.external_channel_id,
f"Switch could not confirm that request **{post.handle}** reached "
"this chat. If a card for it is here, answering it here will not "
"work β answer it in Switch Console instead.",
post.thread_ref,
)
if sent is None:
logger.error(
"Could not tell channel %s that card %s was never confirmed. The "
"request can still be answered in Console, but nothing in the "
"channel says so, and this is not attempted again.",
post.external_channel_id,
post.handle,
)
# ββ Turns βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
async def _publish_turn(
self, key: _Key, agent_id: str, session_id: str, turn_id: str
) -> None:
async with tenant_session(self._sessions, self._tenant_id) as db:
view = turn_view(
await self._activity.turn(db, agent_id, session_id, turn_id)
)
if view is None or view.row.room_id is None:
self._forget_turn(key)
return
room_id = view.row.room_id
target = await self._target(db, key, agent_id, room_id, view.row.thread_id)
if target is None:
self._forget_turn(key)
return
asked_on = (
await self._platform_ref(db, target.channel_id, view.row.message_id)
or target.thread_ref
)
post = await self._turn_posts.get(
db, self._bridge_id, agent_id, session_id, turn_id, for_update=False
)
now: datetime = (await db.execute(select(func.now()))).scalar_one()
unended = [
row.turn_id
for row in await self._activity.turns_of_session(
db, agent_id, session_id
)
if row.status in ("queued", "running") and row.turn_id != turn_id
]
running = await self._running_turn(db, agent_id, session_id)
online = self._agent_online(agent_id)
error_summary = activity_error_summary(view.turn, online=online)
recipient = (
await self._recipient(
db, room_id, target.agent, view.row, target.thread_ref
)
if error_summary and self._adapter.separate_attention_slot
else None
)
db.expunge_all()
self._online_seen[agent_id] = online
interrupt_turn_id = None if view.ended else running
elapsed = view.elapsed_seconds(now)
drawn = self._remembered(key)
was_final = drawn.final
content = TurnActivity(
view.items,
view.turn,
elapsed,
interrupt_turn_id=interrupt_turn_id,
)
state = status_state(
view,
elapsed_seconds=elapsed,
interrupt_turn_id=interrupt_turn_id,
clock_redraws=self._adapter.redraws_for_elapsed_time,
closed_by_platform=drawn.platform_closes_at is not None
and drawn.platform_closes_at <= datetime.now(UTC),
)
if post is None:
unposted = self._unposted.get(key)
# Rebuilt until it holds a marker, so the marker goes where the
# asking message is known to be now: its post can be mapped
# between one attempt and the next.
if unposted is None or unposted.mark is None:
unposted = self._unposted[key] = self._unposted_turn(
view, target, asked_on
)
await self._marks(key, unposted, view, target, waiting_behind=bool(unended))
post = await self._begin_turn(
key, view, target, unposted, content, state, drawn
)
if post is not None or (view.ended and unposted.mark is None):
self._unposted.pop(key, None)
else:
await self._redraw_turn(key, post, view, target, content, state, drawn)
await self._marks(key, post, view, target, waiting_behind=bool(unended))
if post is not None:
await self._attention(post, view, target, error_summary, recipient, drawn)
if post is not None and not view.ended:
self._live_turns[key] = agent_id
drawn.clock_due = self._redraw_due(drawn, elapsed)
else:
self._live_turns.pop(key, None)
if post is not None and drawn.final and not was_final:
await self._stamp_drawn(post)
if drawn.status != view.turn.status:
drawn.status = view.turn.status
# The other waiting turns' stop controls name this session's
# running turn, which may just have changed.
for other in unended:
self._enqueue(("turn", agent_id, session_id, other), _SOON)
def _redraw_due(self, drawn: _TurnDrawn, elapsed: float | None) -> datetime:
"""When a running turn is next due a redraw with no change of its own."""
now = datetime.now(UTC)
due = now + timedelta(seconds=_until_the_clock_moves(elapsed))
closes_at = drawn.platform_closes_at
if closes_at is not None and now < closes_at + _AFTER_PLATFORM_CLOSE < due:
due = closes_at + _AFTER_PLATFORM_CLOSE
return due
def _forget_turn(self, key: _Key) -> None:
"""Stop watching a turn that is gone, or no longer published here."""
self._live_turns.pop(key, None)
self._drop_unposted(key)
def _drop_unposted(self, key: _Key) -> None:
"""Forget a turn's unposted row, saying so if it leaves a marker behind.
Nothing is asked of the platform: a turn that stops being published
here keeps its marker whether or not its message was posted.
"""
unposted = self._unposted.pop(key, None)
if unposted is not None and unposted.mark is not None:
logger.warning(
"No longer publishing turn %s of session %s, whose message was "
"never posted; the %s marker on %s in channel %s stays there.",
unposted.turn_id,
unposted.session_id,
unposted.mark,
unposted.reaction_message_ref,
unposted.external_channel_id,
)
async def _stamp_drawn(self, post: TurnStatusPost) -> None:
"""Record that the turn's message shows how it ended, for the next resync."""
async with tenant_session(self._sessions, self._tenant_id) as db, db.begin():
stored = await self._turn_posts.get(
db,
self._bridge_id,
post.agent_id,
post.session_id,
post.turn_id,
for_update=True,
)
if stored is not None:
stored.updated_at = func.now()
def _remembered(self, key: _Key) -> _TurnDrawn:
drawn = self._drawn.get(key)
if drawn is None:
drawn = self._drawn[key] = _TurnDrawn()
self._drawn.move_to_end(key)
while len(self._drawn) > _MAX_REMEMBERED_TURNS:
self._drawn.popitem(last=False)
return drawn
async def _running_turn(
self, db: AsyncSession, agent_id: str, session_id: str
) -> str | None:
"""The turn a stop control would end: the session's running one, if any."""
running = [
row.turn_id
for row in await self._activity.turns_of_session(db, agent_id, session_id)
if row.status == "running"
]
return running[-1] if running else None
def _unposted_turn(
self, view: TurnView, target: _Target, asked_on: str | None
) -> TurnStatusPost:
"""The turn's row before its message exists, to carry its marker until then."""
return TurnStatusPost(
tenant_id=self._tenant_id,
bridge_id=self._bridge_id,
agent_id=view.row.agent_id,
session_id=view.row.session_id,
turn_id=view.turn.turn_id,
external_channel_id=target.channel_id,
thread_ref=target.thread_ref,
reaction_message_ref=asked_on,
mark=None,
attention_post_id=None,
)
async def _begin_turn(
self,
key: _Key,
view: TurnView,
target: _Target,
post: TurnStatusPost,
content: TurnActivity,
state: str,
drawn: _TurnDrawn,
) -> TurnStatusPost | None:
"""Post the turn in its thread, or at the channel root with none to thread under.
`post` is the turn's row as it stood before the message, marker and
all, and is stored once the platform has the message. One the platform
made but could not draw into is kept and drawn into later, rather than
posted a second time: after the wait, where it asked for one.
Once per turn, which is why the "agent has started" nudge belongs here.
A refusal is logged; the next change to the turn tries again, and an
ended turn is tried again after a wait.
"""
if not view.ended:
await self._adapter.notify_working(
target.channel_id,
target.agent_name,
# Asked at the channel root, the turn threads under what was
# said, and whoever is waiting is watching the root.
None
if post.reaction_message_ref == target.thread_ref
else target.thread_ref,
)
drew = True
try:
ref = await self._adapter.post_rich(
target.channel_id, target.agent_name, content, target.thread_ref
)
except RichContentFailedAfterPost as failed:
ref = failed.ref
drew = False
if isinstance(failed, RichContentThrottled):
logger.warning(
"%s made the message for turn %s in channel %s but asked for "
"a %.1fs wait before drawing the turn into it; drawing it then.",
self._adapter.platform_name,
view.turn.turn_id,
target.channel_id,
failed.retry_after,
)
self._enqueue_later(key, failed.retry_after, _SOON)
else:
logger.error(
"%s made the message for turn %s in channel %s but could not "
"draw the turn into it: %s. %s",
self._adapter.platform_name,
view.turn.turn_id,
target.channel_id,
failed,
"The turn has ended; trying again after a wait."
if view.ended
else "The next change to the turn draws into the same message.",
)
if view.ended:
self._retry_later(key)
except RichContentThrottled:
raise
except RichContentFailed as error:
logger.error(
"Could not post the activity for turn %s of session %s in "
"channel %s: %s. The channel shows what the agent asked without "
"what it did.",
view.turn.turn_id,
view.row.session_id,
target.channel_id,
error,
)
if view.ended:
self._retry_later(key)
return None
closes_in = self._adapter.activity_closes_in(ref)
drawn.platform_closes_at = (
None
if closes_in is None
else datetime.now(UTC) + timedelta(seconds=closes_in)
)
post.external_post_id = ref
async with tenant_session(self._sessions, self._tenant_id) as db, db.begin():
await self._turn_posts.create(db, post)
db.expunge(post)
if drew:
self._retries.clear(key)
drawn.status_state = state
drawn.final = view.ended
return post
async def _redraw_turn(
self,
key: _Key,
post: TurnStatusPost,
view: TurnView,
target: _Target,
content: TurnActivity,
state: str,
drawn: _TurnDrawn,
) -> None:
"""Rewrite the turn's message as the turn now stands, unless nothing shown moved."""
if drawn.wedged:
return
if drawn.status_state == state and (not view.ended or drawn.final):
return
try:
await self._adapter.update_rich(
post.external_channel_id,
target.agent_name,
post.external_post_id,
content,
post.thread_ref,
)
except RichContentThrottled:
raise
except RichContentWedged as wedged:
logger.error("%s", wedged)
drawn.wedged = True
await self._say_wedged(post, view, target)
return
except RichContentFailed as error:
logger.error(
"Could not update the activity for turn %s of session %s in "
"channel %s: %s. %s",
view.turn.turn_id,
view.row.session_id,
post.external_channel_id,
error,
"The turn has ended; trying again after a wait."
if view.ended
else "The next change to the turn will try the same message.",
)
if view.ended:
self._retry_later(key)
return
drawn.status_state = state
drawn.final = view.ended
self._retries.clear(key)
async def _say_wedged(
self, post: TurnStatusPost, view: TurnView, target: _Target
) -> None:
"""Tell the channel the message above has stopped for good, while anyone is looking."""
age = datetime.now(UTC) - view.row.created_at
if age > _WEDGE_NOTICE_MAX_AGE:
logger.warning(
"Not saying that the activity message %s is frozen: its turn "
"started %.0f minutes ago, so a reply under it now would reach "
"nobody still looking at it.",
post.external_post_id,
age.total_seconds() / 60,
)
return
try:
posted = await self._adapter.send_message(
post.external_channel_id,
target.agent_name,
_WEDGE_NOTICE,
post.thread_ref,
)
except Exception:
logger.exception(
"Could not say that the activity message %s for turn %s is "
"frozen. The message stays as it is, unexplained.",
post.external_post_id,
view.turn.turn_id,
)
return
if posted is None:
logger.error(
"The platform would not take the message saying that the "
"activity message %s for turn %s is frozen.",
post.external_post_id,
view.turn.turn_id,
)
# ββ The marker on the asking message ββββββββββββββββββββββββββββββββββββββ
async def _marks(
self,
key: _Key,
post: TurnStatusPost,
view: TurnView,
target: _Target,
*,
waiting_behind: bool,
) -> None:
"""Put the one marker the turn's state earns on the asking message, and
take it off when the turn ends.
The marker is recorded before the platform is asked, so a request that
fails without an answer still counts as a marker that may be there.
"""
if (
not self._adapter.supports_activity_reactions
or post.reaction_message_ref is None
):
return
if view.ended:
if post.mark is not None and not await self._release_mark(
post, target.agent_name
):
self._retry_later(key)
return
# A turn is reported queued for a moment before it starts even when
# nothing is ahead of it; the queued mark is only worth showing when
# another turn of the session really is in the way.
wanted: Mark = (
"queued"
if self._adapter.supports_queue_reaction
and view.turn.status == "queued"
and waiting_behind
else "working"
)
if post.mark == wanted and key not in self._unsure_marks:
return
if post.mark is not None and post.mark != wanted:
if not await self._release_mark(post, target.agent_name):
return
await self._record_mark(post, wanted)
try:
await self._adapter.mark_activity(
post.external_channel_id,
post.reaction_message_ref,
agent_name=target.agent_name,
mark=wanted,
on=True,
force=True,
)
except ActivityMarkRefused as refusal:
logger.warning("%s The turn goes on without the mark.", refusal)
self._unsure_marks.discard(key)
await self._record_mark(post, None)
except Exception:
logger.warning(
"Could not add the %s reaction on %s in %s; trying again with "
"the turn's next change.",
wanted,
post.reaction_message_ref,
post.external_channel_id,
exc_info=True,
)
self._unsure_marks.add(key)
else:
self._unsure_marks.discard(key)
async def _release_mark(self, post: TurnStatusPost, agent_name: str) -> bool:
"""Take this turn's marker off, unless another turn still holds the same one.
Two turns can hang off one asking message; the last to let go removes
it. Where every agent reacts as one bot there is a single marker
between them, and where each reacts as its own there is one apiece.
False when the platform could not be asked, so it is tried again.
"""
mark = post.mark
assert mark is not None and post.reaction_message_ref is not None
async with tenant_session(self._sessions, self._tenant_id) as db:
holders = await self._turn_posts.other_holders(
db,
post,
mark,
same_agent=self._adapter.activity_reactions_per_agent,
)
holders += self._unposted_holders(post, mark)
if not holders:
try:
await self._adapter.mark_activity(
post.external_channel_id,
post.reaction_message_ref,
agent_name=agent_name,
mark=cast(Mark, mark),
on=False,
force=True,
)
except ActivityMarkRefused as refusal:
logger.error("%s The %s marker may stay on the message.", refusal, mark)
except Exception:
logger.warning(
"Could not remove the %s reaction on %s in %s.",
mark,
post.reaction_message_ref,
post.external_channel_id,
exc_info=True,
)
return False
await self._record_mark(post, None)
return True
def _unposted_holders(self, post: TurnStatusPost, mark: str) -> int:
"""Other turns holding `mark` on the same asking message whose own
message is not posted yet. Their rows are not stored, so the database
cannot count them."""
per_agent = self._adapter.activity_reactions_per_agent
return sum(
1
for other in self._unposted.values()
if other is not post
and other.mark == mark
and other.external_channel_id == post.external_channel_id
and other.reaction_message_ref == post.reaction_message_ref
and (not per_agent or other.agent_id == post.agent_id)
)
async def _record_mark(self, post: TurnStatusPost, mark: Mark | None) -> None:
async with tenant_session(self._sessions, self._tenant_id) as db, db.begin():
stored = await self._turn_posts.get(
db,
self._bridge_id,
post.agent_id,
post.session_id,
post.turn_id,
for_update=True,
)
if stored is not None:
stored.mark = mark
post.mark = mark
# ββ The "turn is stuck" message βββββββββββββββββββββββββββββββββββββββββββ
async def _attention(
self,
post: TurnStatusPost,
view: TurnView,
target: _Target,
error_summary: str | None,
recipient: str | None,
drawn: _TurnDrawn,
) -> None:
"""One message per turn saying somebody has to act, cleared once nobody does.
Posted, not edited in, because a post notifies and an edit does not.
"""
if not self._adapter.separate_attention_slot:
return
if error_summary is None and post.attention_post_id is None:
return
state = error_summary or view.turn.status
if post.attention_post_id is not None and drawn.attention_state == state:
return
content = TurnActivity(
[],
view.turn,
status_only=True,
notify_unreachable=bool(error_summary)
and recipient is None
and self._adapter.notifies_only_by_mention,
error_summary=error_summary,
)
try:
if post.attention_post_id is None:
ref = await self._adapter.post_rich(
post.external_channel_id,
target.agent_name,
replace(content, notify_external_id=recipient),
post.thread_ref,
)
async with (
tenant_session(self._sessions, self._tenant_id) as db,
db.begin(),
):
stored = await self._turn_posts.get(
db,
self._bridge_id,
post.agent_id,
post.session_id,
post.turn_id,
for_update=True,
)
if stored is not None:
stored.attention_post_id = ref
post.attention_post_id = ref
else:
await self._adapter.update_rich(
post.external_channel_id,
target.agent_name,
post.attention_post_id,
content,
post.thread_ref,
)
except RichContentThrottled:
raise
except RichContentWedged as wedged:
logger.error("%s", wedged)
except RichContentFailed as error:
logger.error(
"Could not draw the attention message for turn %s in channel "
"%s: %s. The next change to the turn will try again.",
view.turn.turn_id,
post.external_channel_id,
error,
)
return
drawn.attention_state = state
# ββ Read back for a control pressed on a turn's message βββββββββββββββββββ
async def activity_shown_at(
self, channel_id: str, ref: str
) -> ActivitySnapshot | None:
"""The turn a message of ours is showing, for an adapter that offers it."""
async with tenant_session(self._sessions, self._tenant_id) as db:
found = await self._turn_at(db, channel_id, ref)
if found is None:
return None
view, _ = found
now: datetime = (await db.execute(select(func.now()))).scalar_one()
return ActivitySnapshot(
items=view.items,
turn=view.turn,
elapsed_seconds=view.elapsed_seconds(now),
read_at=now,
)
async def stop_target(self, channel_id: str, ref: str) -> StopTarget | None:
"""What a Stop control on the message at `ref` would stop, or None."""
async with tenant_session(self._sessions, self._tenant_id) as db:
found = await self._turn_at(db, channel_id, ref)
if found is None:
return None
view, running = found
assert view.row.room_id is not None
return StopTarget(
agent_id=view.row.agent_id,
session_id=view.row.session_id,
room_id=view.row.room_id,
thread_id=view.row.thread_id,
running_turn_id=running,
)
async def _turn_at(
self, db: AsyncSession, channel_id: str, ref: str
) -> tuple[TurnView, str | None] | None:
"""The turn behind a message, re-checked the way drawing it was checked."""
post = await self._turn_posts.at(db, self._bridge_id, channel_id, ref)
if post is None:
return None
view = turn_view(
await self._activity.turn(db, post.agent_id, post.session_id, post.turn_id)
)
if view is None or view.row.room_id is None:
return None
found = await self._rooms.get_with_membership(
db, view.row.room_id, post.agent_id
)
if (
found is None
or found[0].bridge_id != self._bridge_id
or found[0].external_channel_id != channel_id
or not found[1]
):
return None
return view, await self._running_turn(db, post.agent_id, post.session_id)
def _until_the_clock_moves(elapsed: float | None) -> float:
"""Seconds until a running turn's clock shows another minute.
A queued turn shows no clock, and is looked at again after the same while.
"""
if elapsed is None:
return RUNNING_CLOCK_SECONDS
return RUNNING_CLOCK_SECONDS - elapsed % RUNNING_CLOCK_SECONDS
def _known_root_turn(turn_row: AgentSessionActivityItem | None) -> bool:
"""Whether the turn is recorded and was asked at the channel root. Only
then is its card also shown in the channel: an unrecorded turn may have
been a thread conversation the channel was never part of."""
return (
turn_row is not None
and turn_row.message_id is not None
and turn_row.thread_id in (None, turn_row.message_id)
)
def _asked_at_root(turn_row: AgentSessionActivityItem | None) -> bool:
"""Whether the turn a request belongs to was asked at the channel root.
Only then may its card go to the root when its thread cannot be found. A
request whose turn is not recorded says nothing about where it was asked,
and is treated as the root, as it always was without that record.
"""
if turn_row is None or turn_row.message_id is None:
return True
return turn_row.thread_id in (None, turn_row.message_id)