lab-sync-driver-sdk 0.3.0__py3-none-any.whl

lab_sync_driver_sdk/host.py

@@ -0,0 +1,696 @@
+"""Host runtime: serve a Device over the stdio driver protocol.
+
+The driver runs as an out-of-process child; the supervisor speaks to it over the
+child's stdin (requests) and stdout (frames). stdout is the protocol channel and
+nothing else may write to it, so the host claims the real fd 1 for framing and
+points `sys.stdout` at stderr -- any stray print from device code lands on the
+log channel, not mid-frame. Generates Describe from the driver's decorators and
+drives the decorated method on Execute, streaming progress. A command method may
+declare a `progress` parameter; the host injects an async reporter
+`progress(fraction, message)`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import json
+import logging
+import math
+import os
+import sys
+import time
+from collections.abc import Mapping
+from collections.abc import Sequence
+from concurrent.futures import ThreadPoolExecutor
+from enum import Enum
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import BinaryIO
+from typing import Protocol
+from typing import cast
+
+from lab_sync_driver_protocol import PROTOCOL_VERSION
+
+from lab_sync_driver_sdk.decorators import CommandMeta
+from lab_sync_driver_sdk.decorators import OutputValidationError
+from lab_sync_driver_sdk.decorators import TelemetryMeta
+from lab_sync_driver_sdk.decorators import param_dict
+from lab_sync_driver_sdk.decorators import validate_outputs
+from lab_sync_driver_sdk.settings_binding import bind_settings
+from lab_sync_driver_sdk.settings_binding import binds_settings
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable
+    from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+
+class Hostable(Protocol):
+    """Define what the host needs from a servable target.
+
+    Both an SDK `Device` and the lab-device-sdk adapter satisfy this
+    structurally, so one servicer hosts both.
+    """
+
+    device_type_id: str
+    manufacturer: str
+    model: str
+
+    # Gradual on purpose: `connect` takes nothing, the settings dict, or -- when it
+    # is itself the `@settings` method -- one parameter per setting.
+    async def connect(self, *args: Any, **kwargs: Any) -> None: ...  # noqa: ANN401
+
+    def command_specs(self) -> dict[str, tuple[str, CommandMeta]]: ...
+
+
+def _command_dict(meta: CommandMeta) -> dict[str, object]:
+    """One command's wire entry; optional fields are omitted when unset."""
+    entry: dict[str, object] = {
+        "name": meta.name,
+        "description": meta.description,
+        "inputs": [param_dict(p) for p in meta.inputs],
+        "outputs": [{"name": p.name, "description": p.description, "type": p.type} for p in meta.outputs],
+        "exclusive": meta.exclusive,
+        "concurrent": meta.concurrent,
+    }
+    if meta.category:
+        entry["category"] = meta.category
+    if not meta.operator_visible:
+        entry["operator_visible"] = False
+    if meta.default_sim_sec is not None:
+        entry["default_sim_sec"] = meta.default_sim_sec
+    if meta.operation_phase:
+        entry["operation_phase"] = meta.operation_phase
+    if meta.handles_simulation:
+        entry["handles_simulation"] = True
+    return entry
+
+
+def _declared_metadata(device: Hostable) -> dict[str, object]:
+    """The device's optional self-description: identity text and physical envelope.
+
+    Every field is omitted when unset, so a driver that declares none of them describes byte-for-byte as it did before these fields existed.
+    """
+    out: dict[str, object] = {}
+    for field_name in (
+        "category",
+        "description",
+        "agent_context",
+        "integration_mode",
+        "model_path",
+        "top_view_image_path",
+    ):
+        raw = getattr(device, field_name, "")
+        # `agent_context` is commonly a method that reads a file next to the driver.
+        resolved = raw() if callable(raw) else raw
+        # A plain `(str, Enum)` stringifies to "DeviceCategory.PLATE_HANDLING",
+        # not to its value -- and only `lab_sync_driver_sdk`'s own DeviceCategory is a
+        # StrEnum. lab-device-sdk's is not, so a driver using it would describe a
+        # category nothing downstream matches (consumers look for the value).
+        value = str(resolved.value or "") if isinstance(resolved, Enum) else str(resolved or "")
+        if value:
+            out[field_name] = value
+    for axis in ("width_mm", "depth_mm", "height_mm"):
+        extent = getattr(device, axis, None)
+        if extent is not None:
+            out[axis] = float(cast("float", extent))
+    return out
+
+
+def valid_duration(value: object) -> float | None:
+    """A duration estimate as seconds, or None when it is not a finite, non-negative number.
+
+    Booleans and numeric strings are refused rather than coerced, and so is
+    infinity: it is not valid JSON on the wire, and paced out it would never end.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    seconds = float(value)
+    return seconds if math.isfinite(seconds) and seconds >= 0 else None
+
+
+def _nest_offset(raw: object) -> dict[str, float] | None:
+    """Normalize one nest's declared offset onto the wire, or None when unset.
+
+    A driver may write the offset as an `(x, y, z)` sequence or as a mapping
+    with any subset of those keys; both land on the wire as a full
+    `{"x": .., "y": .., "z": ..}` object so the supervisor never has to guess a
+    missing axis. Anything unreadable — a string, a short sequence, a
+    non-numeric entry — reads as "no position declared" rather than failing the
+    whole describe, matching how `_dimension` treats a bad extent.
+    """
+    if raw is None:
+        return None
+    axes: tuple[str, str, str] = ("x", "y", "z")
+    values: list[float] = []
+    if isinstance(raw, Mapping):
+        source: list[object] = [cast("Mapping[str, object]", raw).get(axis, 0.0) for axis in axes]
+    elif isinstance(raw, Sequence) and not isinstance(raw, (str, bytes)):
+        packed = list(cast("Sequence[object]", raw))
+        if len(packed) < len(axes):
+            return None
+        source = packed[: len(axes)]
+    else:
+        return None
+    for item in source:
+        try:
+            values.append(float(cast("float", item)))
+        except TypeError, ValueError:
+            return None
+    return dict(zip(axes, values, strict=True))
+
+
+def _default_nests(device: Hostable) -> dict[str, dict[str, float] | None] | None:
+    """The labware positions the device declares, or None when it declares none.
+
+    Omitted from `describe` entirely when empty, so a driver that has no nests
+    describes byte-for-byte as it did before the field existed. A nest whose
+    offset does not parse is kept with a null offset rather than dropped: the
+    nest exists on the hardware either way, and an operator can place it by
+    hand.
+    """
+    raw = getattr(device, "default_nests", None)
+    resolved = raw() if callable(raw) else raw
+    if not isinstance(resolved, Mapping):
+        return None
+    nests = {str(name): _nest_offset(offset) for name, offset in cast("Mapping[str, object]", resolved).items()}
+    return nests or None
+
+
+def _configurations(device: Hostable) -> dict[str, object]:
+    """The hardware variants the driver can be added as, and which one this instance is.
+
+    A lab-device-sdk driver lists them from its `get_configurations()` staticmethod,
+    a lab_sync_driver_sdk one in its `configurations` class attribute. Both fields are
+    omitted when the driver declares none, so every other driver describes as
+    before. An instance whose own `configuration` is unset -- or is not one of the
+    names, which only a hand-edited record can produce -- reports the first, which
+    is the variant a driver runs as by default.
+    """
+    lister = getattr(device, "get_configurations", None)
+    raw = lister() if callable(lister) else getattr(device, "configurations", ())
+    if not isinstance(raw, Sequence) or isinstance(raw, (str, bytes)):
+        return {}
+    names = [str(name) for name in cast("Sequence[object]", raw) if str(name)]
+    if not names:
+        return {}
+    active = getattr(device, "configuration", None)
+    return {"configurations": names, "configuration": active if active in names else names[0]}
+
+
+def _describe(device: Hostable) -> dict[str, object]:
+    entry: dict[str, object] = {
+        "device_type_id": device.device_type_id,
+        "manufacturer": device.manufacturer,
+        "model": device.model,
+        "commands": [_command_dict(meta) for _, meta in device.command_specs().values()],
+    }
+    entry.update(_declared_metadata(device))
+    entry.update(_configurations(device))
+    settings_fn = getattr(device, "settings_specs", None)
+    if callable(settings_fn):
+        entry["settings"] = settings_fn()
+    picture_fn = getattr(device, "picture", None)
+    if callable(picture_fn):
+        picture = picture_fn()
+        if picture is not None:
+            entry["picture"] = picture
+    # What the device can draw on a lab map. Not in `_declared_metadata`
+    # because it is a document rather than a string, and omitted entirely when
+    # the driver declares none -- which is every driver that has not opted in.
+    artifacts_fn = getattr(device, "map_artifacts", None)
+    if callable(artifacts_fn):
+        artifacts = artifacts_fn()
+        if artifacts:
+            entry["map_artifacts"] = artifacts
+    # The labware positions the device holds. A document like `map_artifacts`
+    # rather than a scalar, and likewise omitted when the driver declares none.
+    nests = _default_nests(device)
+    if nests:
+        entry["default_nests"] = nests
+    # Which parts of the device's 3D model move. A document, omitted when unset.
+    # Accepts a plain attribute or a method, the same tolerance `default_nests`
+    # has: a fixed rig is naturally a literal, and one that depends on a
+    # connected device's configuration is naturally computed.
+    raw_articulation = getattr(device, "articulation", None)
+    articulation = raw_articulation() if callable(raw_articulation) else raw_articulation
+    if isinstance(articulation, Mapping):
+        entry["articulation"] = dict(cast("Mapping[str, object]", articulation))
+    # The demand-gated samplers the driver offers. The supervisor needs the list to
+    # know what it may switch on; omitted entirely when there are none, so a
+    # driver without samplers describes as it did before they existed.
+    channels = _telemetry_channels(device)
+    if channels:
+        entry["telemetry"] = channels
+    return {"devices": [entry]}
+
+
+def _telemetry_channels(device: Hostable) -> list[dict[str, object]]:
+    """The device's declared telemetry channels, as describe entries.
+
+    Only the declaration travels here -- what a channel *carries* is the channel's own business and reaches the supervisor as frames, not as a
+    schema.
+    """
+    specs_fn = getattr(device, "telemetry_specs", None)
+    if not callable(specs_fn):
+        return []
+    specs = cast("dict[str, tuple[str, TelemetryMeta]]", specs_fn())
+    return [
+        {"channel": meta.channel, "hz": float(meta.hz), "description": meta.description} for _, meta in specs.values()
+    ]
+
+
+def _connect_takes_settings(connect: Callable[..., object]) -> bool:
+    return any(p.kind != p.VAR_KEYWORD for p in inspect.signature(connect).parameters.values())
+
+
+class _Servicer:
+    def __init__(self, device: Hostable, driver_version: str) -> None:
+        super().__init__()
+        self._device = device
+        self._driver_version = driver_version
+        self._specs = device.command_specs()
+        # execution_id -> the running command task, so an abort can cancel it.
+        self._running: dict[str, asyncio.Task[None]] = {}
+        specs_fn = getattr(device, "telemetry_specs", None)
+        self._telemetry: dict[str, tuple[str, TelemetryMeta]] = (
+            cast("dict[str, tuple[str, TelemetryMeta]]", specs_fn()) if callable(specs_fn) else {}
+        )
+        # channel -> its running sampler. A channel absent here is switched off,
+        # which is the state every channel starts in.
+        self._samplers: dict[str, asyncio.Task[None]] = {}
+        # The methods whose handlers all take (request_id, params, send); a table
+        # rather than more elif branches, so adding one does not grow `handle`.
+        self._handlers: dict[
+            str, Callable[[object, dict[str, object], Callable[[dict[str, object]], Awaitable[None]]], Awaitable[None]]
+        ] = {
+            "connect": self._connect,
+            "set_simulation": self._set_simulation,
+            "execute": self._execute,
+            "abort": self._abort,
+            "describe_options": self._describe_options,
+            "estimate_time": self._estimate_time,
+            "set_telemetry_demand": self._set_telemetry_demand,
+        }
+
+    async def handle(self, frame: dict[str, object], send: Callable[[dict[str, object]], Awaitable[None]]) -> None:
+        request_id = frame.get("id")
+        method = frame.get("method")
+        raw_params = frame.get("params")
+        params = cast("dict[str, object]", raw_params) if isinstance(raw_params, dict) else {}
+        if method == "handshake":
+            await send(
+                {
+                    "id": request_id,
+                    "type": "reply",
+                    "result": {
+                        "driver_protocol_version": PROTOCOL_VERSION,
+                        "driver_id": self._device.device_type_id,
+                        "driver_version": self._driver_version,
+                    },
+                }
+            )
+        elif method == "describe":
+            await send({"id": request_id, "type": "reply", "result": _describe(self._device)})
+        elif method == "ping":
+            await send({"id": request_id, "type": "reply", "result": {"ok": True}})
+        elif (handler := self._handlers.get(str(method))) is not None:
+            await handler(request_id, params, send)
+        else:
+            await send(
+                {
+                    "id": request_id,
+                    "type": "error",
+                    "code": "unknown_method",
+                    "message": str(method),
+                }
+            )
+
+    async def _connect(
+        self,
+        request_id: object,
+        params: dict[str, object],
+        send: Callable[[dict[str, object]], Awaitable[None]],
+    ) -> None:
+        raw_settings = params.get("settings")
+        settings = cast("dict[str, object]", raw_settings) if isinstance(raw_settings, dict) else None
+        connect = cast("Callable[..., Awaitable[None]]", self._device.connect)
+        try:
+            if "is_simulated" in params:
+                await self._apply_simulation(enabled=bool(params["is_simulated"]))
+            if binds_settings(connect):
+                await connect(**bind_settings(connect, settings))
+            elif _connect_takes_settings(connect):
+                await connect(settings)
+            else:
+                await connect()
+        except Exception as exc:  # noqa: BLE001
+            await send(
+                {
+                    "id": request_id,
+                    "type": "reply",
+                    "result": {"connected": False, "message": str(exc)},
+                }
+            )
+            return
+        await send(
+            {
+                "id": request_id,
+                "type": "reply",
+                "result": {"connected": True, "message": "connected"},
+            }
+        )
+
+    async def _apply_simulation(self, *, enabled: bool) -> None:
+        setter = getattr(self._device, "set_simulation", None)
+        if callable(setter):
+            await cast("Awaitable[None]", setter(enabled=enabled))
+
+    async def _set_simulation(
+        self,
+        request_id: object,
+        params: dict[str, object],
+        send: Callable[[dict[str, object]], Awaitable[None]],
+    ) -> None:
+        await self._apply_simulation(enabled=bool(params.get("enabled", False)))
+        await send({"id": request_id, "type": "reply", "result": {"ok": True}})
+
+    async def _execute(  # noqa: C901
+        self,
+        request_id: object,
+        params: dict[str, object],
+        send: Callable[[dict[str, object]], Awaitable[None]],
+    ) -> None:
+        command = str(params.get("command", ""))
+        execution_id = str(params.get("execution_id", ""))
+        spec = self._specs.get(command)
+        if spec is None:
+            await send({"id": request_id, "type": "error", "code": "unknown_command", "message": command})
+            return
+        method_name, meta = spec
+        method = getattr(self._device, method_name)
+        kwargs = dict(json.loads(str(params.get("params_json") or "{}")))
+        # Callers key parameters by declared (display) name; `maps_to` names the
+        # method's actual keyword, so remap where declared.
+        for param in meta.inputs:
+            if param.maps_to and param.name in kwargs:
+                kwargs[param.maps_to] = kwargs.pop(param.name)
+
+        queue: asyncio.Queue[tuple[object, ...]] = asyncio.Queue()
+
+        async def progress(fraction: float, message: str = "") -> None:
+            await queue.put(("progress", fraction, message))
+
+        if "progress" in inspect.signature(method).parameters:
+            kwargs["progress"] = progress
+
+        async def run() -> None:
+            try:
+                result = await method(**kwargs)
+                validate_outputs(meta, result)
+                await queue.put(("result", result))
+            except asyncio.CancelledError:
+                await queue.put(("error", "aborted", "command aborted"))
+            except OutputValidationError as exc:
+                logger.exception("command %s output validation failed", command)
+                await queue.put(("error", "output_validation", str(exc)))
+            except Exception as exc:
+                logger.exception("command %s failed", command)
+                await queue.put(("error", "command_error", str(exc)))
+
+        task = asyncio.create_task(run())
+        if execution_id:
+            self._running[execution_id] = task
+        try:
+            while True:
+                item = await queue.get()
+                kind = item[0]
+                if kind == "progress":
+                    await send(
+                        {
+                            "id": request_id,
+                            "type": "progress",
+                            "fraction": item[1],
+                            "message": item[2],
+                        }
+                    )
+                elif kind == "result":
+                    await send(
+                        {
+                            "id": request_id,
+                            "type": "result",
+                            "output_json": json.dumps(item[1]),
+                        }
+                    )
+                    return
+                else:
+                    await send(
+                        {
+                            "id": request_id,
+                            "type": "error",
+                            "code": item[1],
+                            "message": item[2],
+                        }
+                    )
+                    return
+        finally:
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+            if execution_id:
+                _ = self._running.pop(execution_id, None)
+
+    async def _describe_options(
+        self,
+        request_id: object,
+        params: dict[str, object],
+        send: Callable[[dict[str, object]], Awaitable[None]],
+    ) -> None:
+        """Compute runtime choices for a command's dynamic-options parameters.
+
+        Best-effort per parameter: a missing or raising hook yields `[]` for that
+        parameter rather than an error frame, matching the operator-facing
+        contract (the dropdown just comes up empty).
+        """
+        command = str(params.get("command", ""))
+        raw = params.get("parameters")
+        parameters = cast("dict[str, object]", raw) if isinstance(raw, dict) else {}
+        spec = self._specs.get(command)
+        if spec is None:
+            await send({"id": request_id, "type": "error", "code": "unknown_command", "message": command})
+            return
+        _, meta = spec
+        hook = getattr(self._device, "get_dynamic_parameter_options", None)
+        options: dict[str, list[str]] = {}
+        for param in meta.inputs:
+            if not param.dynamic_options:
+                continue
+            values: list[str] = []
+            if callable(hook):
+                try:
+                    values = [str(v) for v in hook(command, param.name, parameters)]
+                except Exception:  # a driver's options hook must not fail the request
+                    logger.exception("dynamic options hook failed for %s / %s", command, param.name)
+            options[param.name] = values
+        await send({"id": request_id, "type": "reply", "result": {"options": options}})
+
+    async def _estimate_time(
+        self,
+        request_id: object,
+        params: dict[str, object],
+        send: Callable[[dict[str, object]], Awaitable[None]],
+    ) -> None:
+        """Estimate one call's duration through the device's `get_dynamic_simulation_time_sec`.
+
+        Best-effort like `_describe_options`: a missing hook, or one that raises
+        or answers something that is not a finite non-negative number, yields the
+        command's declared `default_sim_sec` rather than an error frame. The hook
+        may be a coroutine. `estimated_duration_sec` is null when there is
+        neither, and the supervisor then uses its own default.
+        """
+        command = str(params.get("command", ""))
+        raw = params.get("parameters")
+        parameters = cast("dict[str, object]", raw) if isinstance(raw, dict) else {}
+        spec = self._specs.get(command)
+        if spec is None:
+            await send({"id": request_id, "type": "error", "code": "unknown_command", "message": command})
+            return
+        _, meta = spec
+        estimate: float | None = meta.default_sim_sec
+        hook = getattr(self._device, "get_dynamic_simulation_time_sec", None)
+        if callable(hook):
+            try:
+                answer = hook(command, parameters)
+                if inspect.isawaitable(answer):
+                    answer = await answer
+                if (seconds := valid_duration(answer)) is not None:
+                    estimate = seconds
+            except Exception:  # an estimate must never fail the request
+                logger.exception("simulation time hook failed for %s", command)
+        await send({"id": request_id, "type": "reply", "result": {"estimated_duration_sec": estimate}})
+
+    async def _set_telemetry_demand(
+        self,
+        request_id: object,
+        params: dict[str, object],
+        send: Callable[[dict[str, object]], Awaitable[None]],
+    ) -> None:
+        """Switch samplers on and off to match the supervisor's demand.
+
+        `params["channels"]` is the complete set that should be running, not a
+        delta: the supervisor knows who is watching and this driver does not, so
+        restating the whole set means a lost or reordered frame cannot leave a
+        sampler stuck on. An unknown channel is ignored rather than refused --
+        a supervisor rolled ahead of this driver should not get an error frame for
+        asking about something harmless.
+
+        Args:
+            request_id: The request to reply to.
+            params: Carries `channels`, the set that should be running.
+            send: Frame sink.
+        """
+        raw = params.get("channels")
+        wanted = {str(c) for c in raw} if isinstance(raw, (list, tuple, set)) else set()
+        wanted &= set(self._telemetry)
+        for channel in list(self._samplers):
+            if channel not in wanted:
+                self._stop_sampler(channel)
+        for channel in wanted:
+            if channel not in self._samplers:
+                self._start_sampler(channel, send)
+        await send({"id": request_id, "type": "reply", "result": {"channels": sorted(self._samplers)}})
+
+    def _start_sampler(self, channel: str, send: Callable[[dict[str, object]], Awaitable[None]]) -> None:
+        """Begin sampling one channel until it is switched off or the loop ends."""
+        attr, meta = self._telemetry[channel]
+        task = asyncio.create_task(self._sample_loop(channel, attr, meta, send))
+        self._samplers[channel] = task
+        task.add_done_callback(lambda _t, c=channel: self._samplers.pop(c, None) and None)
+
+    def _stop_sampler(self, channel: str) -> None:
+        """Cancel one channel's sampler, if it is running."""
+        task = self._samplers.pop(channel, None)
+        if task is not None:
+            _ = task.cancel()
+
+    async def _sample_loop(
+        self,
+        channel: str,
+        attr: str,
+        meta: TelemetryMeta,
+        send: Callable[[dict[str, object]], Awaitable[None]],
+    ) -> None:
+        """Sample one channel on its cadence and push un-correlated frames.
+
+        Two failure rules, both chosen so a stream degrades rather than ends: a
+        sampler that raises is logged and retried on the next tick, and a
+        sampler slower than its own period simply runs less often. Neither a
+        flaky read nor a slow device should take the channel down, because
+        nothing would ever switch it back on -- demand is edge-triggered from
+        the browser, and it has already fired.
+
+        Args:
+            channel: The channel being sampled.
+            attr: Attribute name of the decorated method.
+            meta: Its declaration, for the cadence.
+            send: Frame sink.
+        """
+        period = 1.0 / meta.hz if meta.hz > 0 else 0.2
+        sampler = cast("Callable[[], Awaitable[object]]", getattr(self._device, attr))
+        while True:
+            started = time.monotonic()
+            try:
+                payload = await sampler()
+                if isinstance(payload, dict):
+                    await send({"type": "telemetry", "channel": channel, "payload": payload})
+            except asyncio.CancelledError:
+                raise
+            except Exception:  # noqa: BLE001 - a bad read must not end the stream
+                logger.warning("telemetry sampler %r failed; retrying next tick", channel, exc_info=True)
+            await asyncio.sleep(max(0.0, period - (time.monotonic() - started)))
+
+    def shutdown_samplers(self) -> None:
+        """Cancel every running sampler.
+
+        Called when the serve loop exits.
+        """
+        for channel in list(self._samplers):
+            self._stop_sampler(channel)
+
+    async def _abort(
+        self,
+        request_id: object,
+        params: dict[str, object],
+        send: Callable[[dict[str, object]], Awaitable[None]],
+    ) -> None:
+        execution_id = str(params.get("execution_id", ""))
+        task = self._running.get(execution_id)
+        if task is not None and not task.done():
+            _ = task.cancel()
+        # Signal the device to stop hardware (lab Device.abort / an SDK Device override).
+        abort = getattr(self._device, "abort", None)
+        if callable(abort):
+            with contextlib.suppress(Exception):
+                _ = await cast("Awaitable[object]", abort("*"))
+        await send({"id": request_id, "type": "reply", "result": {"aborted": task is not None}})
+
+
+def claim_stdout() -> BinaryIO:
+    """Claim fd 1 for protocol frames.
+
+    Redirect `sys.stdout` to stderr so device prints/logs cannot corrupt the stream.
+    """
+    out: BinaryIO = os.fdopen(os.dup(1), "wb", buffering=0)
+    sys.stdout = sys.stderr
+    root = logging.getLogger()
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+    root.addHandler(logging.StreamHandler(sys.stderr))
+    return out
+
+
+async def serve(device: Hostable, *, driver_version: str = "0.0.0", out: BinaryIO | None = None) -> None:
+    """Serve the driver over stdio until the supervisor closes stdin (EOF).
+
+    `out` lets a caller that claimed fd 1 first (e.g. the lab adapter, which also
+    runs uvicorn) pass the protocol stream in; standalone drivers leave it None.
+    """
+    loop = asyncio.get_running_loop()
+    servicer = _Servicer(device, driver_version)
+    stream = out if out is not None else claim_stdout()
+    # one thread parks on the blocking stdin.readline, one serves writes; 2 is structural, not a knob
+    executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix=f"driver-stdio-{device.device_type_id}")
+    write_lock = asyncio.Lock()
+    stdin: BinaryIO = os.fdopen(os.dup(0), "rb")
+
+    async def send(frame: dict[str, object]) -> None:
+        data = json.dumps(frame).encode("utf-8") + b"\n"
+        async with write_lock:
+            _ = await loop.run_in_executor(executor, stream.write, data)
+
+    tasks: set[asyncio.Task[None]] = set()
+    try:
+        while True:
+            line = await loop.run_in_executor(executor, stdin.readline)
+            if not line:
+                break
+            try:
+                frame = json.loads(line)
+            except json.JSONDecodeError:
+                logger.warning("dropping non-JSON line on stdin: %r", line[:80])
+                continue
+            task = asyncio.create_task(servicer.handle(frame, send))
+            tasks.add(task)
+            task.add_done_callback(tasks.discard)
+    finally:
+        logger.info("stdio serve loop exiting on stdin EOF; cancelling %d in-flight command(s)", len(tasks))
+        # Samplers are not in `tasks` -- they are un-correlated and outlive the
+        # request that started them -- so they need cancelling by name.
+        servicer.shutdown_samplers()
+        for task in list(tasks):
+            _ = task.cancel()
+        if tasks:
+            _ = await asyncio.gather(*tasks, return_exceptions=True)
+        executor.shutdown(wait=False)