mru-sdk 0.1.0a1__py3-none-any.whl

mru/__init__.py

@@ -0,0 +1,21 @@
+"""MRU: robot capabilities for Python jobs; model logic belongs to the job."""
+
+__version__ = "0.1.0a1"
+
+from .auth import Auth
+from .client import Client, LogEntry, LogPage, RemoteJob
+from .errors import APIError, LaunchError, PlatformConnectionError
+from .errors import (AuthenticationError, AuthorizationError, CommandRejected, DeadlineExceeded,
+                     JobCancelled, MRUError, ProtocolError, SessionClosed)
+from .job import Actuator, Job, run, run_async
+from .models import (ActuatorRequirement, ActuatorSpec, EncodedImage, ExecutionAck, JointState,
+                     Observation, Requirements, RobotCapabilities)
+from .session import Session
+
+__all__ = [
+    "APIError", "Client", "LaunchError", "LogEntry", "LogPage", "PlatformConnectionError", "RemoteJob",
+    "Auth", "AuthenticationError", "AuthorizationError",
+    "Actuator", "ActuatorRequirement", "ActuatorSpec", "CommandRejected", "DeadlineExceeded",
+    "EncodedImage", "ExecutionAck", "Job", "JobCancelled", "JointState", "MRUError", "Observation",
+    "ProtocolError", "Requirements", "RobotCapabilities", "Session", "SessionClosed", "run", "run_async",
+]

mru/auth.py

