borgee-plugin-sdk 0.1.2__py3-none-any.whl

borgee_plugin_sdk/_connection.py

@@ -0,0 +1,1680 @@
+"""Bounded BPP WebSocket connection engine."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hashlib
+import importlib.metadata
+import inspect
+import ipaddress
+import json
+import logging
+import random
+import time
+import uuid
+from collections import OrderedDict, deque
+from collections.abc import AsyncIterator, Awaitable, Callable, Coroutine
+from dataclasses import dataclass
+from typing import Any, Literal, TypeGuard
+from urllib.parse import urlsplit, urlunsplit
+
+from websockets.asyncio.client import ClientConnection
+from websockets.asyncio.client import connect as WebSocketConnect
+from websockets.exceptions import ConnectionClosed, SecurityError
+
+from .cursor import CursorStore
+from .errors import (
+    BorgeeError,
+    NotOnlineError,
+    PermissionDeniedError,
+    PreResumeError,
+    ProtocolCapacityError,
+    ProtocolError,
+    ResumeAckError,
+    StaleDeliveryError,
+)
+from .models import (
+    ConfigApplyContext,
+    ConfigApplyResult,
+    ConfigApplyStatus,
+    ConfigUpdate,
+    ConnectionState,
+    ConnectionStatus,
+    DeliveryEvent,
+    FaultReason,
+    InboundKind,
+    InboundMessageEvent,
+    InboundReaction,
+    Message,
+    ReplayMode,
+    ReplaySummaryEvent,
+    user_from_wire,
+)
+
+MAX_INCOMING_BYTES = 5 << 20
+MAX_INCOMING_FRAMES = 512
+MAX_OUTBOUND_BYTES = 32 << 10
+REGULAR_MAX_FRAMES = 64
+REGULAR_MAX_BYTES = 2 << 20
+RESERVED_MAX_FRAMES = 32
+RESERVED_MAX_BYTES = 1 << 20
+CONFIG_MAX_FRAMES = 32
+CONFIG_MAX_BYTES = 1 << 20
+REQUEST_MAX_FRAMES = 32
+REQUEST_MAX_BYTES = 1 << 20
+REQUEST_SINGLE_MAX_BYTES = 32 << 10
+ACTION_PENDING_MAX = 256
+PRE_RESUME_TIMEOUT = 8.0
+RESUME_ACK_TIMEOUT = 5.0
+REPLAY_ARRIVAL_TIMEOUT = 5.0
+SERVER_REQUEST_DEADLINE = 8.0
+SERVER_REQUEST_QUEUE_WAIT = 2.0
+SERVER_REQUEST_HANDLER_TIMEOUT = 5.0
+HANDLER_TASK_SLOT_LIMIT = 64
+
+_DETACHED_TASK_GUARDIAN: set[asyncio.Task[Any]] = set()
+
+
+ConfigHandler = Callable[[ConfigUpdate, ConfigApplyContext], Awaitable[ConfigApplyResult] | ConfigApplyResult]
+ConfigObserver = Callable[[ConfigUpdate], Awaitable[None] | None]
+ServerRequestHandler = Callable[[str, Any], Awaitable[Any] | Any]
+
+
+@dataclass(slots=True)
+class ConnectionOptions:
+    base_url: str
+    api_key: str
+    agent_id: str
+    plugin_id: str
+    cursor_store: CursorStore
+    allow_insecure_loopback: bool
+    replay_mode: ReplayMode
+    replay_latest_n: int
+    config_update_handler: ConfigHandler | None
+    config_update_observer: ConfigObserver | None
+    server_request_handler: ServerRequestHandler | None
+    logger: logging.Logger
+    action_timeout: float
+    config_apply_timeout: float
+    auto_reconnect: bool
+    reconnect_base: float
+    reconnect_max: float
+    heartbeat_interval: float
+    random_source: random.Random
+
+
+@dataclass(slots=True)
+class _QueuedFrame:
+    data: str
+    size: int
+    completion: asyncio.Future[None]
+    deadline: float | None
+    send_timeout: float
+
+
+class _NoRedirectConnect(WebSocketConnect):
+    def process_redirect(self, exc: Exception) -> Exception | str:
+        raise SecurityError("WebSocket redirects are disabled")
+
+
+def validate_websockets_runtime() -> None:
+    try:
+        version = importlib.metadata.version("websockets")
+    except importlib.metadata.PackageNotFoundError as exc:
+        raise PreResumeError("websockets 15.0.1 is required", "bpp.websocket_dependency_missing") from exc
+    if version != "15.0.1":
+        raise PreResumeError(
+            f"websockets 15.0.1 is required; found {version}",
+            "bpp.websocket_dependency_mismatch",
+        )
+    if not inspect.isclass(WebSocketConnect):
+        raise PreResumeError(
+            "websockets connect implementation is incompatible", "bpp.websocket_api_mismatch"
+        )
+    parameters = tuple(inspect.signature(WebSocketConnect.process_redirect).parameters)
+    if parameters != ("self", "exc"):
+        raise PreResumeError("websockets redirect hook is incompatible", "bpp.websocket_api_mismatch")
+
+
+def plugin_websocket_url(base_url: str, *, allow_insecure_loopback: bool = False) -> tuple[str, str]:
+    try:
+        parsed = urlsplit(base_url)
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError("base_url is not a valid HTTP origin") from exc
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("base_url must be an http or https origin")
+    if parsed.username is not None or parsed.password is not None:
+        raise ValueError("base_url must not contain user information")
+    if parsed.path not in {"", "/"} or parsed.query or parsed.fragment:
+        raise ValueError("base_url must be an origin without a path, query, or fragment")
+    if parsed.scheme == "http":
+        if not allow_insecure_loopback or not _is_loopback(parsed.hostname):
+            raise ValueError(
+                "insecure WebSocket transport is restricted to explicitly allowed loopback origins"
+            )
+    hostname = parsed.hostname.lower()
+    host = f"[{hostname}]" if ":" in hostname else hostname
+    netloc = host if port is None else f"{host}:{port}"
+    origin = urlunsplit((parsed.scheme, netloc, "", "", ""))
+    ws_scheme = "wss" if parsed.scheme == "https" else "ws"
+    return urlunsplit((ws_scheme, netloc, "/ws/plugin", "", "")), origin
+
+
+def _is_loopback(hostname: str) -> bool:
+    if hostname.lower() == "localhost":
+        return True
+    try:
+        addr = ipaddress.ip_address(hostname)
+        return addr.is_loopback or addr.is_private
+    except ValueError:
+        return False
+
+
+class _OutboundWriter:
+    def __init__(self, websocket: ClientConnection) -> None:
+        self._websocket = websocket
+        self._regular: deque[_QueuedFrame] = deque()
+        self._reserved: deque[_QueuedFrame] = deque()
+        self._regular_bytes = 0
+        self._reserved_bytes = 0
+        self._reserved_streak = 0
+        self._wakeup = asyncio.Event()
+        self._space = asyncio.Event()
+        self._space.set()
+        self._accepting = True
+        self._task = asyncio.create_task(self._run(), name="borgee-plugin-writer")
+
+    async def send(
+        self,
+        frame: dict[str, Any],
+        *,
+        lane: Literal["regular", "reserved"] = "regular",
+        deadline: float | None = None,
+        send_timeout: float = 0.1,
+    ) -> None:
+        item = self._encode(frame, deadline, send_timeout)
+        admission_deadline = min(time.monotonic() + 0.1, deadline or float("inf"))
+        while True:
+            if not self._accepting:
+                raise BorgeeError("connection writer is closed", "bpp.writer_closed")
+            if self._admit(item, lane):
+                break
+            remaining = admission_deadline - time.monotonic()
+            if remaining <= 0:
+                raise ProtocolCapacityError("outbound queue admission timed out")
+            self._space.clear()
+            try:
+                await asyncio.wait_for(self._space.wait(), remaining)
+            except TimeoutError as exc:
+                raise ProtocolCapacityError("outbound queue admission timed out") from exc
+        await item.completion
+
+    def send_nowait(
+        self,
+        frame: dict[str, Any],
+        *,
+        lane: Literal["regular", "reserved"] = "reserved",
+        deadline: float | None = None,
+        send_timeout: float = 0.1,
+    ) -> asyncio.Future[None]:
+        item = self._encode(frame, deadline, send_timeout)
+        if not self._accepting or not self._admit(item, lane):
+            raise ProtocolCapacityError("outbound queue capacity exceeded")
+        return item.completion
+
+    async def close(self, error: BaseException | None = None) -> None:
+        self._accepting = False
+        self._space.set()
+        failure = error or BorgeeError("connection writer closed", "bpp.writer_closed")
+        for queue in (self._regular, self._reserved):
+            while queue:
+                item = queue.popleft()
+                if not item.completion.done():
+                    item.completion.set_exception(failure)
+        self._regular_bytes = 0
+        self._reserved_bytes = 0
+        self._task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await self._task
+
+    def _encode(self, frame: dict[str, Any], deadline: float | None, send_timeout: float) -> _QueuedFrame:
+        data = json.dumps(frame, separators=(",", ":"), ensure_ascii=False)
+        size = len(data.encode("utf-8"))
+        if size > MAX_OUTBOUND_BYTES:
+            raise ProtocolCapacityError(f"outbound frame exceeds {MAX_OUTBOUND_BYTES} bytes")
+        return _QueuedFrame(data, size, asyncio.get_running_loop().create_future(), deadline, send_timeout)
+
+    def _admit(self, item: _QueuedFrame, lane: Literal["regular", "reserved"]) -> bool:
+        if lane == "regular":
+            if (
+                len(self._regular) >= REGULAR_MAX_FRAMES
+                or self._regular_bytes + item.size > REGULAR_MAX_BYTES
+            ):
+                return False
+            self._regular.append(item)
+            self._regular_bytes += item.size
+        else:
+            if (
+                len(self._reserved) >= RESERVED_MAX_FRAMES
+                or self._reserved_bytes + item.size > RESERVED_MAX_BYTES
+            ):
+                return False
+            self._reserved.append(item)
+            self._reserved_bytes += item.size
+        self._wakeup.set()
+        return True
+
+    def _take(self) -> _QueuedFrame | None:
+        if self._reserved and (not self._regular or self._reserved_streak < 8):
+            self._reserved_streak += 1
+            item = self._reserved.popleft()
+            self._reserved_bytes -= item.size
+        elif self._regular:
+            self._reserved_streak = 0
+            item = self._regular.popleft()
+            self._regular_bytes -= item.size
+        elif self._reserved:
+            self._reserved_streak += 1
+            item = self._reserved.popleft()
+            self._reserved_bytes -= item.size
+        else:
+            return None
+        self._space.set()
+        return item
+
+    async def _run(self) -> None:
+        while True:
+            item = self._take()
+            if item is None:
+                self._wakeup.clear()
+                await self._wakeup.wait()
+                continue
+            if item.deadline is not None and time.monotonic() >= item.deadline:
+                if not item.completion.done():
+                    item.completion.set_exception(TimeoutError("outbound frame deadline expired"))
+                continue
+            timeout = item.send_timeout
+            if item.deadline is not None:
+                timeout = min(timeout, max(0.0, item.deadline - time.monotonic()))
+            try:
+                async with asyncio.timeout(timeout):
+                    await self._websocket.send(item.data)
+            except BaseException as exc:
+                if not item.completion.done():
+                    item.completion.set_exception(exc)
+                if isinstance(exc, asyncio.CancelledError):
+                    raise
+            else:
+                if not item.completion.done():
+                    item.completion.set_result(None)
+
+
+@dataclass(slots=True)
+class _PendingAction:
+    operation: str
+    future: asyncio.Future[Any]
+
+
+@dataclass(slots=True)
+class _BufferedDelivery:
+    event: DeliveryEvent
+    cursor: int
+    size: int
+    generation: int
+    replay: bool
+
+
+class Delivery:
+    """One generation-bound inbound event awaiting an explicit disposition."""
+
+    def __init__(self, connection: BppConnection, buffered: _BufferedDelivery) -> None:
+        self.event = buffered.event
+        self.cursor = buffered.cursor
+        self._connection = connection
+        self._generation = buffered.generation
+        self._replay = buffered.replay
+        self._resolved: Literal["checkpoint", "fail"] | None = None
+
+    async def checkpoint(self) -> None:
+        if self._resolved == "checkpoint":
+            return
+        if self._resolved is not None:
+            raise BorgeeError("delivery was already failed", "bpp.delivery_resolved")
+        await self._connection._settle_delivery(self, checkpoint=True, error=None)
+        self._resolved = "checkpoint"
+
+    async def fail(self, error: BaseException | None = None) -> None:
+        if self._resolved == "fail":
+            return
+        if self._resolved is not None:
+            raise BorgeeError("delivery was already checkpointed", "bpp.delivery_resolved")
+        await self._connection._settle_delivery(self, checkpoint=False, error=error)
+        self._resolved = "fail"
+
+
+class _RecoverableDisconnect(Exception):
+    pass
+
+
+class _TerminalStop(Exception):
+    pass
+
+
+class BppConnection:
+    def __init__(self, options: ConnectionOptions) -> None:
+        if not options.api_key:
+            raise ValueError("api_key must not be empty")
+        if options.replay_latest_n < 1 or options.replay_latest_n > 500:
+            raise ValueError("replay_latest_n must be between 1 and 500")
+        self._options = options
+        self._websocket_url, self._origin = plugin_websocket_url(
+            options.base_url,
+            allow_insecure_loopback=options.allow_insecure_loopback,
+        )
+        self._agent_id = options.agent_id
+        self._state = ConnectionState(ConnectionStatus.CONNECTING)
+        self._state_queue: asyncio.Queue[ConnectionState] = asyncio.Queue(maxsize=1)
+        self._online_ready = asyncio.Event()
+        # A "stop" signal fired for EITHER a terminal fault OR an explicit client close, so an
+        # action waiting for ONLINE fails fast with the real reason instead of the full timeout.
+        self._terminal_event = asyncio.Event()
+        self._supervisor_task: asyncio.Task[None] | None = None
+        self._observer_task: asyncio.Task[None] | None = None
+        self._initial_ready: asyncio.Future[None] | None = None
+        self._connect_future: asyncio.Future[None] | None = None
+        self._close_task: asyncio.Task[None] | None = None
+        self._lifecycle_lock = asyncio.Lock()
+        self._generation_cleanup_lock = asyncio.Lock()
+        self._ever_ready = False
+        self._ever_online = False
+        self._closing = False
+        self._closed_permanently = False
+        self._terminal_set = False
+        self._terminal_error: BaseException | None = None
+
+        self._generation_counter = 0
+        self._active_generation: int | None = None
+        self._websocket: ClientConnection | None = None
+        self._writer: _OutboundWriter | None = None
+        self._generation_tasks: set[asyncio.Task[Any]] = set()
+        self._detached_tasks: set[asyncio.Task[Any]] = set()
+        self._handler_slot_tasks: set[asyncio.Task[Any]] = set()
+        self._handler_slots_available = HANDLER_TASK_SLOT_LIMIT
+        self._background_failure: BaseException | None = None
+        self._resume_ack: asyncio.Future[None] | None = None
+        self._resume_request: tuple[ReplayMode, int] | None = None
+        self._resume_count = 0
+        self._replay_received = 0
+        self._replay_checkpointed = 0
+        self._resume_high_water = 0
+        self._resume_ack_seen = False
+        self._replay_arrived = asyncio.Event()
+
+        self._pending_actions: dict[str, _PendingAction] = {}
+        self._deliveries: deque[_BufferedDelivery] = deque()
+        self._deferred_live: deque[_BufferedDelivery] = deque()
+        self._seen_delivery_cursors: set[int] = set()
+        self._delivery_bytes = 0
+        self._delivery_wakeup = asyncio.Event()
+        self._delivery_consumer = False
+        self._active_delivery: Delivery | None = None
+        self._last_checkpoint = 0
+        self._last_received = 0
+        self._cursor_key = ""
+        self._cursor_write_lock = asyncio.Lock()
+
+        self._config_queue: asyncio.Queue[tuple[dict[str, Any], int, int]] | None = None
+        self._config_queue_bytes = 0
+        self._config_acks: OrderedDict[str, dict[str, Any]] = OrderedDict()
+        self._request_queue: asyncio.Queue[tuple[dict[str, Any], int, float, int]] | None = None
+        self._request_queue_bytes = 0
+        self._observer_queue: deque[tuple[ConfigUpdate, int]] = deque()
+        self._observer_bytes = 0
+        self._observer_wakeup = asyncio.Event()
+
+    @property
+    def agent_id(self) -> str:
+        return self._agent_id
+
+    @property
+    def state(self) -> ConnectionState:
+        return self._state
+
+    def _is_stopping(self) -> bool:
+        # Keep lifecycle checks behind a method call. Their values may change at
+        # every await boundary even though a static analyzer sees one task.
+        return self._terminal_set or self._closing
+
+    async def connect(self) -> None:
+        async with self._lifecycle_lock:
+            if self._closed_permanently:
+                raise BorgeeError("client is permanently closed", "bpp.client_closed")
+            if self._terminal_error is not None:
+                raise self._terminal_error
+            future = self._connect_future
+            if future is None:
+                validate_websockets_runtime()
+                self._closing = False
+                future = asyncio.get_running_loop().create_future()
+                future.add_done_callback(self._consume_future_exception)
+                self._connect_future = future
+                self._initial_ready = future
+                self._observer_task = asyncio.create_task(
+                    self._run_config_observer(), name="borgee-config-observer"
+                )
+                self._supervisor_task = asyncio.create_task(
+                    self._supervise(), name="borgee-plugin-supervisor"
+                )
+        await asyncio.shield(future)
+
+    async def close(self) -> None:
+        async with self._lifecycle_lock:
+            task = self._close_task
+            if task is None:
+                self._closed_permanently = True
+                task = asyncio.create_task(self._close_impl(), name="borgee-plugin-close")
+                self._close_task = task
+        await asyncio.shield(task)
+
+    async def _close_impl(self) -> None:
+        self._closing = True
+        self._terminal_event.set()
+        error = BorgeeError("client closed", "bpp.client_closed")
+        future = self._connect_future
+        if future is not None and not future.done():
+            future.set_exception(error)
+        task = self._supervisor_task
+        if task is not None and task is not asyncio.current_task():
+            task.cancel()
+        await self._invalidate_generation(error)
+        if task is not None and task is not asyncio.current_task():
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        await self._cleanup_generation(error)
+        if self._observer_task is not None:
+            self._detach_task(self._observer_task)
+        self._set_state(ConnectionState(ConnectionStatus.CLOSED))
+        self._delivery_wakeup.set()
+
+    async def __aenter__(self) -> BppConnection:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.close()
+
+    async def deliveries(self) -> AsyncIterator[Delivery]:
+        if self._delivery_consumer:
+            raise RuntimeError("deliveries() supports one consumer")
+        self._delivery_consumer = True
+        try:
+            while True:
+                delivery = await self._next_delivery()
+                if delivery is None:
+                    return
+                yield delivery
+        finally:
+            self._delivery_consumer = False
+
+    async def state_changes(self) -> AsyncIterator[ConnectionState]:
+        while True:
+            state = await self._state_queue.get()
+            yield state
+            if state.status in {ConnectionStatus.ERROR, ConnectionStatus.CLOSED}:
+                return
+
+    async def perform(self, operation: str, payload: dict[str, Any]) -> Any:
+        return await self._perform(operation, payload, allow_pre_resume=False)
+
+    async def report_task_started(self, task_id: str, channel_id: str, subject: str) -> None:
+        self._require_online()
+        await self._send_regular(
+            {
+                "type": "task_started",
+                "task_id": task_id,
+                "agent_id": self._agent_id,
+                "channel_id": channel_id,
+                "subject": subject,
+                "started_at": int(time.time() * 1000),
+            }
+        )
+
+    async def report_task_finished(
+        self,
+        task_id: str,
+        channel_id: str,
+        outcome: str,
+        reason: str,
+    ) -> None:
+        self._require_online()
+        await self._send_regular(
+            {
+                "type": "task_finished",
+                "task_id": task_id,
+                "agent_id": self._agent_id,
+                "channel_id": channel_id,
+                "outcome": outcome,
+                "reason": reason,
+                "finished_at": int(time.time() * 1000),
+            }
+        )
+
+    def send_typing_nowait(self, channel_id: str) -> None:
+        """Fire-and-forget typing indicator frame."""
+        writer = self._writer
+        if writer is None or self._state.status is not ConnectionStatus.ONLINE:
+            return
+        try:
+            writer.send_nowait(
+                {"type": "typing", "channel_id": channel_id},
+                lane="regular",
+            )
+        except (ProtocolCapacityError, BorgeeError):
+            pass  # best-effort, never fail the caller
+
+    async def _supervise(self) -> None:
+        reconnect_attempt = 0
+        initial = True
+        try:
+            while not self._is_stopping():
+                try:
+                    if self._is_stopping():
+                        return
+                    await self._run_generation(initial=initial)
+                    raise _RecoverableDisconnect("connection ended")
+                except asyncio.CancelledError:
+                    raise
+                except _TerminalStop:
+                    return
+                except _RecoverableDisconnect as exc:
+                    if self._is_stopping():
+                        return
+                    if not self._ever_ready or not self._options.auto_reconnect:
+                        raise PreResumeError(str(exc), "bpp.connection_lost") from exc
+                    initial = False
+                    reconnect_attempt += 1
+                    self._set_state(ConnectionState(ConnectionStatus.RECONNECTING, attempt=reconnect_attempt))
+                    cap = min(
+                        self._options.reconnect_max,
+                        self._options.reconnect_base * (2 ** (reconnect_attempt - 1)),
+                    )
+                    delay = cap * (0.5 + self._options.random_source.random() * 0.5)
+                    await asyncio.sleep(delay)
+                    if self._is_stopping():
+                        return
+                initial = False
+        except asyncio.CancelledError:
+            raise
+        except BaseException as exc:
+            await self._terminal(exc)
+
+    async def _run_generation(self, *, initial: bool) -> None:
+        if self._is_stopping():
+            raise _TerminalStop
+        self._generation_counter += 1
+        generation = self._generation_counter
+        self._active_generation = generation
+        self._resume_ack_seen = False
+        self._background_failure = None
+        self._resume_count = 0
+        self._replay_received = 0
+        self._replay_checkpointed = 0
+        self._resume_high_water = 0
+        self._last_received = 0
+        self._replay_arrived.clear()
+        if initial:
+            self._set_state(ConnectionState(ConnectionStatus.CONNECTING))
+
+        receive_task: asyncio.Task[None] | None = None
+        opened = False
+        try:
+            async with asyncio.timeout(PRE_RESUME_TIMEOUT):
+                websocket = await _NoRedirectConnect(
+                    self._websocket_url,
+                    additional_headers={"Authorization": f"Bearer {self._options.api_key}"},
+                    open_timeout=PRE_RESUME_TIMEOUT,
+                    close_timeout=1,
+                    ping_interval=None,
+                    max_size=MAX_INCOMING_BYTES,
+                    max_queue=4,
+                    write_limit=MAX_OUTBOUND_BYTES,
+                )
+                if self._is_stopping():
+                    websocket.transport.abort()
+                    raise _TerminalStop
+                opened = True
+                self._websocket = websocket
+                self._writer = _OutboundWriter(websocket)
+                self._config_queue = asyncio.Queue(maxsize=CONFIG_MAX_FRAMES)
+                self._request_queue = asyncio.Queue(maxsize=REQUEST_MAX_FRAMES)
+                self._config_queue_bytes = 0
+                self._request_queue_bytes = 0
+                receive_task = self._spawn(
+                    self._receive_loop(websocket, generation), "borgee-plugin-receiver"
+                )
+                self._spawn(self._config_worker(generation), "borgee-config-worker")
+                for index in range(8):
+                    self._spawn(self._request_worker(generation), f"borgee-request-worker-{index}")
+
+                await self._send_regular(
+                    {
+                        "type": "connect",
+                        "plugin_id": self._options.plugin_id,
+                        "token": "",
+                        "version": "bpp-1",
+                        "capabilities": json.dumps(
+                            ["semantic_action", "inbound_message", "read_file"], separators=(",", ":")
+                        ),
+                    }
+                )
+                if not self._agent_id:
+                    identity = await self._perform("get_me", {}, allow_pre_resume=True)
+                    try:
+                        self._agent_id = user_from_wire(identity).id
+                    except (TypeError, ValueError) as exc:
+                        raise PreResumeError(
+                            "authenticated agent identity is invalid", "bpp.identity_invalid"
+                        ) from exc
+
+                digest = hashlib.sha256(self._origin.encode()).hexdigest()
+                self._cursor_key = f"{digest}:{self._agent_id}"
+                cursor = await self._read_cursor_detached_on_cancel()
+                if not isinstance(cursor, int) or isinstance(cursor, bool) or cursor < 0:
+                    raise PreResumeError(
+                        "cursor store returned an invalid cursor", "bpp.cursor_store_read_failed"
+                    )
+                self._last_checkpoint = cursor
+                self._last_received = cursor
+                self._resume_request = (self._options.replay_mode, cursor)
+                self._resume_ack = asyncio.get_running_loop().create_future()
+                self._resume_ack.add_done_callback(self._consume_future_exception)
+                self._set_state(ConnectionState(ConnectionStatus.RESUMING))
+                resume: dict[str, Any] = {
+                    "type": "session.resume",
+                    "replay_mode": self._options.replay_mode.value,
+                    "since_cursor": cursor,
+                }
+                if self._options.replay_mode is ReplayMode.LATEST_N:
+                    resume["latest_n"] = self._options.replay_latest_n
+                await self._send_regular(resume)
+                try:
+                    await asyncio.wait_for(asyncio.shield(self._resume_ack), RESUME_ACK_TIMEOUT)
+                except TimeoutError as exc:
+                    raise ResumeAckError("session.resume_ack timed out", "bpp.resume_ack_timeout") from exc
+
+            if self._is_stopping():
+                raise _TerminalStop
+            if self._initial_ready is not None and not self._initial_ready.done():
+                self._initial_ready.set_result(None)
+            self._ever_ready = True
+            self._spawn(self._heartbeat_loop(generation), "borgee-heartbeat")
+            assert receive_task is not None
+            await receive_task
+            raise _RecoverableDisconnect("WebSocket closed")
+        except ConnectionClosed as exc:
+            close_code = _connection_close_code(exc)
+            if self._background_failure is not None:
+                raise self._background_failure from exc
+            if close_code == 4004:
+                raise PreResumeError("authentication failed", "bpp.auth_failed") from exc
+            if close_code == 1009:
+                raise ProtocolCapacityError("WebSocket peer rejected a frame for capacity") from exc
+            if close_code in {1002, 1003, 1007, 1008}:
+                raise ProtocolError(
+                    f"WebSocket peer closed for a protocol violation ({close_code})",
+                    "bpp.peer_protocol_close",
+                ) from exc
+            if not self._resume_ack_seen:
+                raise PreResumeError(
+                    "WebSocket closed before resume acknowledgement", "bpp.pre_resume_closed"
+                ) from exc
+            raise _RecoverableDisconnect(f"WebSocket closed with code {close_code}") from exc
+        except TimeoutError as exc:
+            if not opened and self._ever_ready:
+                raise _RecoverableDisconnect("WebSocket dial timed out") from exc
+            if not self._resume_ack_seen:
+                raise PreResumeError("pre-resume deadline expired", "bpp.pre_resume_timeout") from exc
+            raise
+        except OSError as exc:
+            if not opened and self._ever_ready:
+                raise _RecoverableDisconnect("WebSocket dial failed") from exc
+            raise PreResumeError("WebSocket dial failed", "bpp.connect_failed") from exc
+        finally:
+            await self._invalidate_generation(
+                BorgeeError("connection generation ended", "bpp.connection_lost")
+            )
+            await self._cleanup_generation(BorgeeError("connection generation ended", "bpp.connection_lost"))
+
+    async def _receive_loop(self, websocket: ClientConnection, generation: int) -> None:
+        async for raw in websocket:
+            received_at = time.monotonic()
+            if generation != self._active_generation:
+                return
+            if isinstance(raw, bytes):
+                size = len(raw)
+                try:
+                    text = raw.decode("utf-8")
+                except UnicodeDecodeError as exc:
+                    raise ProtocolError("incoming frame is not UTF-8", "bpp.frame_encoding") from exc
+            else:
+                text = raw
+                size = len(raw.encode("utf-8"))
+            if size > MAX_INCOMING_BYTES:
+                raise ProtocolCapacityError("incoming frame exceeds five MiB")
+            try:
+                frame = json.loads(text)
+            except (TypeError, json.JSONDecodeError) as exc:
+                raise ProtocolError("incoming frame is not valid JSON", "bpp.frame_json") from exc
+            if not isinstance(frame, dict) or not isinstance(frame.get("type"), str):
+                raise ProtocolError("incoming frame has no string type", "bpp.frame_shape")
+            frame_type = frame["type"]
+            if frame_type == "ping":
+                self._send_reserved_nowait({"type": "pong"}, send_timeout=1.0)
+            elif frame_type in {"pong", "agent_toggle"}:
+                continue
+            elif frame_type == "session.resume_ack":
+                self._handle_resume_ack(frame, generation)
+            elif frame_type == "semantic_action_result":
+                self._handle_action_result(frame)
+            elif frame_type == "permission_denied":
+                self._handle_permission_denied(frame)
+            elif frame_type == "inbound_message":
+                self._handle_inbound(frame, size, generation)
+            elif frame_type == "session.summary":
+                self._handle_summary(frame, size, generation)
+            elif frame_type == "agent_config_update":
+                self._admit_config(frame, size, generation)
+            elif frame_type == "request":
+                self._admit_request(frame, size, received_at, generation)
+            else:
+                self._options.logger.debug("Ignored unknown BPP frame type %s", frame_type)
+
+    def _handle_resume_ack(self, frame: dict[str, Any], generation: int) -> None:
+        if generation != self._active_generation or self._resume_ack_seen or self._resume_request is None:
+            raise ResumeAckError("unexpected or duplicate session.resume_ack")
+        requested_mode, since_cursor = self._resume_request
+        replay_mode = frame.get("replay_mode")
+        count = frame.get("count")
+        high_water = frame.get("high_water")
+        reset = frame.get("reset")
+        reason = frame.get("reason")
+        if replay_mode != requested_mode.value:
+            raise ResumeAckError("session.resume_ack replay mode does not match the request")
+        if not _is_int(count) or count < 0 or count > MAX_INCOMING_FRAMES:
+            raise ResumeAckError("session.resume_ack count is outside the supported bounds")
+        if not _is_int(high_water) or high_water < 0:
+            raise ResumeAckError("session.resume_ack high_water is invalid")
+        if not isinstance(reset, bool) or not isinstance(reason, str):
+            raise ResumeAckError("session.resume_ack reset fields are invalid")
+        if reset:
+            raise ResumeAckError(f"server requires cursor reset: {reason}", "bpp.resume_reset_required")
+        if high_water < since_cursor:
+            raise ResumeAckError("session.resume_ack high_water precedes the requested cursor")
+        if requested_mode is ReplayMode.SUMMARY and count != 1:
+            raise ResumeAckError("summary resume must announce exactly one summary frame")
+        self._resume_count = count
+        self._resume_high_water = high_water
+        self._resume_ack_seen = True
+        waiter = self._resume_ack
+        if waiter is not None and not waiter.done():
+            waiter.set_result(None)
+        if count == 0:
+            self._replay_arrived.set()
+            self._spawn(self._finish_zero_replay(generation), "borgee-zero-replay-checkpoint")
+        else:
+            self._spawn(self._wait_for_replay_arrival(generation), "borgee-replay-arrival-timeout")
+
+    def _handle_action_result(self, frame: dict[str, Any]) -> None:
+        nonce = frame.get("nonce")
+        if not isinstance(nonce, str):
+            raise ProtocolError("semantic_action_result nonce is invalid")
+        pending = self._pending_actions.pop(nonce, None)
+        if pending is None:
+            return
+        status = frame.get("status")
+        if status == "ok":
+            payload = frame.get("payload")
+            if not isinstance(payload, str):
+                pending.future.set_exception(ProtocolError("semantic action payload is not a string"))
+                raise ProtocolError("semantic action payload is not a string")
+            try:
+                result = None if payload == "" else json.loads(payload)
+            except json.JSONDecodeError as exc:
+                pending.future.set_exception(ProtocolError("semantic action payload is invalid JSON"))
+                raise ProtocolError("semantic action payload is invalid JSON") from exc
+            if pending.operation == "send_message" and isinstance(result, dict):
+                cursor = frame.get("cursor")
+                if not _is_int(cursor) or cursor < 0:
+                    pending.future.set_exception(ProtocolError("semantic action cursor is invalid"))
+                    raise ProtocolError("semantic action cursor is invalid")
+                result = {**result, "cursor": cursor}
+            pending.future.set_result(result)
+            return
+        if status == "error":
+            code = frame.get("error")
+            if not isinstance(code, str) or not code:
+                pending.future.set_exception(ProtocolError("semantic action error code is invalid"))
+                raise ProtocolError("semantic action error code is invalid")
+            pending.future.set_exception(BorgeeError(f"semantic action {pending.operation} failed", code))
+            return
+        pending.future.set_exception(ProtocolError("semantic action result status is invalid"))
+        raise ProtocolError("semantic action result status is invalid")
+
+    def _handle_permission_denied(self, frame: dict[str, Any]) -> None:
+        request_id = frame.get("request_id")
+        action = frame.get("attempted_action")
+        capability = frame.get("required_capability")
+        scope = frame.get("current_scope")
+        if not isinstance(request_id, str):
+            raise ProtocolError("permission_denied request_id is invalid")
+        if not isinstance(action, str):
+            raise ProtocolError("permission_denied action is invalid")
+        if not isinstance(capability, str):
+            raise ProtocolError("permission_denied capability is invalid")
+        if not isinstance(scope, str):
+            raise ProtocolError("permission_denied frame is invalid")
+        pending = self._pending_actions.pop(request_id, None)
+        if pending is not None:
+            pending.future.set_exception(
+                PermissionDeniedError(
+                    attempted_action=action,
+                    required_capability=capability,
+                    current_scope=scope,
+                )
+            )
+
+    def _handle_inbound(self, frame: dict[str, Any], size: int, generation: int) -> None:
+        if not self._resume_ack_seen:
+            raise ProtocolError("inbound message arrived before session.resume_ack")
+        if self._resume_request is not None and self._resume_request[0] is ReplayMode.SUMMARY:
+            raise ProtocolError("summary resume received an inbound message")
+        cursor = _required_int(frame, "cursor", minimum=1)
+        if cursor in self._seen_delivery_cursors:
+            return
+        replay_pending = self._replay_received < self._resume_count
+        if replay_pending:
+            if cursor <= self._last_checkpoint:
+                raise ProtocolError("inbound cursor is stale", "bpp.cursor_non_monotonic")
+        elif cursor < self._last_received:
+            raise ProtocolError("inbound cursor moved backwards", "bpp.cursor_non_monotonic")
+        elif cursor == self._last_received:
+            return
+        event = _map_inbound(frame, cursor)
+        self._seen_delivery_cursors.add(cursor)
+        self._last_received = max(self._last_received, cursor)
+        self._enqueue_delivery(event, cursor, size, generation)
+
+    def _handle_summary(self, frame: dict[str, Any], size: int, generation: int) -> None:
+        if not self._resume_ack_seen or self._resume_request is None:
+            raise ProtocolError("session summary arrived before session.resume_ack")
+        mode, since_cursor = self._resume_request
+        cursor = _required_int(frame, "cursor", minimum=0)
+        missed_count = _required_int(frame, "missed_count", minimum=0)
+        since = _required_int(frame, "since_cursor", minimum=0)
+        through = _required_int(frame, "through_cursor", minimum=0)
+        summary = frame.get("summary")
+        if (
+            mode is not ReplayMode.SUMMARY
+            or self._resume_count != 1
+            or self._replay_received != 0
+            or cursor != self._resume_high_water
+            or through != self._resume_high_water
+            or since != since_cursor
+            or not isinstance(summary, str)
+        ):
+            raise ProtocolError("session summary does not correlate with the resume request")
+        if cursor < self._last_checkpoint:
+            raise ProtocolError("summary cursor is stale", "bpp.cursor_non_monotonic")
+        event = ReplaySummaryEvent(cursor, missed_count, since, through, summary)
+        self._last_received = max(self._last_received, cursor)
+        self._enqueue_delivery(event, cursor, size, generation)
+
+    def _enqueue_delivery(self, event: DeliveryEvent, cursor: int, size: int, generation: int) -> None:
+        buffered_count = len(self._deliveries) + len(self._deferred_live)
+        if buffered_count >= MAX_INCOMING_FRAMES or self._delivery_bytes + size > MAX_INCOMING_BYTES:
+            raise ProtocolCapacityError("application cursor buffer capacity exceeded")
+        replay_pending = self._replay_received < self._resume_count
+        replay = replay_pending and cursor <= self._resume_high_water
+        if (
+            not replay_pending
+            and cursor <= self._resume_high_water
+            and self._state.status is ConnectionStatus.RESUMING
+        ):
+            raise ProtocolError("received an unannounced replay frame")
+        buffered = _BufferedDelivery(event, cursor, size, generation, replay)
+        self._delivery_bytes += size
+        if replay_pending and not replay:
+            self._deferred_live.append(buffered)
+            return
+        if replay:
+            self._replay_received += 1
+        self._deliveries.append(buffered)
+        if replay and self._replay_received == self._resume_count:
+            self._replay_arrived.set()
+            self._deliveries.extend(sorted(self._deferred_live, key=lambda item: item.cursor))
+            self._deferred_live.clear()
+        self._delivery_wakeup.set()
+
+    async def _wait_for_replay_arrival(self, generation: int) -> None:
+        try:
+            await asyncio.wait_for(self._replay_arrived.wait(), REPLAY_ARRIVAL_TIMEOUT)
+        except TimeoutError as exc:
+            if generation == self._active_generation:
+                raise ResumeAckError(
+                    "declared replay frames did not arrive",
+                    "bpp.replay_incomplete",
+                ) from exc
+
+    def _admit_config(self, frame: dict[str, Any], size: int, generation: int) -> None:
+        queue = self._config_queue
+        if (
+            queue is None
+            or queue.full()
+            or size > CONFIG_MAX_BYTES
+            or self._config_queue_bytes + size > CONFIG_MAX_BYTES
+        ):
+            raise ProtocolCapacityError("configuration queue capacity exceeded")
+        queue.put_nowait((frame, size, generation))
+        self._config_queue_bytes += size
+
+    def _admit_request(
+        self,
+        frame: dict[str, Any],
+        size: int,
+        received_at: float,
+        generation: int,
+    ) -> None:
+        request_id = frame.get("id")
+        if not isinstance(request_id, str) or not request_id:
+            raise ProtocolError("server request id is invalid")
+        deadline = received_at + SERVER_REQUEST_DEADLINE
+        if size > REQUEST_SINGLE_MAX_BYTES:
+            self._send_reserved_nowait(
+                {"type": "response", "id": request_id, "error": "server_request_too_large"},
+                deadline=deadline,
+            )
+            return
+        queue = self._request_queue
+        if queue is None or queue.full() or self._request_queue_bytes + size > REQUEST_MAX_BYTES:
+            self._send_reserved_nowait(
+                {"type": "response", "id": request_id, "error": "server_request_busy"},
+                deadline=deadline,
+            )
+            return
+        queue.put_nowait((frame, size, received_at, generation))
+        self._request_queue_bytes += size
+
+    async def _config_worker(self, generation: int) -> None:
+        queue = self._config_queue
+        assert queue is not None
+        while generation == self._active_generation:
+            frame, size, item_generation = await queue.get()
+            self._config_queue_bytes -= size
+            if item_generation != self._active_generation:
+                continue
+            update = self._decode_config_update(frame)
+            cached = self._config_acks.get(update.idempotency_key)
+            if cached is not None:
+                self._config_acks.move_to_end(update.idempotency_key)
+                await self._send_reserved(cached)
+                continue
+
+            result = await self._apply_config(update, generation)
+            if generation != self._active_generation:
+                continue
+            reason = (
+                ""
+                if result.status is ConfigApplyStatus.APPLIED
+                else (result.reason or FaultReason.UNKNOWN).value
+            )
+            ack = {
+                "type": "agent_config_ack",
+                "cursor": update.cursor,
+                "agent_id": update.agent_id,
+                "schema_version": update.schema_version,
+                "idempotency_key": update.idempotency_key,
+                "status": result.status.value,
+                "reason": reason,
+                "applied_at": int(time.time() * 1000) if result.status is ConfigApplyStatus.APPLIED else 0,
+            }
+            self._config_acks[update.idempotency_key] = ack
+            self._config_acks.move_to_end(update.idempotency_key)
+            while len(self._config_acks) > 256:
+                self._config_acks.popitem(last=False)
+            self._enqueue_config_observer(update, size)
+            await self._send_reserved(ack)
+
+    def _decode_config_update(self, frame: dict[str, Any]) -> ConfigUpdate:
+        agent_id = frame.get("agent_id")
+        idempotency_key = frame.get("idempotency_key")
+        blob = frame.get("blob")
+        if not isinstance(agent_id, str) or not isinstance(idempotency_key, str) or not idempotency_key:
+            raise ProtocolError("configuration update identity is invalid")
+        if not isinstance(blob, str):
+            raise ProtocolError("configuration update blob is not a string")
+        try:
+            decoded_blob = json.loads(blob)
+        except json.JSONDecodeError as exc:
+            raise ProtocolError("configuration update blob is invalid JSON") from exc
+        return ConfigUpdate(
+            agent_id=agent_id,
+            schema_version=_required_int(frame, "schema_version", minimum=0),
+            blob=decoded_blob,
+            idempotency_key=idempotency_key,
+            cursor=_required_int(frame, "cursor", minimum=1),
+        )
+
+    async def _apply_config(self, update: ConfigUpdate, generation: int) -> ConfigApplyResult:
+        handler = self._options.config_update_handler
+        if handler is None:
+            return ConfigApplyResult(ConfigApplyStatus.REJECTED, FaultReason.UNKNOWN)
+        cancelled = asyncio.Event()
+
+        async def invoke() -> ConfigApplyResult:
+            value = handler(update, ConfigApplyContext(cancelled))
+            if inspect.isawaitable(value):
+                value = await value
+            return value
+
+        if not self._try_acquire_handler_slot():
+            raise ProtocolCapacityError("configuration handler capacity exceeded")
+        try:
+            task = asyncio.create_task(invoke(), name="borgee-config-handler")
+        except BaseException:
+            self._handler_slots_available += 1
+            raise
+        self._register_handler_task(task)
+        try:
+            done, _ = await asyncio.wait({task}, timeout=self._options.config_apply_timeout)
+        except asyncio.CancelledError:
+            cancelled.set()
+            self._detach_handler_task(task)
+            raise
+        if not done:
+            cancelled.set()
+            self._detach_handler_task(task)
+            return ConfigApplyResult(ConfigApplyStatus.REJECTED, FaultReason.RUNTIME_TIMEOUT)
+        try:
+            result = task.result()
+        except BaseException:
+            self._options.logger.exception("Configuration handler failed")
+            return ConfigApplyResult(ConfigApplyStatus.REJECTED, FaultReason.UNKNOWN)
+        finally:
+            cancelled.set()
+            self._release_handler_task(task)
+        if generation != self._active_generation or not isinstance(result, ConfigApplyResult):
+            return ConfigApplyResult(ConfigApplyStatus.REJECTED, FaultReason.UNKNOWN)
+        status: object = result.status
+        if not isinstance(status, ConfigApplyStatus):
+            return ConfigApplyResult(ConfigApplyStatus.REJECTED, FaultReason.UNKNOWN)
+        if status is ConfigApplyStatus.APPLIED:
+            return ConfigApplyResult(ConfigApplyStatus.APPLIED)
+        reason = result.reason if result.reason in set(FaultReason) else FaultReason.UNKNOWN
+        return ConfigApplyResult(status, reason)
+
+    def _enqueue_config_observer(self, update: ConfigUpdate, size: int) -> None:
+        if self._options.config_update_observer is None:
+            return
+        dropped = 0
+        while self._observer_queue and (
+            len(self._observer_queue) >= 64 or self._observer_bytes + size > (1 << 20)
+        ):
+            _, old_size = self._observer_queue.popleft()
+            self._observer_bytes -= old_size
+            dropped += 1
+        if size > 1 << 20:
+            dropped += 1
+        else:
+            self._observer_queue.append((update, size))
+            self._observer_bytes += size
+            self._observer_wakeup.set()
+        if dropped:
+            self._options.logger.warning("Dropped %d old configuration observer event(s)", dropped)
+
+    async def _run_config_observer(self) -> None:
+        while True:
+            if not self._observer_queue:
+                self._observer_wakeup.clear()
+                await self._observer_wakeup.wait()
+                continue
+            update, size = self._observer_queue.popleft()
+            self._observer_bytes -= size
+            observer = self._options.config_update_observer
+            if observer is None:
+                continue
+            try:
+                result = observer(update)
+                if inspect.isawaitable(result):
+                    await result
+            except asyncio.CancelledError:
+                raise
+            except BaseException:
+                self._options.logger.exception("Configuration observer failed")
+
+    async def _request_worker(self, generation: int) -> None:
+        queue = self._request_queue
+        assert queue is not None
+        while generation == self._active_generation:
+            frame, size, received_at, item_generation = await queue.get()
+            self._request_queue_bytes -= size
+            if item_generation != self._active_generation:
+                continue
+            request_id = frame["id"]
+            deadline = received_at + SERVER_REQUEST_DEADLINE
+            if time.monotonic() - received_at >= SERVER_REQUEST_QUEUE_WAIT:
+                await self._send_request_error(request_id, "server_request_busy", deadline, generation)
+                continue
+            handler = self._options.server_request_handler
+            if handler is None:
+                await self._send_request_error(request_id, "no_server_request_handler", deadline, generation)
+                continue
+            data = frame.get("data")
+            action = data.get("action", "") if isinstance(data, dict) else ""
+            if not isinstance(action, str):
+                action = ""
+            remaining = deadline - time.monotonic()
+            handler_timeout = min(SERVER_REQUEST_HANDLER_TIMEOUT, remaining - 1.0)
+            if handler_timeout <= 0:
+                await self._send_request_error(request_id, "server_request_busy", deadline, generation)
+                continue
+
+            if not self._try_acquire_handler_slot():
+                await self._send_request_error(request_id, "server_request_busy", deadline, generation)
+                continue
+            try:
+                task = asyncio.create_task(
+                    self._invoke_server_handler(handler, action, data),
+                    name="borgee-server-request-handler",
+                )
+            except BaseException:
+                self._handler_slots_available += 1
+                raise
+            self._register_handler_task(task)
+            try:
+                done, _ = await asyncio.wait({task}, timeout=handler_timeout)
+            except asyncio.CancelledError:
+                self._detach_handler_task(task)
+                raise
+            if not done:
+                self._detach_handler_task(task)
+                await self._send_request_error(request_id, "server_request_timeout", deadline, generation)
+                continue
+            try:
+                result = task.result()
+            except BaseException:
+                await self._send_request_error(request_id, "server_request_failed", deadline, generation)
+                continue
+            finally:
+                self._release_handler_task(task)
+            if generation != self._active_generation:
+                continue
+            response = {"type": "response", "id": request_id, "data": result}
+            try:
+                await self._send_reserved(response, deadline=deadline)
+            except ProtocolCapacityError:
+                await self._send_request_error(request_id, "server_request_too_large", deadline, generation)
+
+    @staticmethod
+    async def _invoke_server_handler(
+        handler: ServerRequestHandler,
+        action: str,
+        data: Any,
+    ) -> Any:
+        value = handler(action, data)
+        return await value if inspect.isawaitable(value) else value
+
+    async def _send_request_error(
+        self,
+        request_id: str,
+        code: str,
+        deadline: float,
+        generation: int,
+    ) -> None:
+        if generation != self._active_generation or time.monotonic() >= deadline:
+            return
+        await self._send_reserved(
+            {"type": "response", "id": request_id, "error": code},
+            deadline=deadline,
+        )
+
+    async def _perform(self, operation: str, payload: dict[str, Any], *, allow_pre_resume: bool) -> Any:
+        # One action_timeout bounds waiting-for-online AND the response wait together (FIX C).
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + self._options.action_timeout
+        if not allow_pre_resume:
+            await self._wait_until_online_for_action(operation, deadline)
+        elif self._writer is None or operation != "get_me":
+            raise NotOnlineError("only get_me is allowed before resume")
+        if len(self._pending_actions) >= ACTION_PENDING_MAX:
+            raise ProtocolCapacityError("too many pending semantic actions")
+        nonce = str(uuid.uuid4())
+        future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
+        self._pending_actions[nonce] = _PendingAction(operation, future)
+        try:
+            await self._send_regular(
+                {
+                    "type": "semantic_action",
+                    "agent_id": self._agent_id,
+                    "action": operation,
+                    "payload": json.dumps(payload, separators=(",", ":"), ensure_ascii=False),
+                    "nonce": nonce,
+                }
+            )
+            remaining = max(0.0, deadline - loop.time())
+            return await asyncio.wait_for(future, remaining)
+        except TimeoutError as exc:
+            raise BorgeeError(f"semantic action {operation} timed out", "bpp.action_timeout") from exc
+        finally:
+            self._pending_actions.pop(nonce, None)
+
+    async def _read_cursor_detached_on_cancel(self) -> int:
+        task = asyncio.create_task(
+            self._options.cursor_store.read(self._cursor_key),
+            name="borgee-cursor-read",
+        )
+        try:
+            return await asyncio.shield(task)
+        except asyncio.CancelledError:
+            self._detach_task(task)
+            raise
+
+    @staticmethod
+    def _consume_future_exception(future: asyncio.Future[Any]) -> None:
+        if future.cancelled():
+            return
+        with contextlib.suppress(BaseException):
+            future.exception()
+
+    async def _heartbeat_loop(self, generation: int) -> None:
+        while generation == self._active_generation:
+            await asyncio.sleep(self._options.heartbeat_interval)
+            if generation != self._active_generation:
+                return
+            await self._send_regular(
+                {
+                    "type": "heartbeat",
+                    "plugin_id": self._options.plugin_id,
+                    "agent_id": self._agent_id,
+                    "status": "online",
+                    "reason": "",
+                    "timestamp": int(time.time() * 1000),
+                }
+            )
+
+    async def _next_delivery(self) -> Delivery | None:
+        while True:
+            if self._active_delivery is None and self._deliveries:
+                buffered = self._deliveries.popleft()
+                self._delivery_bytes -= buffered.size
+                delivery = Delivery(self, buffered)
+                self._active_delivery = delivery
+                return delivery
+            if (
+                self._active_delivery is None
+                and not self._deliveries
+                and (self._closing or self._terminal_error is not None)
+            ):
+                return None
+            self._delivery_wakeup.clear()
+            if self._active_delivery is None and self._deliveries:
+                continue
+            await self._delivery_wakeup.wait()
+
+    async def _settle_delivery(
+        self,
+        delivery: Delivery,
+        *,
+        checkpoint: bool,
+        error: BaseException | None,
+    ) -> None:
+        try:
+            async with self._cursor_write_lock:
+                if delivery is not self._active_delivery or delivery._generation != self._active_generation:
+                    raise StaleDeliveryError()
+                if checkpoint:
+                    if delivery.cursor < self._last_checkpoint:
+                        raise StaleDeliveryError("delivery cursor is older than the durable checkpoint")
+                    if delivery.cursor > self._last_checkpoint:
+                        await self._options.cursor_store.write(self._cursor_key, delivery.cursor)
+                        self._last_checkpoint = delivery.cursor
+                    if delivery._replay:
+                        self._replay_checkpointed += 1
+                        if self._replay_checkpointed == self._resume_count:
+                            await self._finish_replay_locked(delivery._generation)
+                    self._active_delivery = None
+                    self._delivery_wakeup.set()
+                    return
+                self._active_delivery = None
+                self._delivery_wakeup.set()
+        except StaleDeliveryError:
+            raise
+        except Exception as exc:
+            await self._terminal(exc)
+            raise
+        await self._terminal(error or BorgeeError("delivery failed", "bpp.delivery_failed"))
+
+    async def _finish_zero_replay(self, generation: int) -> None:
+        async with self._cursor_write_lock:
+            if generation != self._active_generation:
+                return
+            await self._finish_replay_locked(generation)
+
+    async def _finish_replay_locked(self, generation: int) -> None:
+        if generation != self._active_generation:
+            raise StaleDeliveryError()
+        if self._resume_high_water > self._last_checkpoint:
+            await self._options.cursor_store.write(self._cursor_key, self._resume_high_water)
+            self._last_checkpoint = self._resume_high_water
+        if generation == self._active_generation:
+            self._set_state(ConnectionState(ConnectionStatus.ONLINE))
+
+    def _require_online(self) -> None:
+        if self._state.status is not ConnectionStatus.ONLINE:
+            raise NotOnlineError()
+
+    async def _wait_until_online_for_action(self, operation: str, deadline: float) -> None:
+        if self._state.status is ConnectionStatus.ONLINE and self._writer is not None:
+            return
+        # Fail fast on a terminal fault or an explicit close so the real reason (e.g.
+        # bpp.auth_failed) surfaces immediately, instead of blocking for the whole action_timeout.
+        if self._is_stopping() or self._closed_permanently:
+            raise self._terminal_error or NotOnlineError("connection is not available")
+        if not self._ever_online:
+            self._require_online()
+        if not self._options.auto_reconnect:
+            raise NotOnlineError("auto reconnect is disabled")
+        loop = asyncio.get_running_loop()
+        remaining = deadline - loop.time()
+        if remaining <= 0:
+            raise BorgeeError(f"semantic action {operation} timed out", "bpp.action_timeout")
+        online_task = asyncio.ensure_future(self._online_ready.wait())
+        terminal_task = asyncio.ensure_future(self._terminal_event.wait())
+        try:
+            done, _pending = await asyncio.wait(
+                {online_task, terminal_task},
+                timeout=remaining,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+        finally:
+            for task in (online_task, terminal_task):
+                task.cancel()
+            await asyncio.gather(online_task, terminal_task, return_exceptions=True)
+        if self._is_stopping() or self._closed_permanently or terminal_task in done:
+            raise self._terminal_error or BorgeeError("connection closed", "bpp.client_closed")
+        if not done:
+            raise BorgeeError(f"semantic action {operation} timed out", "bpp.action_timeout")
+        if self._state.status is not ConnectionStatus.ONLINE or self._writer is None:
+            raise NotOnlineError("connection left ONLINE before semantic action could be sent")
+
+    async def _send_regular(self, frame: dict[str, Any]) -> None:
+        writer = self._writer
+        if writer is None:
+            raise NotOnlineError("WebSocket writer is unavailable")
+        await writer.send(frame, lane="regular")
+
+    async def _send_reserved(
+        self,
+        frame: dict[str, Any],
+        *,
+        deadline: float | None = None,
+    ) -> None:
+        writer = self._writer
+        if writer is None:
+            raise NotOnlineError("WebSocket writer is unavailable")
+        await writer.send(frame, lane="reserved", deadline=deadline)
+
+    def _send_reserved_nowait(
+        self,
+        frame: dict[str, Any],
+        *,
+        deadline: float | None = None,
+        send_timeout: float = 0.1,
+    ) -> None:
+        writer = self._writer
+        if writer is None:
+            raise NotOnlineError("WebSocket writer is unavailable")
+        completion = writer.send_nowait(
+            frame,
+            lane="reserved",
+            deadline=deadline,
+            send_timeout=send_timeout,
+        )
+        completion.add_done_callback(self._consume_send_result)
+
+    def _consume_send_result(self, future: asyncio.Future[None]) -> None:
+        if future.cancelled():
+            return
+        error = future.exception()
+        if error is not None and not self._closing:
+            self._options.logger.warning("Reserved BPP write failed: %s", type(error).__name__)
+            websocket = self._websocket
+            if websocket is not None:
+                websocket.transport.abort()
+
+    def _spawn(self, coroutine: Coroutine[Any, Any, Any], name: str) -> asyncio.Task[Any]:
+        task: asyncio.Task[Any] = asyncio.create_task(coroutine, name=name)
+        self._generation_tasks.add(task)
+        task.add_done_callback(self._generation_task_done)
+        return task
+
+    def _generation_task_done(self, task: asyncio.Task[Any]) -> None:
+        self._generation_tasks.discard(task)
+        if task.cancelled() or self._closing or self._terminal_set:
+            return
+        error = task.exception()
+        if error is not None:
+            if isinstance(error, ConnectionClosed):
+                return
+            self._background_failure = error
+            websocket = self._websocket
+            if websocket is not None:
+                websocket.transport.abort()
+
+    def _detach_task(self, task: asyncio.Task[Any]) -> None:
+        if task.done():
+            self._detached_task_done(task)
+            return
+        task.cancel()
+        _DETACHED_TASK_GUARDIAN.add(task)
+        self._detached_tasks.add(task)
+        task.add_done_callback(self._detached_task_done)
+
+    def _detached_task_done(self, task: asyncio.Task[Any]) -> None:
+        _DETACHED_TASK_GUARDIAN.discard(task)
+        self._detached_tasks.discard(task)
+        if task.cancelled():
+            return
+        with contextlib.suppress(BaseException):
+            task.exception()
+
+    def _try_acquire_handler_slot(self) -> bool:
+        if self._handler_slots_available == 0:
+            return False
+        self._handler_slots_available -= 1
+        return True
+
+    def _register_handler_task(self, task: asyncio.Task[Any]) -> None:
+        self._handler_slot_tasks.add(task)
+
+    def _release_handler_task(self, task: asyncio.Task[Any]) -> None:
+        if task not in self._handler_slot_tasks:
+            return
+        self._handler_slot_tasks.remove(task)
+        self._handler_slots_available += 1
+
+    def _detach_handler_task(self, task: asyncio.Task[Any]) -> None:
+        if task.done():
+            self._handler_task_done(task)
+            return
+        task.cancel()
+        _DETACHED_TASK_GUARDIAN.add(task)
+        self._detached_tasks.add(task)
+        task.add_done_callback(self._handler_task_done)
+
+    def _handler_task_done(self, task: asyncio.Task[Any]) -> None:
+        _DETACHED_TASK_GUARDIAN.discard(task)
+        self._detached_tasks.discard(task)
+        if not task.cancelled():
+            with contextlib.suppress(BaseException):
+                task.exception()
+        self._release_handler_task(task)
+
+    async def _invalidate_generation(self, error: BaseException) -> None:
+        async with self._cursor_write_lock:
+            self._active_generation = None
+            self._online_ready.clear()
+            self._deliveries.clear()
+            self._deferred_live.clear()
+            self._seen_delivery_cursors.clear()
+            self._delivery_bytes = 0
+            self._active_delivery = None
+            self._delivery_wakeup.set()
+            self._fail_pending(error)
+            waiter = self._resume_ack
+            if waiter is not None and not waiter.done():
+                waiter.set_exception(error)
+
+    async def _cleanup_generation(self, error: BaseException) -> None:
+        async with self._generation_cleanup_lock:
+            current = asyncio.current_task()
+            tasks = [task for task in self._generation_tasks if task is not current]
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+            self._generation_tasks.clear()
+            writer = self._writer
+            self._writer = None
+            if writer is not None:
+                await writer.close(error)
+            websocket = self._websocket
+            self._websocket = None
+            if websocket is not None:
+                try:
+                    await asyncio.wait_for(websocket.close(), 1.0)
+                except (TimeoutError, ConnectionClosed):
+                    websocket.transport.abort()
+            self._config_queue = None
+            self._request_queue = None
+            self._config_queue_bytes = 0
+            self._request_queue_bytes = 0
+
+    async def _terminal(self, error: BaseException) -> None:
+        async with self._lifecycle_lock:
+            if self._terminal_set or self._closing or self._closed_permanently:
+                return
+            self._terminal_set = True
+            self._terminal_error = error
+            self._terminal_event.set()
+            future = self._connect_future
+            if future is not None and not future.done():
+                future.set_exception(error)
+            supervisor = self._supervisor_task
+            current = asyncio.current_task()
+            if supervisor is not None and supervisor is not current:
+                supervisor.cancel()
+            code = error.code if isinstance(error, BorgeeError) else "bpp.internal"
+            reason = FaultReason.API_KEY_INVALID if code == "bpp.auth_failed" else FaultReason.UNKNOWN
+            self._set_state(ConnectionState(ConnectionStatus.ERROR, reason=reason, code=code))
+        await self._invalidate_generation(error)
+        websocket = self._websocket
+        if websocket is not None:
+            websocket.transport.abort()
+        if supervisor is not None and supervisor is not current:
+            with contextlib.suppress(asyncio.CancelledError):
+                await supervisor
+        await self._cleanup_generation(error)
+
+    def _fail_pending(self, error: BaseException) -> None:
+        for pending in self._pending_actions.values():
+            if not pending.future.done():
+                pending.future.set_exception(error)
+        self._pending_actions.clear()
+
+    def _set_state(self, state: ConnectionState) -> None:
+        if self._terminal_set and state.status not in {ConnectionStatus.ERROR, ConnectionStatus.CLOSED}:
+            return
+        if self._closed_permanently and state.status is not ConnectionStatus.CLOSED:
+            return
+        self._state = state
+        if state.status is ConnectionStatus.ONLINE:
+            self._ever_online = True
+            self._online_ready.set()
+        else:
+            self._online_ready.clear()
+        if self._state_queue.full():
+            with contextlib.suppress(asyncio.QueueEmpty):
+                self._state_queue.get_nowait()
+        self._state_queue.put_nowait(state)
+
+
+def _is_int(value: object) -> TypeGuard[int]:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _connection_close_code(error: ConnectionClosed) -> int | None:
+    if error.rcvd is not None:
+        return error.rcvd.code
+    if error.sent is not None:
+        return error.sent.code
+    return None
+
+
+def _required_int(frame: dict[str, Any], field: str, *, minimum: int) -> int:
+    value = frame.get(field)
+    if not _is_int(value) or value < minimum:
+        raise ProtocolError(f"{field} must be an integer greater than or equal to {minimum}")
+    return value
+
+
+def _required_str(frame: dict[str, Any], field: str) -> str:
+    value = frame.get(field)
+    if not isinstance(value, str):
+        raise ProtocolError(f"{field} must be a string")
+    return value
+
+
+def _map_inbound(frame: dict[str, Any], cursor: int) -> InboundMessageEvent:
+    try:
+        kind = InboundKind(_required_str(frame, "kind"))
+    except ValueError as exc:
+        raise ProtocolError("inbound message kind is invalid") from exc
+    channel_id = _required_str(frame, "channel_id")
+    channel_type = _required_str(frame, "channel_type") or None
+    message_id = _required_str(frame, "message_id")
+    author_id = _required_str(frame, "author_id")
+    author_name = _required_str(frame, "author_name") or None
+    body = _required_str(frame, "body")
+    created_at = _required_int(frame, "created_at", minimum=0)
+    message: Message | None = None
+    reaction: InboundReaction | None = None
+    if kind in {InboundKind.MESSAGE, InboundKind.EDITED, InboundKind.MENTION}:
+        message = Message(
+            id=message_id,
+            channel_id=channel_id,
+            author_id=author_id,
+            body=body,
+            created_at=created_at,
+        )
+    if kind is InboundKind.REACTION:
+        added = frame.get("reaction_added")
+        if not isinstance(added, bool):
+            raise ProtocolError("reaction_added must be a boolean")
+        reaction = InboundReaction(
+            emoji=_required_str(frame, "emoji"),
+            user_id=_required_str(frame, "reactor_id"),
+            added=added,
+        )
+    return InboundMessageEvent(
+        kind=kind,
+        cursor=cursor,
+        channel_id=channel_id,
+        created_at=created_at,
+        channel_type=channel_type,
+        message=message,
+        message_id=message_id if kind in {InboundKind.DELETED, InboundKind.REACTION} else None,
+        reaction=reaction,
+        author_name=author_name,
+    )