@neoline/hostbridge 2.0.4 → 2.0.5

package/src/server_control_mcp/mux_rpc.py

@@ -0,0 +1,1779 @@
+"""Persistent, concurrent RPC over the HostBridge multiplexed wire protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from collections import deque
+from collections.abc import Awaitable, Callable, Mapping
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+
+from .mux_connection import ByteCreditWindow, ConnectionLifecycle, ConnectionState, MuxStateError
+from .mux_protocol import (
+    MAX_FRAME_PAYLOAD_BYTES,
+    FrameType,
+    MuxCodec,
+    MuxFrame,
+    MuxProtocolError,
+    SequenceTracker,
+    StreamIdAllocator,
+    StreamParity,
+    decode_control_payload,
+    decode_window_update,
+    encode_control_payload,
+    encode_frame,
+    encode_window_update,
+)
+from .mux_stream import AsyncByteCreditWindow, MuxRpcStream
+
+MuxRpcHandler = Callable[[str, dict[str, object]], Awaitable[dict[str, object]]]
+MuxRpcStreamHandler = Callable[[str, dict[str, object], MuxRpcStream], Awaitable[dict[str, object]]]
+MuxRpcRequestClosedHandler = Callable[[str], Awaitable[None]]
+MuxFrameWriteFailureHandler = Callable[[BaseException], Awaitable[None]]
+
+DEFAULT_STREAM_WINDOW_BYTES = 1024 * 1024
+DEFAULT_CONNECTION_WINDOW_BYTES = 32 * 1024 * 1024
+DEFAULT_DATA_CHUNK_BYTES = 64 * 1024
+DEFAULT_TOMBSTONE_RETENTION_SECONDS = 5.0
+DEFAULT_MAX_TOMBSTONES = 65_536
+DEFAULT_MAX_STREAM_QUEUE_BYTES = 2 * 1024 * 1024
+DEFAULT_MAX_DATA_QUEUE_BYTES = 32 * 1024 * 1024
+DEFAULT_MAX_CONTROL_QUEUE_BYTES = 64 * 1024
+DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 30.0
+DEFAULT_HEARTBEAT_TIMEOUT_SECONDS = 10.0
+DEFAULT_HANDSHAKE_TIMEOUT_SECONDS = 10.0
+DEFAULT_CLEANUP_TIMEOUT_SECONDS = 5.0
+
+
+class MuxRpcError(RuntimeError):
+    pass
+
+
+class MuxCapacityError(MuxRpcError):
+    pass
+
+
+class MuxConnectionClosed(MuxRpcError):
+    pass
+
+
+class MuxRemoteError(MuxRpcError):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        retryable: bool = False,
+        details: dict[str, object] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.retryable = retryable
+        self.details = details or {}
+
+
+class MuxRpcFailure(MuxRemoteError):
+    """Structured failure raised by a server-side RPC handler."""
+
+
+@dataclass(frozen=True, slots=True)
+class _TerminalStream:
+    sequences: SequenceTracker
+    expires_at: float
+
+
+class _TerminalStreams:
+    def __init__(
+        self,
+        *,
+        retention_seconds: float = DEFAULT_TOMBSTONE_RETENTION_SECONDS,
+        max_entries: int = DEFAULT_MAX_TOMBSTONES,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if (
+            not isinstance(retention_seconds, (int, float))
+            or isinstance(retention_seconds, bool)
+            or not math.isfinite(retention_seconds)
+            or retention_seconds <= 0
+        ):
+            raise ValueError("retention_seconds must be a finite positive number")
+        _positive(max_entries, "max_entries")
+        self._retention_seconds = float(retention_seconds)
+        self._max_entries = max_entries
+        self._clock = clock
+        self._entries: dict[int, _TerminalStream] = {}
+
+    def add(self, stream_id: int, sequences: SequenceTracker) -> None:
+        self._expire()
+        if stream_id not in self._entries and len(self._entries) >= self._max_entries:
+            raise MuxCapacityError("terminal stream capacity is exhausted")
+        self._entries[stream_id] = _TerminalStream(
+            sequences,
+            self._clock() + self._retention_seconds,
+        )
+
+    def get(self, stream_id: int) -> _TerminalStream | None:
+        self._expire()
+        return self._entries.get(stream_id)
+
+    def clear(self) -> None:
+        self._entries.clear()
+
+    def _expire(self) -> None:
+        now = self._clock()
+        expired = [stream_id for stream_id, entry in self._entries.items() if entry.expires_at <= now]
+        for stream_id in expired:
+            del self._entries[stream_id]
+
+
+class _FrameReader:
+    def __init__(self, reader: asyncio.StreamReader) -> None:
+        self._reader = reader
+        self._codec = MuxCodec()
+        self._ready: deque[MuxFrame] = deque()
+
+    async def read(self) -> MuxFrame:
+        while not self._ready:
+            data = await self._reader.read(64 * 1024)
+            if not data:
+                if self._codec.buffered_bytes:
+                    raise MuxConnectionClosed("multiplexed connection ended with an incomplete frame")
+                raise MuxConnectionClosed("multiplexed connection closed")
+            self._ready.extend(self._codec.feed(data))
+        return self._ready.popleft()
+
+
+@dataclass(slots=True)
+class _QueuedFrame:
+    frame_type: FrameType
+    stream_id: int
+    sequences: SequenceTracker
+    flags: int
+    payload: bytes
+    completed: asyncio.Future[None]
+    queued_bytes: int
+    is_data: bool
+
+
+class _FrameWriter:
+    def __init__(
+        self,
+        writer: asyncio.StreamWriter,
+        *,
+        max_stream_queue_bytes: int = DEFAULT_MAX_STREAM_QUEUE_BYTES,
+        max_data_queue_bytes: int = DEFAULT_MAX_DATA_QUEUE_BYTES,
+        max_control_queue_bytes: int = DEFAULT_MAX_CONTROL_QUEUE_BYTES,
+        failure_handler: MuxFrameWriteFailureHandler | None = None,
+    ) -> None:
+        _positive(max_stream_queue_bytes, "max_stream_queue_bytes")
+        _positive(max_data_queue_bytes, "max_data_queue_bytes")
+        _positive(max_control_queue_bytes, "max_control_queue_bytes")
+        self._writer = writer
+        self._lock = asyncio.Lock()
+        self._max_stream_queue_bytes = max_stream_queue_bytes
+        self._max_data_queue_bytes = max_data_queue_bytes
+        self._max_control_queue_bytes = max_control_queue_bytes
+        self._stream_queue_bytes: dict[int, int] = {}
+        self._data_queue_bytes = 0
+        self._control_queue_bytes = 0
+        self._control_queue: deque[_QueuedFrame] = deque()
+        self._stream_queues: dict[int, deque[_QueuedFrame]] = {}
+        self._ready_streams: deque[int] = deque()
+        self._writer_task: asyncio.Task[None] | None = None
+        self._closed_error: BaseException | None = None
+        self._failure_handler = failure_handler
+
+    async def write_sequenced(
+        self,
+        frame_type: FrameType,
+        stream_id: int,
+        sequences: SequenceTracker,
+        *,
+        flags: int = 0,
+        payload: bytes = b"",
+    ) -> None:
+        completed: asyncio.Future[None] = asyncio.get_running_loop().create_future()
+        queued_bytes = max(1, len(payload))
+        is_data = frame_type is FrameType.DATA
+        queued = _QueuedFrame(frame_type, stream_id, sequences, flags, payload, completed, queued_bytes, is_data)
+        async with self._lock:
+            if self._closed_error is not None:
+                raise self._closed_error
+            self._reserve_budget(queued)
+            if stream_id == 0:
+                self._control_queue.append(queued)
+            else:
+                stream_queue = self._stream_queues.setdefault(stream_id, deque())
+                stream_queue.append(queued)
+                if len(stream_queue) == 1:
+                    self._ready_streams.append(stream_id)
+            if self._writer_task is None:
+                self._writer_task = asyncio.create_task(
+                    self._run(),
+                    name="hostbridge-mux-frame-writer",
+                )
+        await asyncio.shield(completed)
+
+    async def _run(self) -> None:
+        control_burst = 0
+        while True:
+            async with self._lock:
+                queued, control_burst = self._next_frame(control_burst)
+                if queued is None:
+                    self._writer_task = None
+                    return
+            try:
+                frame = MuxFrame(
+                    queued.frame_type,
+                    queued.stream_id,
+                    queued.sequences.next_outbound(),
+                    flags=queued.flags,
+                    payload=queued.payload,
+                )
+                self._writer.write(encode_frame(frame))
+                await self._writer.drain()
+            except (ConnectionError, OSError, RuntimeError) as exc:
+                error = MuxConnectionClosed("multiplexed connection write failed")
+                error.__cause__ = exc
+                await self._fail(error, queued)
+                return
+            except BaseException as exc:
+                await self._fail(exc, queued)
+                return
+            async with self._lock:
+                self._release_budget(queued)
+            if not queued.completed.done():
+                queued.completed.set_result(None)
+
+    def _reserve_budget(self, queued: _QueuedFrame) -> None:
+        if queued.is_data:
+            stream_bytes = self._stream_queue_bytes.get(queued.stream_id, 0)
+            if stream_bytes + queued.queued_bytes > self._max_stream_queue_bytes:
+                raise MuxCapacityError(
+                    f"stream {queued.stream_id} data queue limit is {self._max_stream_queue_bytes} bytes"
+                )
+            if self._data_queue_bytes + queued.queued_bytes > self._max_data_queue_bytes:
+                raise MuxCapacityError(f"connection data queue limit is {self._max_data_queue_bytes} bytes")
+            self._stream_queue_bytes[queued.stream_id] = stream_bytes + queued.queued_bytes
+            self._data_queue_bytes += queued.queued_bytes
+            return
+        if self._control_queue_bytes + queued.queued_bytes > self._max_control_queue_bytes:
+            raise MuxCapacityError(f"connection control queue limit is {self._max_control_queue_bytes} bytes")
+        self._control_queue_bytes += queued.queued_bytes
+
+    def _release_budget(self, queued: _QueuedFrame) -> None:
+        if queued.is_data:
+            stream_bytes = self._stream_queue_bytes[queued.stream_id] - queued.queued_bytes
+            if stream_bytes:
+                self._stream_queue_bytes[queued.stream_id] = stream_bytes
+            else:
+                del self._stream_queue_bytes[queued.stream_id]
+            self._data_queue_bytes -= queued.queued_bytes
+            return
+        self._control_queue_bytes -= queued.queued_bytes
+
+    def _next_frame(self, control_burst: int) -> tuple[_QueuedFrame | None, int]:
+        if self._control_queue and (control_burst < 8 or not self._ready_streams):
+            return self._control_queue.popleft(), control_burst + 1
+        if self._ready_streams:
+            stream_id = self._ready_streams.popleft()
+            stream_queue = self._stream_queues[stream_id]
+            queued = stream_queue.popleft()
+            if stream_queue:
+                self._ready_streams.append(stream_id)
+            else:
+                del self._stream_queues[stream_id]
+            return queued, 0
+        if self._control_queue:
+            return self._control_queue.popleft(), control_burst + 1
+        return None, control_burst
+
+    async def _fail(self, error: BaseException, active: _QueuedFrame) -> None:
+        async with self._lock:
+            self._closed_error = error
+            queued = [active, *self._control_queue]
+            for stream_queue in self._stream_queues.values():
+                queued.extend(stream_queue)
+            self._control_queue.clear()
+            self._stream_queues.clear()
+            self._ready_streams.clear()
+            self._stream_queue_bytes.clear()
+            self._data_queue_bytes = 0
+            self._control_queue_bytes = 0
+            self._writer_task = None
+        failure_handler = self._failure_handler
+        self._failure_handler = None
+        if failure_handler is not None:
+            try:
+                await failure_handler(error)
+            except BaseException as exc:
+                error.add_note(f"mux write failure cleanup also failed: {exc!r}")
+        for item in queued:
+            if not item.completed.done():
+                item.completed.set_exception(error)
+                item.completed.exception()
+
+
+@dataclass(slots=True)
+class _PendingRequest:
+    future: asyncio.Future[dict[str, object]]
+    sequences: SequenceTracker
+    result: dict[str, object] | None = None
+
+
+@dataclass(slots=True)
+class _ClientStreamRequest:
+    sequences: SequenceTracker
+    receive_window: int
+    opened: asyncio.Future[MuxRpcStream]
+    stream: MuxRpcStream | None = None
+    local_eof_sent: bool = False
+
+
+class MuxRpcClient:
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        *,
+        max_pending: int,
+        connection_window: int,
+        stream_window: int,
+        heartbeat_interval: float = DEFAULT_HEARTBEAT_INTERVAL_SECONDS,
+        heartbeat_timeout: float = DEFAULT_HEARTBEAT_TIMEOUT_SECONDS,
+        handshake_timeout: float = DEFAULT_HANDSHAKE_TIMEOUT_SECONDS,
+        cleanup_timeout: float = DEFAULT_CLEANUP_TIMEOUT_SECONDS,
+    ) -> None:
+        _positive(max_pending, "max_pending")
+        _positive(connection_window, "connection_window")
+        _positive(stream_window, "stream_window")
+        _finite_positive(heartbeat_interval, "heartbeat_interval")
+        _finite_positive(heartbeat_timeout, "heartbeat_timeout")
+        _finite_positive(handshake_timeout, "handshake_timeout")
+        _finite_positive(cleanup_timeout, "cleanup_timeout")
+        self._reader = _FrameReader(reader)
+        self._writer = _FrameWriter(writer, failure_handler=self._connection_failed)
+        self._stream_writer = writer
+        self._max_pending = max_pending
+        self._default_stream_window = stream_window
+        self._allocator = StreamIdAllocator(StreamParity.ODD)
+        self._pending: dict[int, _PendingRequest] = {}
+        self._streams: dict[int, _ClientStreamRequest] = {}
+        self._terminal_streams = _TerminalStreams()
+        self._reader_task: asyncio.Task[None] | None = None
+        self._lifecycle = ConnectionLifecycle()
+        self._lifecycle.start_connecting()
+        self._local_close_started = False
+        self._close_error: MuxConnectionClosed | None = None
+        self._close_lock = asyncio.Lock()
+        self._close_task: asyncio.Task[None] | None = None
+        self._connection_sequences = SequenceTracker()
+        self._connection_receive_window = ByteCreditWindow(
+            initial_credit=connection_window,
+            maximum_credit=connection_window,
+        )
+        self._connection_send_window: AsyncByteCreditWindow | None = None
+        self._window_stalls = 0
+        self._protocol_failures = 0
+        self._heartbeat_interval = float(heartbeat_interval)
+        self._heartbeat_timeout = float(heartbeat_timeout)
+        self._handshake_timeout = float(handshake_timeout)
+        self._cleanup_timeout = float(cleanup_timeout)
+        self._heartbeat_task: asyncio.Task[None] | None = None
+        self._heartbeat_waiter: tuple[bytes, asyncio.Future[None]] | None = None
+        self._heartbeat_nonce = 0
+
+    @classmethod
+    async def connect_unix(
+        cls,
+        path: Path | str,
+        *,
+        max_pending: int = 256,
+        connection_window: int = DEFAULT_CONNECTION_WINDOW_BYTES,
+        stream_window: int = DEFAULT_STREAM_WINDOW_BYTES,
+        heartbeat_interval: float = DEFAULT_HEARTBEAT_INTERVAL_SECONDS,
+        heartbeat_timeout: float = DEFAULT_HEARTBEAT_TIMEOUT_SECONDS,
+        handshake_timeout: float = DEFAULT_HANDSHAKE_TIMEOUT_SECONDS,
+        cleanup_timeout: float = DEFAULT_CLEANUP_TIMEOUT_SECONDS,
+    ) -> MuxRpcClient:
+        _positive(max_pending, "max_pending")
+        _positive(connection_window, "connection_window")
+        _positive(stream_window, "stream_window")
+        _finite_positive(heartbeat_interval, "heartbeat_interval")
+        _finite_positive(heartbeat_timeout, "heartbeat_timeout")
+        _finite_positive(handshake_timeout, "handshake_timeout")
+        _finite_positive(cleanup_timeout, "cleanup_timeout")
+        try:
+            reader, writer = await asyncio.open_unix_connection(str(path))
+        except (ConnectionError, OSError) as exc:
+            raise MuxConnectionClosed(f"failed to connect to multiplexed daemon at {path}") from exc
+        client = cls(
+            reader,
+            writer,
+            max_pending=max_pending,
+            connection_window=connection_window,
+            stream_window=stream_window,
+            heartbeat_interval=heartbeat_interval,
+            heartbeat_timeout=heartbeat_timeout,
+            handshake_timeout=handshake_timeout,
+            cleanup_timeout=cleanup_timeout,
+        )
+        try:
+            await client._start()
+        except BaseException:
+            writer.close()
+            await _wait_closed_bounded(writer, cleanup_timeout)
+            raise
+        return client
+
+    @property
+    def pending_count(self) -> int:
+        return len(self._pending) + len(self._streams)
+
+    @property
+    def closed(self) -> bool:
+        return self._lifecycle.terminal
+
+    @property
+    def draining(self) -> bool:
+        return self._lifecycle.draining
+
+    @property
+    def state(self) -> ConnectionState:
+        return self._lifecycle.state
+
+    @property
+    def window_stalls(self) -> int:
+        return self._window_stalls
+
+    @property
+    def protocol_failures(self) -> int:
+        return self._protocol_failures
+
+    def _record_window_stall(self) -> None:
+        self._window_stalls += 1
+
+    async def request(self, method: str, params: Mapping[str, object]) -> dict[str, object]:
+        if self.closed:
+            raise self._close_error or MuxConnectionClosed("multiplexed client is closed")
+        if self.draining:
+            raise MuxConnectionClosed("multiplexed server connection is draining")
+        if not isinstance(method, str) or not method.strip():
+            raise ValueError("method must be a non-empty string")
+        if not isinstance(params, Mapping):
+            raise TypeError("params must be a mapping")
+        if self.pending_count >= self._max_pending:
+            raise MuxCapacityError(f"pending request limit is {self._max_pending}")
+
+        stream_id = self._allocator.allocate()
+        sequences = SequenceTracker()
+        future: asyncio.Future[dict[str, object]] = asyncio.get_running_loop().create_future()
+        pending = _PendingRequest(future, sequences)
+        self._pending[stream_id] = pending
+        control = encode_control_payload({"method": method, "params": dict(params)})
+        try:
+            await _write_sequenced_before_honouring_cancellation(
+                self._writer,
+                FrameType.OPEN,
+                stream_id,
+                sequences,
+                payload=control,
+            )
+            return await future
+        except asyncio.CancelledError:
+            if self._pending.pop(stream_id, None) is not None:
+                self._terminal_streams.add(stream_id, sequences)
+                await _complete_sequenced_write_after_cancellation(
+                    self._writer,
+                    FrameType.RESET,
+                    stream_id,
+                    sequences,
+                    payload=_error_payload("cancelled", "request cancelled"),
+                )
+            raise
+        except MuxConnectionClosed:
+            self._pending.pop(stream_id, None)
+            if future.done() and not future.cancelled():
+                future.exception()
+            raise
+
+    async def open_stream(
+        self,
+        method: str,
+        params: Mapping[str, object],
+        *,
+        receive_window: int | None = None,
+    ) -> MuxRpcStream:
+        if self.closed:
+            raise self._close_error or MuxConnectionClosed("multiplexed client is closed")
+        if self.draining:
+            raise MuxConnectionClosed("multiplexed server connection is draining")
+        if not isinstance(method, str) or not method.strip():
+            raise ValueError("method must be a non-empty string")
+        if not isinstance(params, Mapping):
+            raise TypeError("params must be a mapping")
+        if self.pending_count >= self._max_pending:
+            raise MuxCapacityError(f"pending request limit is {self._max_pending}")
+        window = self._default_stream_window if receive_window is None else receive_window
+        _positive(window, "receive_window")
+
+        stream_id = self._allocator.allocate()
+        sequences = SequenceTracker()
+        opened: asyncio.Future[MuxRpcStream] = asyncio.get_running_loop().create_future()
+        request = _ClientStreamRequest(sequences, window, opened)
+        self._streams[stream_id] = request
+        control = encode_control_payload(
+            {
+                "mode": "stream",
+                "method": method,
+                "params": dict(params),
+                "receive_window": window,
+            }
+        )
+        try:
+            await _write_sequenced_before_honouring_cancellation(
+                self._writer,
+                FrameType.OPEN,
+                stream_id,
+                sequences,
+                payload=control,
+            )
+            return await opened
+        except asyncio.CancelledError:
+            if self._streams.pop(stream_id, None) is not None:
+                self._terminal_streams.add(stream_id, sequences)
+                await _complete_sequenced_write_after_cancellation(
+                    self._writer,
+                    FrameType.RESET,
+                    stream_id,
+                    sequences,
+                    payload=_error_payload("cancelled", "stream open cancelled"),
+                )
+            raise
+        except MuxConnectionClosed:
+            self._streams.pop(stream_id, None)
+            if opened.done() and not opened.cancelled():
+                opened.exception()
+            raise
+
+    async def _stream_send_data(self, stream: MuxRpcStream, data: bytes) -> None:
+        await self._send_stream_data(stream, data)
+
+    async def _stream_accept(self, stream: MuxRpcStream) -> None:
+        raise RuntimeError("client-owned streams are already accepted")
+
+    async def _stream_send_eof(self, stream: MuxRpcStream) -> None:
+        await _write_sequenced_before_honouring_cancellation(
+            self._writer,
+            FrameType.EOF,
+            stream.stream_id,
+            stream._sequences,
+        )
+        request = self._streams.get(stream.stream_id)
+        if request is not None and request.stream is stream:
+            request.local_eof_sent = True
+        await self._maybe_close_stream(stream.stream_id)
+
+    async def _stream_release_credit(self, stream: MuxRpcStream, amount: int) -> None:
+        await stream._release_receive_credit(amount)
+        self._connection_receive_window.grant(amount)
+        await self._writer.write_sequenced(
+            FrameType.WINDOW_UPDATE,
+            stream.stream_id,
+            stream._sequences,
+            payload=encode_window_update(amount),
+        )
+        await self._writer.write_sequenced(
+            FrameType.WINDOW_UPDATE,
+            0,
+            self._connection_sequences,
+            payload=encode_window_update(amount),
+        )
+        await self._maybe_close_stream(stream.stream_id)
+
+    async def _stream_reset(self, stream: MuxRpcStream, message: str) -> None:
+        request = self._streams.pop(stream.stream_id, None)
+        if request is None:
+            return
+        self._terminal_streams.add(stream.stream_id, request.sequences)
+        error = MuxConnectionClosed(f"stream reset: {message}")
+        await stream._fail(error)
+        await self._writer.write_sequenced(
+            FrameType.RESET,
+            stream.stream_id,
+            request.sequences,
+            payload=_error_payload("cancelled", message),
+        )
+
+    async def close(self) -> None:
+        task = self._close_task
+        if task is None:
+            task = asyncio.create_task(
+                self._close_owned(),
+                name="hostbridge-mux-rpc-client-close",
+            )
+            task.add_done_callback(_consume_task_result)
+            self._close_task = task
+        await asyncio.shield(task)
+
+    async def _close_owned(self) -> None:
+        async with self._close_lock:
+            if self.closed:
+                await self._stop_heartbeat()
+                if self._reader_task is not None and self._reader_task is not asyncio.current_task():
+                    with suppress(MuxConnectionClosed, asyncio.CancelledError):
+                        await self._reader_task
+                return
+            self._local_close_started = True
+            if self.state is ConnectionState.READY:
+                self._lifecycle.start_draining()
+            elif self.state in {ConnectionState.CONNECTING, ConnectionState.HANDSHAKING}:
+                self._lifecycle.mark_closed()
+            await self._stop_heartbeat()
+            self._close_error = MuxConnectionClosed("multiplexed client closed")
+            pending_items = list(self._pending.items())
+            self._pending.clear()
+            stream_items = list(self._streams.items())
+            self._streams.clear()
+            for _stream_id, pending in pending_items:
+                if not pending.future.done():
+                    pending.future.set_exception(MuxConnectionClosed("multiplexed client closed"))
+            for _stream_id, request in stream_items:
+                error = MuxConnectionClosed("multiplexed client closed")
+                if request.stream is not None:
+                    await request.stream._fail(error)
+                elif not request.opened.done():
+                    request.opened.set_exception(error)
+            try:
+                async with asyncio.timeout(self._cleanup_timeout):
+                    for stream_id, pending in pending_items:
+                        with suppress(MuxRpcError, MuxProtocolError):
+                            await self._writer.write_sequenced(
+                                FrameType.RESET,
+                                stream_id,
+                                pending.sequences,
+                                payload=_error_payload("cancelled", "client closed"),
+                            )
+                    for stream_id, request in stream_items:
+                        with suppress(MuxRpcError, MuxProtocolError):
+                            await self._writer.write_sequenced(
+                                FrameType.RESET,
+                                stream_id,
+                                request.sequences,
+                                payload=_error_payload("cancelled", "client closed"),
+                            )
+                    await self._writer.write_sequenced(
+                        FrameType.GOAWAY,
+                        0,
+                        self._connection_sequences,
+                        payload=encode_control_payload({"reason": "client closed"}),
+                    )
+            except (TimeoutError, MuxRpcError, MuxProtocolError):
+                pass
+            self._stream_writer.close()
+            await _wait_closed_bounded(self._stream_writer, self._cleanup_timeout)
+            if self._reader_task is not None and self._reader_task is not asyncio.current_task():
+                with suppress(MuxConnectionClosed, asyncio.CancelledError):
+                    await self._reader_task
+            if self.state is ConnectionState.DRAINING:
+                self._lifecycle.mark_closed()
+
+    async def _start(self) -> None:
+        self._lifecycle.start_handshake()
+        try:
+            async with asyncio.timeout(self._handshake_timeout):
+                await self._handshake()
+        except TimeoutError as exc:
+            self._lifecycle.mark_failed()
+            raise MuxConnectionClosed("multiplexed client handshake timed out") from exc
+        except BaseException:
+            self._lifecycle.mark_failed()
+            raise
+        self._lifecycle.mark_ready()
+        self._reader_task = asyncio.create_task(self._read_loop(), name="hostbridge-mux-rpc-client")
+        self._heartbeat_task = asyncio.create_task(
+            self._heartbeat_loop(),
+            name="hostbridge-mux-rpc-heartbeat",
+        )
+
+    async def _handshake(self) -> None:
+        await self._writer.write_sequenced(
+            FrameType.HELLO,
+            0,
+            self._connection_sequences,
+            payload=encode_control_payload(
+                {
+                    "role": "client",
+                    "rpc": True,
+                    "connection_window": self._connection_receive_window.available,
+                }
+            ),
+        )
+        frame = await self._reader.read()
+        self._connection_sequences.accept_inbound(frame.sequence)
+        if frame.frame_type is not FrameType.HELLO_OK or frame.stream_id != 0:
+            raise MuxProtocolError("server did not complete the mux handshake")
+        hello = decode_control_payload(frame.payload)
+        if hello.get("role") != "server" or hello.get("rpc") is not True:
+            raise MuxProtocolError("server returned incompatible mux capabilities")
+        connection_window = hello.get("connection_window")
+        if not isinstance(connection_window, int) or isinstance(connection_window, bool) or connection_window <= 0:
+            raise MuxProtocolError("server returned an invalid connection window")
+        self._connection_send_window = AsyncByteCreditWindow(
+            connection_window,
+            on_stall=self._record_window_stall,
+        )
+
+    async def _read_loop(self) -> None:
+        try:
+            while True:
+                frame = await self._reader.read()
+                if frame.stream_id == 0:
+                    await self._handle_connection_frame(frame)
+                    continue
+                await self._handle_stream_frame(frame)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            await self._connection_failed(exc)
+
+    async def _handle_connection_frame(self, frame: MuxFrame) -> None:
+        self._connection_sequences.accept_inbound(frame.sequence)
+        if frame.frame_type is FrameType.WINDOW_UPDATE:
+            if self._connection_send_window is None:
+                raise MuxProtocolError("connection window update arrived before handshake")
+            try:
+                await self._connection_send_window.grant(decode_window_update(frame.payload))
+            except ValueError as exc:
+                raise MuxProtocolError("connection window credit exceeds the negotiated maximum") from exc
+            return
+        if frame.frame_type is FrameType.GOAWAY:
+            decode_control_payload(frame.payload)
+            self._lifecycle.start_draining()
+            return
+        if frame.frame_type is FrameType.PING:
+            await self._writer.write_sequenced(
+                FrameType.PONG,
+                0,
+                self._connection_sequences,
+                payload=frame.payload,
+            )
+            return
+        if frame.frame_type is FrameType.PONG:
+            waiter = self._heartbeat_waiter
+            if waiter is not None and frame.payload == waiter[0] and not waiter[1].done():
+                waiter[1].set_result(None)
+            return
+        raise MuxProtocolError(f"unexpected connection frame {frame.frame_type.name}")
+
+    async def _handle_stream_frame(self, frame: MuxFrame) -> None:
+        stream_request = self._streams.get(frame.stream_id)
+        if stream_request is not None:
+            await self._handle_client_stream_frame(frame, stream_request)
+            return
+        pending = self._pending.get(frame.stream_id)
+        if pending is None:
+            terminal = self._terminal_streams.get(frame.stream_id)
+            if terminal is None:
+                raise MuxProtocolError(f"frame for unknown stream {frame.stream_id}")
+            await self._handle_terminal_frame(frame, terminal)
+            return
+
+        pending.sequences.accept_inbound(frame.sequence)
+        if frame.frame_type is FrameType.OPEN_OK:
+            control = decode_control_payload(frame.payload)
+            result = control.get("result")
+            if not isinstance(result, dict):
+                raise MuxProtocolError("OPEN_OK response result must be an object")
+            pending.result = result
+            await self._writer.write_sequenced(
+                FrameType.CLOSE,
+                frame.stream_id,
+                pending.sequences,
+                payload=encode_control_payload({"reason": "complete"}),
+            )
+            return
+        if frame.frame_type is FrameType.CLOSE_ACK:
+            if pending.result is None:
+                raise MuxProtocolError("CLOSE_ACK arrived before OPEN_OK")
+            self._pending.pop(frame.stream_id, None)
+            self._terminal_streams.add(frame.stream_id, pending.sequences)
+            if not pending.future.done():
+                pending.future.set_result(pending.result)
+            return
+        if frame.frame_type is FrameType.RESET:
+            self._pending.pop(frame.stream_id, None)
+            self._terminal_streams.add(frame.stream_id, pending.sequences)
+            error = _remote_error(frame.payload)
+            with suppress(MuxRpcError, MuxProtocolError):
+                await self._writer.write_sequenced(
+                    FrameType.RESET,
+                    frame.stream_id,
+                    pending.sequences,
+                    payload=_error_payload("acknowledged", "remote reset acknowledged"),
+                )
+            if not pending.future.done():
+                pending.future.set_exception(error)
+            return
+        raise MuxProtocolError(f"unexpected response frame {frame.frame_type.name}")
+
+    async def _handle_client_stream_frame(self, frame: MuxFrame, request: _ClientStreamRequest) -> None:
+        request.sequences.accept_inbound(frame.sequence)
+        if frame.frame_type is FrameType.OPEN_OK:
+            if request.stream is not None:
+                raise MuxProtocolError("stream received duplicate OPEN_OK")
+            control = decode_control_payload(frame.payload)
+            send_credit = control.get("receive_window")
+            if not isinstance(send_credit, int) or isinstance(send_credit, bool) or send_credit <= 0:
+                raise MuxProtocolError("OPEN_OK contains an invalid receive window")
+            request.stream = MuxRpcStream(
+                self,
+                frame.stream_id,
+                request.sequences,
+                send_credit=send_credit,
+                receive_credit=request.receive_window,
+                open_initiator=True,
+                on_send_stall=self._record_window_stall,
+            )
+            if not request.opened.done():
+                request.opened.set_result(request.stream)
+            return
+        if frame.frame_type is FrameType.RESET:
+            self._streams.pop(frame.stream_id, None)
+            self._terminal_streams.add(frame.stream_id, request.sequences)
+            error = _remote_error(frame.payload)
+            if request.stream is not None:
+                await request.stream._fail(error)
+            elif not request.opened.done():
+                request.opened.set_exception(error)
+            with suppress(MuxRpcError, MuxProtocolError):
+                await self._writer.write_sequenced(
+                    FrameType.RESET,
+                    frame.stream_id,
+                    request.sequences,
+                    payload=_error_payload("acknowledged", "remote reset acknowledged"),
+                )
+            return
+        stream = request.stream
+        if stream is None:
+            raise MuxProtocolError(f"{frame.frame_type.name} arrived before OPEN_OK")
+        if frame.frame_type is FrameType.DATA:
+            try:
+                self._connection_receive_window.consume(len(frame.payload))
+                await stream._accept_data(frame.payload)
+            except MuxStateError as exc:
+                raise MuxProtocolError("stream DATA exceeds advertised receive credit") from exc
+            return
+        if frame.frame_type is FrameType.WINDOW_UPDATE:
+            try:
+                await stream._grant_send_credit(decode_window_update(frame.payload))
+            except ValueError as exc:
+                raise MuxProtocolError("stream window credit exceeds the negotiated maximum") from exc
+            return
+        if frame.frame_type is FrameType.EOF:
+            await stream._accept_eof()
+            await self._maybe_close_stream(frame.stream_id)
+            return
+        if frame.frame_type is FrameType.CLOSE_ACK:
+            if not stream.close_sent:
+                raise MuxProtocolError("CLOSE_ACK arrived before CLOSE")
+            control = decode_control_payload(frame.payload)
+            result = control.get("result")
+            if not isinstance(result, dict):
+                raise MuxProtocolError("CLOSE_ACK result must be an object")
+            self._streams.pop(frame.stream_id, None)
+            self._terminal_streams.add(frame.stream_id, request.sequences)
+            await stream._finish(result)
+            return
+        raise MuxProtocolError(f"unexpected stream frame {frame.frame_type.name}")
+
+    async def _handle_terminal_frame(self, frame: MuxFrame, terminal: _TerminalStream) -> None:
+        terminal.sequences.accept_inbound(frame.sequence)
+        if frame.frame_type is FrameType.DATA:
+            await self._discard_late_data(frame)
+            return
+        if frame.frame_type is FrameType.WINDOW_UPDATE:
+            decode_window_update(frame.payload)
+            return
+        if frame.frame_type in {
+            FrameType.OPEN_OK,
+            FrameType.EOF,
+            FrameType.CLOSE,
+            FrameType.CLOSE_ACK,
+            FrameType.RESET,
+        }:
+            return
+        raise MuxProtocolError(f"unexpected late frame {frame.frame_type.name}")
+
+    async def _discard_late_data(self, frame: MuxFrame) -> None:
+        try:
+            self._connection_receive_window.consume(len(frame.payload))
+            self._connection_receive_window.grant(len(frame.payload))
+        except MuxStateError as exc:
+            raise MuxProtocolError("late stream DATA exceeds connection credit") from exc
+        await self._writer.write_sequenced(
+            FrameType.WINDOW_UPDATE,
+            0,
+            self._connection_sequences,
+            payload=encode_window_update(len(frame.payload)),
+        )
+
+    async def _send_stream_data(self, stream: MuxRpcStream, data: bytes) -> None:
+        connection_window = self._connection_send_window
+        if connection_window is None:
+            raise MuxConnectionClosed("connection send window is unavailable")
+        chunk_size = min(
+            DEFAULT_DATA_CHUNK_BYTES,
+            MAX_FRAME_PAYLOAD_BYTES,
+            stream._send_window.maximum,
+            connection_window.maximum,
+        )
+        for offset in range(0, len(data), chunk_size):
+            chunk = data[offset : offset + chunk_size]
+            await stream._send_window.acquire(len(chunk))
+            try:
+                await connection_window.acquire(len(chunk))
+            except BaseException:
+                await stream._send_window.grant(len(chunk))
+                raise
+            try:
+                await _write_sequenced_before_honouring_cancellation(
+                    self._writer,
+                    FrameType.DATA,
+                    stream.stream_id,
+                    stream._sequences,
+                    payload=chunk,
+                )
+            except MuxCapacityError as exc:
+                await connection_window.grant(len(chunk))
+                await stream._send_window.grant(len(chunk))
+                await self._resource_limit_stream(stream, exc)
+                raise
+
+    async def _resource_limit_stream(self, stream: MuxRpcStream, error: MuxCapacityError) -> None:
+        request = self._streams.pop(stream.stream_id, None)
+        if request is None:
+            return
+        self._terminal_streams.add(stream.stream_id, request.sequences)
+        await stream._fail(error)
+        await self._writer.write_sequenced(
+            FrameType.RESET,
+            stream.stream_id,
+            request.sequences,
+            payload=_error_payload("resource_limit", str(error), retryable=True),
+        )
+
+    async def _maybe_close_stream(self, stream_id: int) -> None:
+        request = self._streams.get(stream_id)
+        if request is None or request.stream is None or request.stream.close_sent:
+            return
+        if (
+            not request.local_eof_sent
+            or not request.stream.local_eof
+            or not request.stream.remote_eof
+            or request.stream.buffered_bytes != 0
+        ):
+            return
+        request.stream._send_close()
+        await self._writer.write_sequenced(
+            FrameType.CLOSE,
+            stream_id,
+            request.sequences,
+            payload=encode_control_payload({"reason": "complete"}),
+        )
+
+    async def _connection_failed(self, cause: BaseException) -> None:
+        if self.closed:
+            return
+        if self._local_close_started:
+            if self.state is ConnectionState.DRAINING:
+                self._lifecycle.mark_closed()
+            return
+        if isinstance(cause, MuxProtocolError):
+            self._protocol_failures += 1
+        clean_drain = self.draining and not self._pending and not self._streams
+        if clean_drain:
+            self._lifecycle.mark_closed()
+        else:
+            self._lifecycle.mark_failed()
+        await self._stop_heartbeat()
+        error = MuxConnectionClosed(str(cause) or "multiplexed connection failed")
+        self._close_error = error
+        pending = list(self._pending.values())
+        self._pending.clear()
+        streams = list(self._streams.values())
+        self._streams.clear()
+        self._terminal_streams.clear()
+        for pending_request in pending:
+            if not pending_request.future.done():
+                pending_request.future.set_exception(error)
+        for stream_request in streams:
+            if stream_request.stream is not None:
+                await stream_request.stream._fail(error)
+            elif not stream_request.opened.done():
+                stream_request.opened.set_exception(error)
+        if self._connection_send_window is not None:
+            await self._connection_send_window.close(error)
+        self._stream_writer.close()
+        await _wait_closed_bounded(self._stream_writer, self._cleanup_timeout)
+
+    async def _heartbeat_loop(self) -> None:
+        try:
+            while True:
+                await asyncio.sleep(self._heartbeat_interval)
+                if self.closed:
+                    return
+                self._heartbeat_nonce = (self._heartbeat_nonce + 1) & 0xFFFFFFFFFFFFFFFF
+                payload = self._heartbeat_nonce.to_bytes(8, "big")
+                acknowledged = asyncio.get_running_loop().create_future()
+                self._heartbeat_waiter = (payload, acknowledged)
+                try:
+                    await self._writer.write_sequenced(
+                        FrameType.PING,
+                        0,
+                        self._connection_sequences,
+                        payload=payload,
+                    )
+                    async with asyncio.timeout(self._heartbeat_timeout):
+                        await acknowledged
+                except TimeoutError:
+                    await self._connection_failed(MuxConnectionClosed("multiplexed heartbeat timed out"))
+                    return
+                finally:
+                    if self._heartbeat_waiter is not None and self._heartbeat_waiter[1] is acknowledged:
+                        self._heartbeat_waiter = None
+        except asyncio.CancelledError:
+            raise
+        except (MuxConnectionClosed, MuxProtocolError, OSError) as exc:
+            await self._connection_failed(exc)
+
+    async def _stop_heartbeat(self) -> None:
+        heartbeat = self._heartbeat_task
+        if heartbeat is None or heartbeat is asyncio.current_task():
+            return
+        self._heartbeat_task = None
+        heartbeat.cancel()
+        await asyncio.gather(heartbeat, return_exceptions=True)
+
+
+@dataclass(slots=True)
+class _ServerRequest:
+    sequences: SequenceTracker
+    method: str | None = None
+    task: asyncio.Task[None] | None = None
+    response_sent: bool = False
+    reset_sent: bool = False
+    stream: MuxRpcStream | None = None
+    stream_result: dict[str, object] | None = None
+
+
+class MuxRpcServerConnection:
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        handler: MuxRpcHandler,
+        *,
+        max_handlers: int,
+        stream_handler: MuxRpcStreamHandler | None,
+        request_closed_handler: MuxRpcRequestClosedHandler | None,
+        connection_window: int,
+        stream_window: int,
+        handshake_timeout: float = DEFAULT_HANDSHAKE_TIMEOUT_SECONDS,
+        cleanup_timeout: float = DEFAULT_CLEANUP_TIMEOUT_SECONDS,
+    ) -> None:
+        _positive(max_handlers, "max_handlers")
+        _positive(connection_window, "connection_window")
+        _positive(stream_window, "stream_window")
+        _finite_positive(handshake_timeout, "handshake_timeout")
+        _finite_positive(cleanup_timeout, "cleanup_timeout")
+        self._reader = _FrameReader(reader)
+        self._writer = _FrameWriter(writer, failure_handler=self._writer_failed)
+        self._stream_writer = writer
+        self._handler = handler
+        self._stream_handler = stream_handler
+        self._request_closed_handler = request_closed_handler
+        self._max_handlers = max_handlers
+        self._default_stream_window = stream_window
+        self._requests: dict[int, _ServerRequest] = {}
+        self._terminal_streams = _TerminalStreams()
+        self._connection_sequences = SequenceTracker()
+        self._connection_receive_window = ByteCreditWindow(
+            initial_credit=connection_window,
+            maximum_credit=connection_window,
+        )
+        self._connection_send_window: AsyncByteCreditWindow | None = None
+        self._window_stalls = 0
+        self._protocol_failures = 0
+        self._lifecycle = ConnectionLifecycle()
+        self._lifecycle.start_connecting()
+        self._drain_requested = False
+        self._goaway_sent = False
+        self._ready = asyncio.Event()
+        self._handshake_timeout = float(handshake_timeout)
+        self._cleanup_timeout = float(cleanup_timeout)
+
+    @property
+    def active_requests(self) -> int:
+        return len(self._requests)
+
+    @property
+    def window_stalls(self) -> int:
+        return self._window_stalls
+
+    @property
+    def protocol_failures(self) -> int:
+        return self._protocol_failures
+
+    @property
+    def state(self) -> ConnectionState:
+        return self._lifecycle.state
+
+    def _record_window_stall(self) -> None:
+        self._window_stalls += 1
+
+    async def _writer_failed(self, _cause: BaseException) -> None:
+        self._stream_writer.close()
+
+    async def start_draining(self, reason: str = "server shutting down") -> None:
+        if self._lifecycle.terminal:
+            return
+        self._drain_requested = True
+        await self._ready.wait()
+        if self._lifecycle.terminal or self._goaway_sent:
+            return
+        self._lifecycle.start_draining()
+        self._goaway_sent = True
+        await self._writer.write_sequenced(
+            FrameType.GOAWAY,
+            0,
+            self._connection_sequences,
+            payload=encode_control_payload({"reason": reason}),
+        )
+        if not self._requests:
+            self._stream_writer.close()
+
+    async def serve(self) -> None:
+        try:
+            self._lifecycle.start_handshake()
+            try:
+                async with asyncio.timeout(self._handshake_timeout):
+                    await self._handshake()
+            except TimeoutError:
+                self._lifecycle.mark_failed()
+                return
+            self._lifecycle.mark_ready()
+            if self._drain_requested:
+                self._lifecycle.start_draining()
+            self._ready.set()
+            while True:
+                frame = await self._reader.read()
+                if frame.stream_id == 0:
+                    if await self._handle_connection_frame(frame):
+                        return
+                else:
+                    await self._handle_stream_frame(frame)
+                if self._lifecycle.draining and not self._requests:
+                    return
+        except (MuxConnectionClosed, MuxProtocolError, OSError) as exc:
+            if isinstance(exc, MuxProtocolError):
+                self._protocol_failures += 1
+            self._lifecycle.mark_failed()
+            return
+        finally:
+            self._ready.set()
+            tasks = [request.task for request in self._requests.values() if request.task is not None]
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+            error = MuxConnectionClosed("multiplexed server connection closed")
+            for request in self._requests.values():
+                if request.stream is not None:
+                    await request.stream._fail(error)
+            if self._connection_send_window is not None:
+                await self._connection_send_window.close(error)
+            self._requests.clear()
+            self._terminal_streams.clear()
+            self._stream_writer.close()
+            await _wait_closed_bounded(self._stream_writer, self._cleanup_timeout)
+            if self.state is ConnectionState.DRAINING:
+                self._lifecycle.mark_closed()
+            elif not self._lifecycle.terminal:
+                self._lifecycle.mark_failed()
+
+    async def _handshake(self) -> None:
+        frame = await self._reader.read()
+        self._connection_sequences.accept_inbound(frame.sequence)
+        if frame.frame_type is not FrameType.HELLO or frame.stream_id != 0:
+            raise MuxProtocolError("client did not start with HELLO")
+        hello = decode_control_payload(frame.payload)
+        if hello.get("role") != "client" or hello.get("rpc") is not True:
+            raise MuxProtocolError("client offered incompatible mux capabilities")
+        connection_window = hello.get("connection_window")
+        if not isinstance(connection_window, int) or isinstance(connection_window, bool) or connection_window <= 0:
+            raise MuxProtocolError("client offered an invalid connection window")
+        self._connection_send_window = AsyncByteCreditWindow(
+            connection_window,
+            on_stall=self._record_window_stall,
+        )
+        await self._writer.write_sequenced(
+            FrameType.HELLO_OK,
+            0,
+            self._connection_sequences,
+            payload=encode_control_payload(
+                {
+                    "role": "server",
+                    "rpc": True,
+                    "connection_window": self._connection_receive_window.available,
+                }
+            ),
+        )
+
+    async def _handle_connection_frame(self, frame: MuxFrame) -> bool:
+        self._connection_sequences.accept_inbound(frame.sequence)
+        if frame.frame_type is FrameType.WINDOW_UPDATE:
+            if self._connection_send_window is None:
+                raise MuxProtocolError("connection window update arrived before handshake")
+            try:
+                await self._connection_send_window.grant(decode_window_update(frame.payload))
+            except ValueError as exc:
+                raise MuxProtocolError("connection window credit exceeds the negotiated maximum") from exc
+            return False
+        if frame.frame_type is FrameType.GOAWAY:
+            self._lifecycle.start_draining()
+            return True
+        if frame.frame_type is FrameType.PING:
+            await self._writer.write_sequenced(
+                FrameType.PONG,
+                0,
+                self._connection_sequences,
+                payload=frame.payload,
+            )
+            return False
+        if frame.frame_type is FrameType.PONG:
+            return False
+        raise MuxProtocolError(f"unexpected connection frame {frame.frame_type.name}")
+
+    async def _handle_stream_frame(self, frame: MuxFrame) -> None:
+        request = self._requests.get(frame.stream_id)
+        if frame.frame_type is FrameType.OPEN:
+            if (
+                request is not None
+                or self._terminal_streams.get(frame.stream_id) is not None
+                or frame.stream_id % 2 != int(StreamParity.ODD)
+            ):
+                raise MuxProtocolError(f"invalid or reused client stream {frame.stream_id}")
+            request = _ServerRequest(SequenceTracker())
+            request.sequences.accept_inbound(frame.sequence)
+            self._requests[frame.stream_id] = request
+            if self._drain_requested or self._lifecycle.draining:
+                await self._send_failure(
+                    frame.stream_id,
+                    request,
+                    MuxRpcFailure("connection_lost", "multiplexed server connection is draining", retryable=True),
+                )
+                return
+            control = decode_control_payload(frame.payload)
+            mode = control.get("mode", "unary")
+            method = control.get("method")
+            params = control.get("params")
+            if not isinstance(method, str) or not method.strip() or not isinstance(params, dict):
+                await self._send_failure(frame.stream_id, request, MuxRpcFailure("invalid_request", "invalid RPC"))
+                return
+            request.method = method
+            active_handlers = sum(item.task is not None and not item.task.done() for item in self._requests.values())
+            if active_handlers >= self._max_handlers:
+                await self._send_failure(
+                    frame.stream_id,
+                    request,
+                    MuxRpcFailure("busy", "server handler capacity is exhausted", retryable=True),
+                )
+                return
+            if mode == "stream":
+                receive_window = control.get("receive_window")
+                if (
+                    self._stream_handler is None
+                    or not isinstance(receive_window, int)
+                    or isinstance(receive_window, bool)
+                    or receive_window <= 0
+                ):
+                    await self._send_failure(
+                        frame.stream_id,
+                        request,
+                        MuxRpcFailure("invalid_request", "streaming RPC is unavailable or invalid"),
+                    )
+                    return
+                request.stream = MuxRpcStream(
+                    self,
+                    frame.stream_id,
+                    request.sequences,
+                    send_credit=receive_window,
+                    receive_credit=self._default_stream_window,
+                    open_initiator=False,
+                    result_expected=False,
+                    accepted=False,
+                    on_send_stall=self._record_window_stall,
+                )
+                request.task = asyncio.create_task(
+                    self._run_stream_handler(frame.stream_id, request, method, params),
+                    name=f"hostbridge-mux-stream-{frame.stream_id}",
+                )
+                return
+            if mode != "unary":
+                await self._send_failure(
+                    frame.stream_id,
+                    request,
+                    MuxRpcFailure("invalid_request", "unsupported RPC mode"),
+                )
+                return
+            request.task = asyncio.create_task(
+                self._run_handler(frame.stream_id, request, method, params),
+                name=f"hostbridge-mux-rpc-{frame.stream_id}",
+            )
+            return
+        if request is None:
+            terminal = self._terminal_streams.get(frame.stream_id)
+            if terminal is not None:
+                await self._handle_terminal_frame(frame, terminal)
+                return
+            raise MuxProtocolError(f"frame for unknown stream {frame.stream_id}")
+
+        request.sequences.accept_inbound(frame.sequence)
+        if request.stream is not None:
+            if not request.response_sent and frame.frame_type is not FrameType.RESET:
+                raise MuxProtocolError(f"{frame.frame_type.name} arrived before stream acceptance")
+            if frame.frame_type is FrameType.DATA:
+                try:
+                    self._connection_receive_window.consume(len(frame.payload))
+                    await request.stream._accept_data(frame.payload)
+                except MuxStateError as exc:
+                    raise MuxProtocolError("stream DATA exceeds advertised receive credit") from exc
+                return
+            if frame.frame_type is FrameType.WINDOW_UPDATE:
+                try:
+                    await request.stream._grant_send_credit(decode_window_update(frame.payload))
+                except ValueError as exc:
+                    raise MuxProtocolError("stream window credit exceeds the negotiated maximum") from exc
+                return
+            if frame.frame_type is FrameType.EOF:
+                await request.stream._accept_eof()
+                return
+        if frame.frame_type is FrameType.CLOSE:
+            if not request.response_sent:
+                raise MuxProtocolError("CLOSE arrived before OPEN_OK")
+            if request.stream is not None:
+                try:
+                    request.stream._receive_close()
+                except MuxStateError as exc:
+                    raise MuxProtocolError("stream CLOSE arrived before both EOF") from exc
+                if request.stream_result is None:
+                    return
+                await self._acknowledge_stream_close(frame.stream_id, request)
+                return
+            await self._writer.write_sequenced(
+                FrameType.CLOSE_ACK,
+                frame.stream_id,
+                request.sequences,
+                payload=b"",
+            )
+            self._retire_request(frame.stream_id, request)
+            if self._request_closed_handler is not None and request.method is not None:
+                await self._request_closed_handler(request.method)
+            return
+        if frame.frame_type is FrameType.RESET:
+            if request.task is not None and not request.task.done():
+                request.task.cancel()
+            if not request.reset_sent:
+                request.reset_sent = True
+                await self._writer.write_sequenced(
+                    FrameType.RESET,
+                    frame.stream_id,
+                    request.sequences,
+                    payload=_error_payload("cancelled", "request cancelled"),
+                )
+            if request.stream is not None:
+                await request.stream._fail(MuxConnectionClosed("stream reset by peer"))
+            self._retire_request(frame.stream_id, request)
+            return
+        raise MuxProtocolError(f"unexpected request frame {frame.frame_type.name}")
+
+    async def _handle_terminal_frame(self, frame: MuxFrame, terminal: _TerminalStream) -> None:
+        terminal.sequences.accept_inbound(frame.sequence)
+        if frame.frame_type is FrameType.DATA:
+            await self._discard_late_data(frame)
+            return
+        if frame.frame_type is FrameType.WINDOW_UPDATE:
+            decode_window_update(frame.payload)
+            return
+        if frame.frame_type in {
+            FrameType.EOF,
+            FrameType.CLOSE,
+            FrameType.CLOSE_ACK,
+            FrameType.RESET,
+        }:
+            return
+        raise MuxProtocolError(f"unexpected late frame {frame.frame_type.name}")
+
+    async def _discard_late_data(self, frame: MuxFrame) -> None:
+        try:
+            self._connection_receive_window.consume(len(frame.payload))
+            self._connection_receive_window.grant(len(frame.payload))
+        except MuxStateError as exc:
+            raise MuxProtocolError("late stream DATA exceeds connection credit") from exc
+        await self._writer.write_sequenced(
+            FrameType.WINDOW_UPDATE,
+            0,
+            self._connection_sequences,
+            payload=encode_window_update(len(frame.payload)),
+        )
+
+    def _retire_request(self, stream_id: int, request: _ServerRequest) -> None:
+        self._terminal_streams.add(stream_id, request.sequences)
+        self._requests.pop(stream_id, None)
+
+    async def _run_handler(
+        self,
+        stream_id: int,
+        request: _ServerRequest,
+        method: str,
+        params: dict[str, object],
+    ) -> None:
+        try:
+            result = await self._handler(method, params)
+            if not isinstance(result, dict):
+                raise MuxRpcFailure("internal", "RPC handler returned a non-object result")
+            if self._requests.get(stream_id) is not request:
+                return
+            await self._writer.write_sequenced(
+                FrameType.OPEN_OK,
+                stream_id,
+                request.sequences,
+                payload=encode_control_payload({"result": result}),
+            )
+            request.response_sent = True
+        except asyncio.CancelledError:
+            raise
+        except MuxRpcFailure as exc:
+            if self._requests.get(stream_id) is request:
+                await self._send_failure(stream_id, request, exc)
+        except Exception:
+            if self._requests.get(stream_id) is request:
+                await self._send_failure(
+                    stream_id,
+                    request,
+                    MuxRpcFailure("internal", "internal HostBridge error", retryable=True),
+                )
+
+    async def _run_stream_handler(
+        self,
+        stream_id: int,
+        request: _ServerRequest,
+        method: str,
+        params: dict[str, object],
+    ) -> None:
+        stream = request.stream
+        handler = self._stream_handler
+        try:
+            if stream is None or handler is None:
+                raise MuxRpcFailure("internal", "stream handler state is unavailable")
+            result = await handler(method, params, stream)
+            if not isinstance(result, dict):
+                raise MuxRpcFailure("internal", "stream handler returned a non-object result")
+            if not stream.accepted:
+                raise MuxRpcFailure("internal", "stream handler returned before accepting the stream")
+            if self._requests.get(stream_id) is not request:
+                return
+            request.stream_result = result
+            await stream.send_eof()
+            if stream.close_received and self._requests.get(stream_id) is request:
+                await self._acknowledge_stream_close(stream_id, request)
+        except asyncio.CancelledError:
+            raise
+        except MuxRpcFailure as exc:
+            if self._requests.get(stream_id) is request:
+                await self._send_failure(stream_id, request, exc)
+                if stream is not None:
+                    await stream._fail(MuxConnectionClosed(f"stream reset: {exc}"))
+        except Exception:
+            if self._requests.get(stream_id) is request:
+                await self._send_failure(
+                    stream_id,
+                    request,
+                    MuxRpcFailure("internal", "internal HostBridge error", retryable=True),
+                )
+                if stream is not None:
+                    await stream._fail(MuxConnectionClosed("stream handler failed"))
+
+    async def _stream_send_data(self, stream: MuxRpcStream, data: bytes) -> None:
+        await self._send_stream_data(stream, data)
+
+    async def _acknowledge_stream_close(self, stream_id: int, request: _ServerRequest) -> None:
+        stream = request.stream
+        result = request.stream_result
+        if stream is None or result is None:
+            raise MuxProtocolError("stream CLOSE acknowledgement is missing terminal state")
+        await self._writer.write_sequenced(
+            FrameType.CLOSE_ACK,
+            stream_id,
+            request.sequences,
+            payload=encode_control_payload({"result": result}),
+        )
+        await stream._finish(result)
+        self._retire_request(stream_id, request)
+        if self._request_closed_handler is not None and request.method is not None:
+            await self._request_closed_handler(request.method)
+
+    async def _stream_accept(self, stream: MuxRpcStream) -> None:
+        request = self._requests.get(stream.stream_id)
+        if request is None or request.stream is not stream:
+            raise MuxConnectionClosed("stream request is no longer active")
+        if request.response_sent:
+            return
+        await self._writer.write_sequenced(
+            FrameType.OPEN_OK,
+            stream.stream_id,
+            request.sequences,
+            payload=encode_control_payload({"stream": True, "receive_window": self._default_stream_window}),
+        )
+        request.response_sent = True
+
+    async def _stream_send_eof(self, stream: MuxRpcStream) -> None:
+        await _write_sequenced_before_honouring_cancellation(
+            self._writer,
+            FrameType.EOF,
+            stream.stream_id,
+            stream._sequences,
+        )
+
+    async def _stream_release_credit(self, stream: MuxRpcStream, amount: int) -> None:
+        await stream._release_receive_credit(amount)
+        self._connection_receive_window.grant(amount)
+        await self._writer.write_sequenced(
+            FrameType.WINDOW_UPDATE,
+            stream.stream_id,
+            stream._sequences,
+            payload=encode_window_update(amount),
+        )
+        await self._writer.write_sequenced(
+            FrameType.WINDOW_UPDATE,
+            0,
+            self._connection_sequences,
+            payload=encode_window_update(amount),
+        )
+
+    async def _stream_reset(self, stream: MuxRpcStream, message: str) -> None:
+        request = self._requests.get(stream.stream_id)
+        if request is None:
+            return
+        if request.task is not None and request.task is not asyncio.current_task():
+            request.task.cancel()
+        request.reset_sent = True
+        await stream._fail(MuxConnectionClosed(f"stream reset: {message}"))
+        await self._writer.write_sequenced(
+            FrameType.RESET,
+            stream.stream_id,
+            request.sequences,
+            payload=_error_payload("cancelled", message),
+        )
+
+    async def _send_stream_data(self, stream: MuxRpcStream, data: bytes) -> None:
+        connection_window = self._connection_send_window
+        if connection_window is None:
+            raise MuxConnectionClosed("connection send window is unavailable")
+        chunk_size = min(
+            DEFAULT_DATA_CHUNK_BYTES,
+            MAX_FRAME_PAYLOAD_BYTES,
+            stream._send_window.maximum,
+            connection_window.maximum,
+        )
+        for offset in range(0, len(data), chunk_size):
+            chunk = data[offset : offset + chunk_size]
+            await stream._send_window.acquire(len(chunk))
+            try:
+                await connection_window.acquire(len(chunk))
+            except BaseException:
+                await stream._send_window.grant(len(chunk))
+                raise
+            try:
+                await _write_sequenced_before_honouring_cancellation(
+                    self._writer,
+                    FrameType.DATA,
+                    stream.stream_id,
+                    stream._sequences,
+                    payload=chunk,
+                )
+            except MuxCapacityError as exc:
+                await connection_window.grant(len(chunk))
+                await stream._send_window.grant(len(chunk))
+                await self._resource_limit_stream(stream, exc)
+                raise
+
+    async def _resource_limit_stream(self, stream: MuxRpcStream, error: MuxCapacityError) -> None:
+        request = self._requests.get(stream.stream_id)
+        if request is None:
+            return
+        if request.task is not None and request.task is not asyncio.current_task():
+            request.task.cancel()
+        request.reset_sent = True
+        await stream._fail(error)
+        self._retire_request(stream.stream_id, request)
+        await self._writer.write_sequenced(
+            FrameType.RESET,
+            stream.stream_id,
+            request.sequences,
+            payload=_error_payload("resource_limit", str(error), retryable=True),
+        )
+
+    async def _send_failure(self, stream_id: int, request: _ServerRequest, error: MuxRpcFailure) -> None:
+        request.reset_sent = True
+        await self._writer.write_sequenced(
+            FrameType.RESET,
+            stream_id,
+            request.sequences,
+            payload=_error_payload(error.code, str(error), retryable=error.retryable, details=error.details),
+        )
+
+
+async def serve_mux_rpc(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    handler: MuxRpcHandler,
+    *,
+    max_handlers: int = 256,
+    stream_handler: MuxRpcStreamHandler | None = None,
+    request_closed_handler: MuxRpcRequestClosedHandler | None = None,
+    connection_window: int = DEFAULT_CONNECTION_WINDOW_BYTES,
+    stream_window: int = DEFAULT_STREAM_WINDOW_BYTES,
+    handshake_timeout: float = DEFAULT_HANDSHAKE_TIMEOUT_SECONDS,
+    cleanup_timeout: float = DEFAULT_CLEANUP_TIMEOUT_SECONDS,
+) -> None:
+    connection = MuxRpcServerConnection(
+        reader,
+        writer,
+        handler,
+        max_handlers=max_handlers,
+        stream_handler=stream_handler,
+        request_closed_handler=request_closed_handler,
+        connection_window=connection_window,
+        stream_window=stream_window,
+        handshake_timeout=handshake_timeout,
+        cleanup_timeout=cleanup_timeout,
+    )
+    await connection.serve()
+
+
+async def _wait_closed_bounded(writer: asyncio.StreamWriter, timeout: float) -> None:
+    try:
+        async with asyncio.timeout(timeout):
+            await writer.wait_closed()
+    except Exception:
+        return
+
+
+def _consume_task_result(task: asyncio.Task[None]) -> None:
+    with suppress(BaseException):
+        task.result()
+
+
+async def _complete_sequenced_write_after_cancellation(
+    writer: _FrameWriter,
+    frame_type: FrameType,
+    stream_id: int,
+    sequences: SequenceTracker,
+    *,
+    flags: int = 0,
+    payload: bytes = b"",
+) -> None:
+    task = asyncio.create_task(
+        writer.write_sequenced(
+            frame_type,
+            stream_id,
+            sequences,
+            flags=flags,
+            payload=payload,
+        )
+    )
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            continue
+    with suppress(MuxRpcError):
+        task.result()
+
+
+async def _write_sequenced_before_honouring_cancellation(
+    writer: _FrameWriter,
+    frame_type: FrameType,
+    stream_id: int,
+    sequences: SequenceTracker,
+    *,
+    flags: int = 0,
+    payload: bytes = b"",
+) -> None:
+    task = asyncio.create_task(
+        writer.write_sequenced(
+            frame_type,
+            stream_id,
+            sequences,
+            flags=flags,
+            payload=payload,
+        )
+    )
+    cancellation: asyncio.CancelledError | None = None
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError as exc:
+            cancellation = exc
+    task.result()
+    if cancellation is not None:
+        raise cancellation
+
+
+def _error_payload(
+    code: str,
+    message: str,
+    *,
+    retryable: bool = False,
+    details: dict[str, object] | None = None,
+) -> bytes:
+    return encode_control_payload(
+        {
+            "code": code,
+            "message": message,
+            "retryable": retryable,
+            "details": details or {},
+        }
+    )
+
+
+def _remote_error(payload: bytes) -> MuxRemoteError:
+    control = decode_control_payload(payload)
+    code = control.get("code")
+    message = control.get("message")
+    retryable = control.get("retryable", False)
+    details = control.get("details", {})
+    if (
+        not isinstance(code, str)
+        or not code
+        or not isinstance(message, str)
+        or not isinstance(retryable, bool)
+        or not isinstance(details, dict)
+    ):
+        raise MuxProtocolError("RESET contains an invalid structured error")
+    return MuxRemoteError(code, message, retryable=retryable, details=details)
+
+
+def _positive(value: int, name: str) -> None:
+    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+        raise ValueError(f"{name} must be a positive integer")
+
+
+def _finite_positive(value: float, name: str) -> None:
+    if not isinstance(value, int | float) or isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be a finite positive number")