@@ -0,0 +1,39 @@
+"""Job credentials supplied by the platform, separate from task parameters."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+from .errors import AuthenticationError
+
+
+@dataclass(frozen=True, slots=True)
+class Auth:
+    """An opaque bearer credential. Construction does not validate access with MRU."""
+
+    _token: str = field(repr=False)
+
+    def __post_init__(self) -> None:
+        if (not isinstance(self._token, str) or not self._token
+                or any(not 33 <= ord(character) <= 126 for character in self._token)):
+            raise ValueError("Job token must be a nonempty printable ASCII string without whitespace")
+
+    @classmethod
+    def from_token(cls, token: str) -> Auth:
+        """Use a job token already issued by the platform; never a password."""
+        return cls(token)
+
+    @classmethod
+    def from_env(cls) -> Auth:
+        """Read MRU_JOB_TOKEN, failing if it is missing or malformed."""
+        token = os.environ.get("MRU_JOB_TOKEN")
+        if token is None:
+            raise AuthenticationError("unauthenticated", "Set MRU_JOB_TOKEN or pass auth=Auth.from_token(...)")
+        try:
+            return cls.from_token(token)
+        except ValueError:
+            raise AuthenticationError("unauthenticated", "MRU_JOB_TOKEN is malformed") from None
+
+    def _to_wire(self) -> dict[str, str]:
+        return {"scheme": "bearer", "token": self._token}

mru/client.py

@@ -0,0 +1,281 @@
+"""Python job launch client for the proposed mru.python-job/v1 backend contract.
+
+The backend contract is documented in docs/launch-api.md; it is not deployed
+by this package. No connection to a legacy deployment or CLI API is made.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import time
+import uuid
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from email.message import Message
+from http.client import HTTPException
+from pathlib import Path
+from typing import IO, Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from .errors import (APIError, AuthenticationError, AuthorizationError, LaunchError,
+                     PlatformConnectionError, ProtocolError)
+from .models import Requirements
+from .source import bundle_source
+
+TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled"})
+
+
+def _positive(value: float, name: str) -> float:
+    if isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be positive and finite")
+    return value
+
+
+def _identifier(value: str) -> str:
+    if not isinstance(value, str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,128}", value):
+        raise ValueError("Expected a job ID returned by MRU")
+    return quote(value, safe="")
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req: Request, fp: IO[bytes], code: int, msg: str,
+                         headers: Message, newurl: str) -> Request | None:
+        return None  # Never forward account credentials to another location.
+
+
+@dataclass(frozen=True)
+class LogEntry:
+    """One stdout, stderr, or system log line from a remote job."""
+
+    sequence: int
+    timestamp: str
+    stream: str
+    message: str
+
+
+@dataclass(frozen=True)
+class LogPage:
+    """Entries after the requested cursor, in ascending sequence order.
+
+    Pass ``cursor`` as ``after`` to fetch the next page. ``has_more`` means another
+    page is available now; it does not indicate whether the job has finished.
+    """
+
+    entries: tuple[LogEntry, ...]
+    cursor: int
+    has_more: bool
+
+    @classmethod
+    def _from_wire(cls, value: dict[str, Any], *, after: int) -> LogPage:
+        try:
+            raw_entries, cursor, has_more = value["entries"], value["cursor"], value["has_more"]
+            if not isinstance(raw_entries, list) or type(cursor) is not int or type(has_more) is not bool:
+                raise ValueError()
+            entries, previous = [], after
+            for item in raw_entries:
+                entry = LogEntry(item["sequence"], item["timestamp"], item["stream"], item["message"])
+                if (type(entry.sequence) is not int or entry.sequence <= previous
+                        or not all(isinstance(text, str) for text in (entry.timestamp, entry.stream, entry.message))):
+                    raise ValueError()
+                entries.append(entry)
+                previous = entry.sequence
+            if cursor < previous:
+                raise ValueError()
+        except (KeyError, TypeError, ValueError):
+            raise ProtocolError("MRU returned an invalid log page") from None
+        return cls(tuple(entries), cursor, has_more)
+
+
+class Client:
+    """Launch and monitor remote jobs using an MRU account token.
+
+    This client runs on the customer's computer, independently of Job/Session
+    inside the remote runtime. Constructing it makes no network requests.
+    """
+
+    def __init__(self, *, token: str, api_url: str, timeout: float = 30.0):
+        if (not isinstance(token, str) or not token
+                or any(not 33 <= ord(c) <= 126 for c in token)):
+            raise AuthenticationError("unauthenticated", "Supply a nonempty MRU API token without whitespace")
+        url = api_url
+        if not isinstance(url, str) or any(ord(c) <= 32 or ord(c) == 127 for c in url):
+            raise ValueError("Use an HTTPS MRU API origin")
+        try:
+            parsed = urlsplit(url)
+            parsed.port  # Reject malformed ports before attempting a connection.
+            valid = (parsed.hostname and not parsed.username and not parsed.password
+                     and not parsed.query and not parsed.fragment and parsed.path in ("", "/")
+                     and (parsed.scheme == "https" or
+                          parsed.scheme == "http" and parsed.hostname in ("localhost", "127.0.0.1", "::1")))
+        except ValueError:
+            valid = False
+        if not valid:
+            raise ValueError("Use an HTTPS MRU API origin (HTTP is allowed only for localhost)")
+        self.api_url = url.rstrip("/")
+        self.timeout = _positive(timeout, "timeout")
+        self._token = token
+        self._opener = build_opener(_NoRedirect)
+
+    @classmethod
+    def from_env(cls, *, timeout: float = 30.0) -> Client:
+        """Read MRU_API_TOKEN and MRU_API_URL; no CLI state or job credentials."""
+        token, url = os.environ.get("MRU_API_TOKEN"), os.environ.get("MRU_API_URL")
+        if not token:
+            raise AuthenticationError("unauthenticated", "Set MRU_API_TOKEN")
+        if not url:
+            raise ValueError("Set MRU_API_URL to a server implementing the Python launch contract")
+        return cls(token=token, api_url=url, timeout=timeout)
+
+    def _request(self, path: str, body: dict[str, Any] | None = None, *, timeout: float | None = None,
+                 request_id: str | None = None) -> dict[str, Any]:
+        data = None if body is None else json.dumps(body, allow_nan=False).encode("utf-8")
+        if data is not None and len(data) > 16 * 1024 * 1024:
+            raise ValueError("Launch request exceeds the 16 MiB limit")
+        request = Request(self.api_url + path, data=data, headers={
+            "Authorization": "Bearer " + self._token,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            **({"Idempotency-Key": request_id} if request_id else {}),
+        })
+        try:
+            with self._opener.open(request, timeout=self.timeout if timeout is None else timeout) as response:
+                result = json.load(response)
+        except HTTPError as exc:
+            try:
+                with exc:
+                    reply = json.load(exc)
+                detail = reply.get("error", {}).get("message") if isinstance(reply, dict) and isinstance(reply.get("error"), dict) else None
+            except (ValueError, OSError, HTTPException):
+                detail = None
+            message = detail if isinstance(detail, str) else f"MRU API returned HTTP {exc.code}"
+            message = message.replace(self._token, "[redacted]")
+            if exc.code == 401:
+                raise AuthenticationError("unauthenticated", message) from None
+            if exc.code == 403:
+                raise AuthorizationError("permission_denied", message) from None
+            raise APIError(exc.code, message) from None
+        except (URLError, OSError, HTTPException):
+            raise PlatformConnectionError("MRU connection failed; the remote outcome may be unknown") from None
+        except (ValueError, UnicodeError):
+            raise ProtocolError("MRU API returned invalid JSON") from None
+        if not isinstance(result, dict):
+            raise ProtocolError("MRU API response must be an object")
+        return result
+
+    def me(self) -> dict[str, Any]:
+        """Verify credentials and return the authenticated account response."""
+        return self._request("/v1/me")
+
+    def launch(self, entrypoint: str | Path, *, robot_id: str,
+               params: Mapping[str, Any] | None = None, dependencies: Sequence[str] = (),
+               requirements: Requirements | None = None, source_dir: str | Path | None = None,
+               files: Sequence[str] = (), python_version: str = "3.12",
+               timeout_seconds: int = 600, request_id: str | None = None) -> RemoteJob:
+        """Upload selected source files and queue a Python job on MRU.
+
+        Nothing is imported or executed locally. Only entrypoint and explicit
+        files are uploaded. Requires the proposed backend contract in launch-api.md.
+        """
+        request_id = uuid.uuid4().hex if request_id is None else request_id
+        if not isinstance(request_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]{16,80}", request_id):
+            raise ValueError("request_id must contain 16–80 ASCII letters, digits, underscores, or hyphens")
+        if not isinstance(robot_id, str) or not robot_id.strip() or len(robot_id) > 128:
+            raise ValueError("robot_id must be a nonempty string of at most 128 characters")
+        if not isinstance(dependencies, Sequence) or isinstance(dependencies, (str, bytes)) or any(
+                not isinstance(dep, str) or not dep.strip() or dep.startswith("-") or "\n" in dep or "\r" in dep
+                for dep in dependencies):
+            raise ValueError("dependencies must contain individual package requirements, not pip options")
+        if not isinstance(python_version, str) or not re.fullmatch(r"3\.(?:1[1-9]|[2-9][0-9])", python_version):
+            raise ValueError("python_version must name Python 3.11 or newer, e.g. 3.12")
+        if type(timeout_seconds) is not int or timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be a positive integer")
+        if params is not None and (not isinstance(params, Mapping) or any(not isinstance(k, str) for k in params)):
+            raise ValueError("params must be an object with string keys")
+        entry_name, source = bundle_source(entrypoint, source_dir=source_dir, files=files)
+        payload = {
+            "protocol": "mru.python-job/v1", "entrypoint": entry_name,
+            "robot_id": robot_id, "params": dict(params or {}),
+            "dependencies": list(dependencies), "python_version": python_version,
+            "requirements": (requirements or Requirements()).to_wire(),
+            "timeout_seconds": timeout_seconds, "source": source,
+        }
+        try:
+            view = self._request("/v1/jobs", payload, request_id=request_id)
+            return RemoteJob(self, view, request_id=request_id)
+        except (PlatformConnectionError, ProtocolError) as exc:
+            raise LaunchError(request_id, "Launch outcome is unknown; retry unchanged source and options with this request_id") from exc
+        except APIError as exc:
+            if exc.status_code >= 500:
+                raise LaunchError(request_id, "Launch outcome is unknown; retry unchanged source and options with this request_id") from exc
+            raise
+
+    def get_job(self, job_id: str) -> RemoteJob:
+        """Reconnect to a previously launched job without starting another one."""
+        identifier = _identifier(job_id)
+        return RemoteJob(self, self._request("/v1/jobs/" + identifier), expected_id=job_id)
+
+
+class RemoteJob:
+    """Handle for a remote Python job. Status is cached until refresh/wait/cancel."""
+
+    def __init__(self, client: Client, view: dict[str, Any], *, request_id: str | None = None,
+                 expected_id: str | None = None):
+        self._client = client
+        self.request_id = request_id
+        self._update(view, expected_id=expected_id)
+
+    def _update(self, view: dict[str, Any], *, expected_id: str | None = None) -> None:
+        try:
+            identifier, status = view["job"]["id"], view["job"]["status"]
+            _identifier(identifier)
+            if not isinstance(status, str) or not status or expected_id is not None and identifier != expected_id:
+                raise ValueError()
+        except (KeyError, TypeError, ValueError):
+            raise ProtocolError("MRU returned an invalid job response") from None
+        self.id: str = identifier
+        self.status: str = status
+        self.details: dict[str, Any] = dict(view["job"])  # Full job record from the last response.
+
+    def refresh(self) -> RemoteJob:
+        view = self._client._request("/v1/jobs/" + quote(self.id, safe=""))
+        self._update(view, expected_id=self.id)
+        return self
+
+    def wait(self, *, timeout: float = 300.0, poll_interval: float = 2.0) -> RemoteJob:
+        """Wait for terminal status; timeout leaves the remote job running."""
+        deadline = time.monotonic() + _positive(timeout, "timeout")
+        _positive(poll_interval, "poll_interval")
+        while self.status not in TERMINAL_STATUSES:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"Stopped waiting for {self.id}; the remote job has not been cancelled")
+            try:
+                view = self._client._request("/v1/jobs/" + quote(self.id, safe=""),
+                                             timeout=min(self._client.timeout, remaining))
+            except PlatformConnectionError:
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(f"Stopped waiting for {self.id}; the remote job has not been cancelled") from None
+                raise
+            self._update(view, expected_id=self.id)
+            if self.status not in TERMINAL_STATUSES:
+                time.sleep(min(poll_interval, max(0, deadline - time.monotonic())))
+        return self
+
+    def cancel(self) -> RemoteJob:
+        """Request cancellation; use refresh/wait to observe the resulting status."""
+        view = self._client._request("/v1/jobs/" + quote(self.id, safe="") + "/cancel", {})
+        self._update(view, expected_id=self.id)
+        return self
+
+    def logs(self, *, after: int = 0, limit: int = 100) -> LogPage:
+        """Fetch one page of log entries with sequence greater than ``after``."""
+        if type(after) is not int or after < 0 or type(limit) is not int or not 1 <= limit <= 100:
+            raise ValueError("after must be a nonnegative integer; limit must be between 1 and 100")
+        view = self._client._request("/v1/jobs/" + quote(self.id, safe="")
+                                     + "/logs?" + urlencode({"after": after, "limit": limit}))
+        return LogPage._from_wire(view, after=after)

mru/errors.py

@@ -0,0 +1,53 @@
+"""Errors surfaced to job authors."""
+
+
+class MRUError(Exception):
+    """Base SDK error."""
+
+
+class SessionClosed(MRUError):
+    pass
+
+
+class JobCancelled(MRUError):
+    pass
+
+
+class DeadlineExceeded(MRUError):
+    """The outcome may be unknown; the SDK requests a stop and ends the session."""
+
+
+class CommandRejected(MRUError):
+    def __init__(self, code: str, message: str):
+        self.code = code
+        super().__init__(message)
+
+
+class ProtocolError(MRUError):
+    pass
+
+
+class AuthenticationError(CommandRejected):
+    """The job credential is missing, invalid, expired, or revoked."""
+
+
+class AuthorizationError(CommandRejected):
+    """The authenticated job lacks permission for this robot or action."""
+
+
+class APIError(MRUError):
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class PlatformConnectionError(MRUError):
+    """The platform could not be reached or its response was lost."""
+
+
+class LaunchError(PlatformConnectionError):
+    """A submission may have succeeded. Preserve request_id before retrying."""
+
+    def __init__(self, request_id: str, message: str):
+        self.request_id = request_id
+        super().__init__(f"{message} (request_id={request_id})")

mru/job.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
+from types import MappingProxyType, TracebackType
+from typing import Any
+
+from .auth import Auth
+from .models import ActuatorSpec, ExecutionAck, Observation, Requirements
+from .session import Session
+from .transport import UnixTransport
+
+
+class Actuator:
+    """A named actuator group advertised by the robot. Obtain handles from ``job.actuators``."""
+
+    def __init__(self, session: Session, name: str, spec: ActuatorSpec):
+        self._session, self.name, self.spec = session, name, spec
+
+    async def move(self, *, positions: Sequence[float], duration_ms: int,
+                   observation_id: str, timeout: float | None = None) -> ExecutionAck:
+        """Execute absolute positions in spec.joints order and spec.unit; await execution."""
+        self._session.check_active()
+        positions = tuple(positions)
+        if "joint_position" not in self.spec.commands:
+            raise ValueError("Actuator does not support absolute joint positions")
+        self.spec.validate(positions)
+        if isinstance(duration_ms, bool) or not isinstance(duration_ms, int) or duration_ms <= 0:
+            raise ValueError("duration_ms must be a positive integer")
+        if not isinstance(observation_id, str) or not observation_id:
+            raise ValueError("An observation_id is required")
+        result = await self._session.request(
+            "move", timeout=timeout, actuator=self.name, command="joint_position",
+            unit=self.spec.unit, positions=positions, duration_ms=duration_ms,
+            observation_id=observation_id,
+        )
+        return ExecutionAck(result["command_id"], result["executed_at_ns"])
+
+
+class Job:
+    """The running job: parameters, observations, actuators, and lifecycle."""
+
+    def __init__(self, session: Session):
+        if session.capabilities is None:
+            raise ValueError("Open the session before creating a Job")
+        self.session = session
+        self.params: Mapping[str, Any] = MappingProxyType(session.params)
+        self.actuators: Mapping[str, Actuator] = MappingProxyType({
+            name: Actuator(session, name, spec) for name, spec in session.capabilities.actuators.items()
+        })
+        self.logger = logging.getLogger("mru.job")
+        self._finished = False
+
+    def observations(self) -> AsyncIterator[Observation]:
+        """Iterate recent observations; only one consumer is supported per session."""
+        return self.session.observations()
+
+    async def complete(self) -> None:
+        """Report success and stop further execution."""
+        await self.session.finish()
+        self._finished = True
+
+    async def fail(self, reason: str) -> None:
+        """Report failure with a human-readable reason and stop further execution."""
+        await self.session.finish(failure=reason)
+        self._finished = True
+
+    async def __aenter__(self) -> Job:
+        return self
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc: BaseException | None,
+                        traceback: TracebackType | None) -> None:
+        try:
+            if not self._finished:
+                if exc is None:
+                    await self.complete()
+                elif isinstance(exc, Exception):
+                    with contextlib.suppress(Exception):
+                        await self.fail(str(exc))
+        finally:
+            await self.session.close()
+
+
+async def run_async(main: Callable[[Job], Awaitable[None]], *, session: Session | None = None,
+                    requirements: Requirements | None = None, auth: Auth | None = None) -> None:
+    """Run a job; returning normally completes it. Platform cancellation cancels main()."""
+    if session is None:
+        path = os.environ.get("MRU_SESSION_SOCKET")
+        if not path:
+            raise RuntimeError("Set MRU_SESSION_SOCKET or provide a Session (e.g. FakeRobot.session())")
+        if auth is None:
+            auth = Auth.from_env()
+        session = Session(await UnixTransport.connect(path))
+    await session.open(requirements, auth=auth)
+    async with Job(session) as job:
+        async def call_main() -> None:
+            await main(job)  # Accept any awaitable, not only coroutines.
+
+        task = asyncio.create_task(call_main(), name="mru-job")
+        interrupted = asyncio.create_task(session.interrupted.wait())
+        try:
+            await asyncio.wait({task, interrupted}, return_when=asyncio.FIRST_COMPLETED)
+            if interrupted.done():
+                session.check_active()
+            await task
+        finally:
+            for pending in (task, interrupted):
+                if not pending.done():
+                    pending.cancel()
+            await asyncio.gather(task, interrupted, return_exceptions=True)
+
+
+def run(main: Callable[[Job], Awaitable[None]], *, session: Session | None = None,
+        requirements: Requirements | None = None, auth: Auth | None = None) -> None:
+    """Blocking form of :func:`run_async` for scripts without an event loop."""
+    asyncio.run(run_async(main, session=session, requirements=requirements, auth=auth))

mru/models.py

@@ -0,0 +1,136 @@
+"""Wire-independent robot data. Position commands use each group's declared unit."""
+
+from __future__ import annotations
+
+import base64
+import math
+from dataclasses import asdict, dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class JointState:
+    names: tuple[str, ...]
+    positions: tuple[float, ...]
+    unit: str = "rad"
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "names", tuple(self.names))
+        object.__setattr__(self, "positions", tuple(self.positions))
+
+
+@dataclass(frozen=True)
+class EncodedImage:
+    data: bytes
+    encoding: str  # e.g. image/jpeg or image/png; decoding belongs to the job
+
+
+@dataclass(frozen=True)
+class Observation:
+    id: str
+    timestamp_ns: int  # Agent capture time, Unix epoch nanoseconds
+    joint_states: Mapping[str, JointState] = field(default_factory=dict)
+    images: Mapping[str, EncodedImage] = field(default_factory=dict)
+    sensors: Mapping[str, float] = field(default_factory=dict)
+
+    def to_wire(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "timestamp_ns": self.timestamp_ns,
+            "joint_states": {name: asdict(value) for name, value in self.joint_states.items()},
+            "images": {
+                name: {"encoding": value.encoding, "data": base64.b64encode(value.data).decode("ascii")}
+                for name, value in self.images.items()
+            },
+            "sensors": dict(self.sensors),
+        }
+
+    @classmethod
+    def from_wire(cls, value: dict[str, Any]) -> Observation:
+        return cls(
+            id=value["id"], timestamp_ns=value["timestamp_ns"],
+            joint_states={
+                name: JointState(state["names"], state["positions"], state["unit"])
+                for name, state in value.get("joint_states", {}).items()
+            },
+            images={
+                name: EncodedImage(base64.b64decode(image["data"], validate=True), image["encoding"])
+                for name, image in value.get("images", {}).items()
+            },
+            sensors=value.get("sensors", {}),
+        )
+
+
+@dataclass(frozen=True)
+class ActuatorSpec:
+    joints: tuple[str, ...]
+    unit: str = "rad"
+    commands: tuple[str, ...] = ("joint_position",)
+    limits: tuple[tuple[float, float], ...] = ()
+
+    def __post_init__(self) -> None:
+        # Accept lists from callers and JSON; comparisons and hashing rely on tuples.
+        object.__setattr__(self, "joints", tuple(self.joints))
+        object.__setattr__(self, "commands", tuple(self.commands))
+        object.__setattr__(self, "limits", tuple((low, high) for low, high in self.limits))
+
+    def validate(self, positions: tuple[float, ...]) -> None:
+        if len(positions) != len(self.joints):
+            raise ValueError(f"Expected {len(self.joints)} positions in joint order {self.joints}")
+        if not all(math.isfinite(value) for value in positions):
+            raise ValueError("Positions must be finite")
+        if self.limits and len(self.limits) != len(self.joints):
+            raise ValueError("Invalid actuator capability limits")
+        if self.limits and any(not low <= value <= high for value, (low, high) in zip(positions, self.limits)):
+            raise ValueError("Position exceeds advertised limits")
+
+
+@dataclass(frozen=True)
+class RobotCapabilities:
+    sensors: Mapping[str, str]  # name -> joint_state, encoded_image, scalar
+    actuators: Mapping[str, ActuatorSpec]
+
+    def to_wire(self) -> dict[str, Any]:
+        return {"sensors": dict(self.sensors), "actuators": {k: asdict(v) for k, v in self.actuators.items()}}
+
+    @classmethod
+    def from_wire(cls, value: dict[str, Any]) -> RobotCapabilities:
+        return cls(value["sensors"], {
+            name: ActuatorSpec(spec["joints"], spec["unit"], spec["commands"], spec.get("limits", ()))
+            for name, spec in value["actuators"].items()
+        })
+
+
+@dataclass(frozen=True)
+class ActuatorRequirement:
+    unit: str
+    command: str = "joint_position"
+    joints: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "joints", tuple(self.joints))
+
+
+@dataclass(frozen=True)
+class Requirements:
+    sensors: Mapping[str, str] = field(default_factory=dict)
+    actuators: Mapping[str, ActuatorRequirement] = field(default_factory=dict)
+
+    def to_wire(self) -> dict[str, Any]:
+        return {"sensors": dict(self.sensors), "actuators": {k: asdict(v) for k, v in self.actuators.items()}}
+
+    def validate(self, capabilities: RobotCapabilities) -> None:
+        for name, kind in self.sensors.items():
+            if capabilities.sensors.get(name) != kind:
+                raise ValueError(f"Missing or incompatible sensor: {name} ({kind})")
+        for name, requirement in self.actuators.items():
+            spec = capabilities.actuators.get(name)
+            if (spec is None or spec.unit != requirement.unit or requirement.command not in spec.commands
+                    or (requirement.joints and requirement.joints != spec.joints)):
+                raise ValueError(f"Missing or incompatible actuator: {name}")
+
+
+@dataclass(frozen=True)
+class ExecutionAck:
+    command_id: str
+    executed_at_ns: int