lucen-device 0.3.0__py3-none-any.whl

lucen_device/__init__.py

@@ -0,0 +1,13 @@
+"""MouseMouse robot-side driver — the device consent layer's other half (M13).
+
+`lucen-device` runs on the robot's own computer and holds two things the hub
+never sees: the device's Ed25519 private key and whatever the robot needs to
+start a policy (a bus, an SSH target, a launch command). It talks to the hub
+with an ordinary `write`-scoped API key — which, by the hub's own contract,
+cannot approve anything — and acts only on approvals a human signed in the
+web app, verified **offline** against the hub's published key.
+"""
+
+__version__ = "0.3.0"
+
+__all__ = ["__version__"]

lucen_device/adapter_runtime.py

@@ -0,0 +1,214 @@
+"""Driving an adapter the driver did not write (M17d).
+
+Everything :mod:`lucen_device.serve` and :mod:`lucen_device.endpoint` do to an
+adapter goes through here, because since M17d the adapter may be anybody's
+code:
+
+- :func:`describe` — the ``adapter_info`` the hub stores at registration:
+  where the code came from, which protocols it implements, what the fail-safe
+  probe found;
+- :func:`resolve_registered` — load the ONE adapter ``device.json`` names and
+  refuse (:class:`AdapterChanged`) when that name no longer resolves to the
+  distribution and class that were registered. A new *version* of the same
+  distribution is allowed — robots get updates — and is what the ``started``
+  event reports;
+- :func:`prepare` — the optional hooks, in order: ``set_safe_stop(mode)`` from
+  the robot card, then the staged start (``safe`` -> ``default_pose``);
+- :func:`safe_status` / :func:`safe_stop` — ``status()`` and ``stop()`` under a
+  timeout and an exception barrier: a heartbeat must not be able to crash or
+  stall a run, and a ``stop()`` that raises must still be reported.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Final
+
+from lucen_device import __version__
+from lucen_device.adapters import (
+    START_STAGES,
+    AdapterError,
+    Capabilities,
+    LoadedAdapter,
+    guarded_call,
+    inspect_adapter,
+    load_adapter,
+    probe_fail_safe,
+)
+from lucen_device.adapters.registry import construct
+from lucen_device.config import DeviceConfig
+from lucen_device.embodiment import safe_stop_mode
+
+STATUS_TIMEOUT_S: Final[float] = 2.0
+#: `command`'s documented stop is up to 30 s of stop_cmd + 10 s TERM + 5 s KILL.
+STOP_TIMEOUT_S: Final[float] = 60.0
+STATUS_MAX_BYTES: Final[int] = 16 * 1024
+#: Q8: a person's STOP holds first — the fail-safe's own budget (endpoint.py's
+#: `HOLD_TIMEOUT_S`): a hold that does not return in a second is not a hold.
+STOP_HOLD_TIMEOUT_S: Final[float] = 1.0
+
+
+class AdapterChanged(AdapterError):
+    """The registered adapter name now resolves to different code."""
+
+
+def _norm(value: Any) -> str | None:
+    return re.sub(r"[-_.]+", "-", str(value)).lower() if value else None
+
+
+def describe(
+    loaded: LoadedAdapter, config: dict[str, Any], *, probe: bool = True
+) -> tuple[dict[str, Any], Capabilities, bool]:
+    """(`adapter_info`, capabilities, endpoint_capable) for a loaded adapter.
+
+    Endpoint-capable means BOTH halves hold: the class implements the chunk
+    protocol, and `hold()` then `stop()` ran clean on a fresh instance.
+    """
+    found = inspect_adapter(loaded.klass)
+    verdict: str | None = None
+    capable = False
+    if "chunks" in found.protocols and probe:
+        capable, verdict = probe_fail_safe(lambda: construct(loaded, config))
+    info = {
+        **loaded.provenance(),
+        "driver_version": __version__,
+        "protocols": list(found.protocols),
+        "fail_safe_probe": verdict,
+    }
+    return info, found, capable
+
+
+def resolve_registered(config: DeviceConfig) -> LoadedAdapter:
+    """The adapter this box registered — or :class:`AdapterChanged` / :class:`AdapterError`."""
+    loaded = load_adapter(config.load_spec)
+    if loaded.name != config.adapter:
+        raise AdapterChanged(
+            f"`{config.load_spec}` now calls itself {loaded.name!r}; this box registered "
+            f"{config.adapter!r}. Re-register (`lucen-device register --force`) to run it."
+        )
+    registered = config.adapter_info
+    if registered:  # a pre-M17d registration recorded nothing to compare with
+        now = loaded.provenance()
+        for key in ("source", "target", "distribution"):
+            before, after = registered.get(key), now.get(key)
+            same = _norm(before) == _norm(after) if key == "distribution" else before == after
+            if not same:
+                raise AdapterChanged(
+                    f"adapter {config.adapter!r} was registered from {key} {before!r} and now "
+                    f"resolves to {after!r}. The driver runs what the operator registered: "
+                    "re-register (`lucen-device register --force`) if this is intended."
+                )
+    return loaded
+
+
+def provenance_for_events(loaded: LoadedAdapter, config: DeviceConfig) -> dict[str, Any]:
+    """What ran, for the signed trail — plus the registered version when it has moved."""
+    out: dict[str, Any] = {
+        "adapter": loaded.name,
+        "adapter_info": {**loaded.provenance(), "driver_version": __version__},
+    }
+    registered = config.adapter_info.get("version") if config.adapter_info else None
+    if registered and registered != loaded.version:
+        out["adapter_info"] = {**out["adapter_info"], "registered_version": registered}
+    return out
+
+
+def prepare(adapter: Any, found: Capabilities, interface: dict[str, Any] | None) -> dict[str, Any]:
+    """`set_safe_stop`, then the staged start. Facts for the `started` event, or AdapterError."""
+    facts: dict[str, Any] = {}
+    mode = safe_stop_mode(interface)
+    if "safe_stop" in found.protocols:
+        _hook(lambda: adapter.set_safe_stop(mode or "hold"), f"set_safe_stop({mode or 'hold'})")
+        facts["safe_stop"] = mode or "hold"
+    elif mode not in (None, "hold"):
+        raise AdapterError(
+            f"the robot card declares safe_stop `{mode}`, and this adapter has no "
+            "`set_safe_stop()` — its hold()/stop() cannot be told what a safe stop is on this "
+            "robot. Nothing was started."
+        )
+    else:
+        facts["safe_stop"] = "adapter_default"
+    if "staged_start" in found.protocols:
+        for stage in START_STAGES:
+            _hook(lambda s=stage: adapter.stage(s, interface), f"stage `{stage}`")
+        facts["staged_start"] = list(START_STAGES)
+    return facts
+
+
+def _hook(call: Any, what: str) -> None:
+    try:
+        call()
+    except AdapterError as exc:
+        raise AdapterError(f"{what}: {exc}") from exc
+    except Exception as exc:  # third-party code
+        raise AdapterError(f"{what} raised {type(exc).__name__}: {exc}") from exc
+
+
+def safe_status(adapter: Any, *, timeout: float = STATUS_TIMEOUT_S) -> dict[str, Any]:
+    """`adapter.status()` as plain, bounded JSON — never an exception, never a stall."""
+    box: list[Any] = []
+    problem = guarded_call(lambda: box.append(adapter.status()), timeout=timeout)
+    if problem is not None:
+        return {"status_error": f"status() {problem}"}
+    status = box[0] if box else None
+    if not isinstance(status, dict):
+        return {"status_error": f"status() returned {type(status).__name__}, not a dict"}
+    try:
+        encoded = json.dumps(status, default=str)
+    except (TypeError, ValueError) as exc:
+        return {"status_error": f"status() is not JSON: {exc}"}
+    if len(encoded) > STATUS_MAX_BYTES:
+        return {"status_error": f"status() is {len(encoded)} bytes; the cap is {STATUS_MAX_BYTES}"}
+    plain: dict[str, Any] = json.loads(encoded)
+    return plain
+
+
+def safe_stop(adapter: Any, *, timeout: float = STOP_TIMEOUT_S) -> str | None:
+    """`adapter.stop()`; None when it returned, else what went wrong (reported, not raised)."""
+    problem = guarded_call(adapter.stop, timeout=timeout)
+    return None if problem is None else f"stop() {problem}"
+
+
+def hold_then_stop(
+    adapter: Any, reason: str, *, hold_timeout: float = STOP_HOLD_TIMEOUT_S
+) -> dict[str, Any]:
+    """Q8: a person's STOP, in M17d's fail-safe order — `hold(reason)`, then `stop()`.
+
+    `hold()` is part of the chunk protocol, so an adapter without one (a
+    reflex-only plugin) goes straight to `stop()`. A hold that raises or hangs
+    does not delay the stop: it is reported, and `stop()` runs regardless.
+    Returns what happened, for the signed `stopped` event.
+    """
+    sequence: list[str] = []
+    facts: dict[str, Any] = {}
+    hold = getattr(adapter, "hold", None)
+    if callable(hold):
+        problem = guarded_call(lambda: hold(reason), timeout=hold_timeout)
+        sequence.append("hold")
+        if problem is not None:
+            facts["hold_error"] = f"hold() {problem}"
+    stop_problem = safe_stop(adapter)
+    sequence.append("stop")
+    if stop_problem is not None:
+        facts["stop_error"] = stop_problem
+    facts["stop_sequence"] = sequence
+    return facts
+
+
+def summary(status: dict[str, Any], **facts: Any) -> dict[str, Any]:
+    """An event summary in which the DRIVER's facts win over the adapter's status keys."""
+    return {**status, **facts}
+
+
+__all__ = [
+    "AdapterChanged",
+    "describe",
+    "hold_then_stop",
+    "prepare",
+    "provenance_for_events",
+    "resolve_registered",
+    "safe_status",
+    "safe_stop",
+    "summary",
+]

lucen_device/adapters/__init__.py

@@ -0,0 +1,203 @@
+"""Adapters: the one seam between an approved policy and a robot.
+
+**Adapters are plugins (M17d).** The driver ships three; anybody else's robot
+gets its own by installing a distribution that registers a class in the
+entry-point group ``lucen_device.adapters`` — the built-ins register through
+the same group — or, for a script nobody packaged, by naming it as
+``module:Class`` / ``path/to/file.py:Class``. See :mod:`.registry`.
+
+Loading an adapter is **code execution on the robot box**, with the driver's
+privileges. So the rule is: *the operator names the adapter at* ``lucen-device
+register`` *and the driver loads that one and no other.* Listing what is
+installed reads package metadata and imports nothing; ``serve`` loads exactly
+what ``device.json`` names and refuses when it no longer resolves to the
+distribution and class that were registered. What ran — distribution, version,
+class — goes into the device's ``adapter_info`` on the hub and into every
+signed ``started`` event.
+
+Two required protocols, two optional hooks:
+
+- :class:`Adapter` (M13, ``policy``) — ``start(model_path, manifest, seconds)
+  / stop() / status() / is_running()``: the robot runs the approved file
+  itself (the reflex path). The driver does everything before ``start`` and
+  everything after ``stop``.
+- :class:`ChunkConsumer` (M15, ``chunks``) — the robot **consumes a hub
+  endpoint**: ``begin(contract, seconds)``, ``observe()`` (what to send),
+  ``apply(chunk)`` (a fresh action chunk), and the **mandatory local
+  fail-safe** ``hold(reason)`` — freeze in a safe posture (or the adapter's
+  own stop) when the round trip misses the chunk deadline twice or the link
+  drops — plus ``resume()`` when chunks flow again.
+- :class:`StagedStart` (M17d, optional, ``staged_start``) —
+  ``stage(name, interface)`` is called with ``"safe"`` and then
+  ``"default_pose"`` before ``start`` / ``begin``: reach the safe state, move
+  to the robot card's default pose, only then hand over to the policy.
+- :class:`SafeStopAware` (M17d, optional, ``safe_stop``) —
+  ``set_safe_stop(mode)`` with the robot card's
+  ``interface.safety.safe_stop`` (``hold | zero_torque | default_pose``): what
+  ``hold()`` and ``stop()`` must *mean* on this robot. An adapter that cannot
+  do the mode raises, and nothing starts.
+
+**Capability by protocol, not by name** (:mod:`.capabilities`): whether a
+device may consume a hub endpoint is what :func:`inspect_adapter` finds in the
+class *and* what :func:`probe_fail_safe` finds when it calls ``hold()`` then
+``stop()`` on a fresh instance. ``hold()`` and ``stop()`` must therefore be
+safe to call in any state — before ``begin``, twice in a row — and must not
+raise. The hub stores the declaration; **the enforcement is in the driver's
+link loop** (:mod:`lucen_device.endpoint`), which treats a ``hold()`` that
+raises or hangs as a reason to ``stop()``.
+
+What ships:
+
+- ``virtual`` — every protocol. Validates the contract, ticks at the control
+  rate, holds when told, and simulates **nothing** (no inference, no physics,
+  no actuators) — it exists so the whole consent path and the whole fail-safe
+  run in CI on a laptop.
+- ``command`` — ``policy`` only: a shell-out to the box's own start / stop /
+  status commands, from local config, never from the hub. No chunk interface,
+  so **not** endpoint-capable. ``lucen-legged`` is its deprecated alias.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+class AdapterError(Exception):
+    """The adapter refuses to start (bad file, missing config, robot said no)."""
+
+
+class Adapter(Protocol):
+    name: str
+
+    def start(self, model_path: Path, manifest: dict[str, Any], seconds: float) -> None: ...
+
+    def stop(self) -> None: ...
+
+    def status(self) -> dict[str, Any]: ...
+
+    def is_running(self) -> bool: ...
+
+
+@runtime_checkable
+class ChunkConsumer(Protocol):
+    """What an adapter must implement to consume a hub endpoint (M15)."""
+
+    name: str
+
+    def begin(self, contract: dict[str, Any], seconds: float) -> None: ...
+
+    def observe(self) -> dict[str, Any]: ...
+
+    def apply(self, chunk: Any, *, received_at: float) -> None: ...
+
+    def hold(self, reason: str) -> None: ...
+
+    def resume(self) -> None: ...
+
+    def stop(self) -> None: ...
+
+    def status(self) -> dict[str, Any]: ...
+
+    def is_running(self) -> bool: ...
+
+
+@runtime_checkable
+class StagedStart(Protocol):
+    """Optional: reach a safe state, then the default pose, before the policy (M17d)."""
+
+    def stage(self, name: str, interface: dict[str, Any] | None) -> None: ...
+
+
+@runtime_checkable
+class SafeStopAware(Protocol):
+    """Optional: let the robot card's `safety.safe_stop` choose what hold / stop mean."""
+
+    def set_safe_stop(self, mode: str) -> None: ...
+
+
+#: The methods the fail-safe rests on; missing any one of them means no endpoints.
+FAIL_SAFE_METHODS: tuple[str, ...] = ("begin", "observe", "apply", "hold", "resume", "stop")
+#: The stages a :class:`StagedStart` adapter is walked through, in order,
+#: before `start()` / `begin()` (which is the third stage: the policy).
+START_STAGES: tuple[str, ...] = ("safe", "default_pose")
+#: `interface.safety.safe_stop` values (docs/openapi.yaml, `EmbodimentSafety`).
+SAFE_STOP_MODES: tuple[str, ...] = ("hold", "zero_torque", "default_pose")
+
+# Re-exported below; imported late because both modules need `AdapterError`.
+from lucen_device.adapters.capabilities import (  # noqa: E402
+    Capabilities,
+    guarded_call,
+    inspect_adapter,
+    probe_fail_safe,
+)
+from lucen_device.adapters.registry import (  # noqa: E402
+    ADAPTER_ID_PATTERN,
+    ENTRY_POINT_GROUP,
+    AdapterRef,
+    LoadedAdapter,
+    available_adapters,
+    construct,
+    load_adapter,
+)
+
+
+def adapter_class(name: str) -> type[Any]:
+    """The class behind an adapter spec. **Imports it** — only for a spec somebody named."""
+    return load_adapter(name).klass
+
+
+def supports_endpoints(adapter: str | type[Any]) -> bool:
+    """True when the adapter class implements every fail-safe method — hold above all.
+
+    The static half of the capability; :func:`probe_fail_safe` is the other.
+    """
+    klass = adapter_class(adapter) if isinstance(adapter, str) else adapter
+    return "chunks" in inspect_adapter(klass).protocols
+
+
+def make_adapter(name: str, config: dict[str, Any]) -> Adapter:
+    adapter: Adapter = construct(load_adapter(name), config)
+    return adapter
+
+
+def make_chunk_consumer(name: str, config: dict[str, Any]) -> ChunkConsumer:
+    """The endpoint-use adapter, or :class:`AdapterError` naming the missing fail-safe."""
+    loaded = load_adapter(name)
+    found = inspect_adapter(loaded.klass)
+    if "chunks" not in found.protocols:
+        raise AdapterError(
+            f"adapter {loaded.name!r} cannot consume an endpoint: it does not implement "
+            f"{', '.join(found.missing_chunk_methods)} — the local hold/stop is mandatory "
+            "(invariant 3)"
+        )
+    adapter = construct(loaded, config)
+    assert isinstance(adapter, ChunkConsumer)
+    return adapter
+
+
+__all__ = [
+    "ADAPTER_ID_PATTERN",
+    "ENTRY_POINT_GROUP",
+    "FAIL_SAFE_METHODS",
+    "SAFE_STOP_MODES",
+    "START_STAGES",
+    "Adapter",
+    "AdapterError",
+    "AdapterRef",
+    "Capabilities",
+    "ChunkConsumer",
+    "LoadedAdapter",
+    "SafeStopAware",
+    "StagedStart",
+    "adapter_class",
+    "available_adapters",
+    "construct",
+    "guarded_call",
+    "inspect_adapter",
+    "load_adapter",
+    "make_adapter",
+    "make_chunk_consumer",
+    "probe_fail_safe",
+    "supports_endpoints",
+]

lucen_device/adapters/capabilities.py

@@ -0,0 +1,127 @@
+"""What an adapter can do — found in its code and by calling its fail-safe (M17d).
+
+Until M17d the hub kept a list of adapter names that may consume an endpoint
+(``{"virtual"}``). With adapters as plugins there is no such list to keep, so
+the capability is established **on the box**, in two halves:
+
+1. :func:`inspect_adapter` — *static*: which protocols the class implements.
+   ``chunks`` needs every method of the fail-safe (``begin / observe / apply /
+   hold / resume / stop``) plus ``status`` / ``is_running``, each a real
+   callable and not an abstract stub.
+2. :func:`probe_fail_safe` — *dynamic*: construct a fresh instance, call
+   ``hold("probe")``, then ``stop()``, each under a timeout. An adapter whose
+   ``hold()`` raises (``NotImplementedError`` included), hangs, or cannot even
+   be constructed is **not** endpoint-capable, and the reason is kept.
+
+That makes two demands on an adapter author, both stated in the docs:
+``hold()`` and ``stop()`` must be safe to call in any state — before
+``begin()``, twice in a row — and must never raise. They are the two calls the
+driver makes when everything else has already gone wrong.
+
+Neither half proves the robot stops. They prove the code path exists and runs;
+the enforcement that matters is in the link loop, which calls ``stop()`` when
+``hold()`` fails at the moment it is needed (:mod:`lucen_device.endpoint`).
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Final
+
+from lucen_device.adapters import FAIL_SAFE_METHODS, AdapterError
+
+POLICY_METHODS: Final[tuple[str, ...]] = ("start", "stop", "status", "is_running")
+CHUNK_METHODS: Final[tuple[str, ...]] = (*FAIL_SAFE_METHODS, "status", "is_running")
+#: How long `hold()` / `stop()` may take in the registration probe.
+PROBE_TIMEOUT_S: Final[float] = 5.0
+
+
+def _implements(klass: type[Any], method: str) -> bool:
+    found = getattr(klass, method, None)
+    return callable(found) and not getattr(found, "__isabstractmethod__", False)
+
+
+@dataclass(frozen=True)
+class Capabilities:
+    protocols: tuple[str, ...]
+    #: Which methods of the chunk protocol the class lacks (empty when `chunks` is present).
+    missing_chunk_methods: tuple[str, ...]
+
+
+def inspect_adapter(klass: type[Any]) -> Capabilities:
+    """The protocols `klass` implements, from its attributes. Runs nothing."""
+    protocols: list[str] = []
+    if all(_implements(klass, m) for m in POLICY_METHODS):
+        protocols.append("policy")
+    missing = tuple(m for m in CHUNK_METHODS if not _implements(klass, m))
+    if not missing:
+        protocols.append("chunks")
+    if _implements(klass, "stage"):
+        protocols.append("staged_start")
+    if _implements(klass, "set_safe_stop"):
+        protocols.append("safe_stop")
+    return Capabilities(protocols=tuple(protocols), missing_chunk_methods=missing)
+
+
+def guarded_call(call: Callable[[], Any], *, timeout: float) -> str | None:
+    """Run `call` on a worker thread. None when it returned; else why it did not.
+
+    Third-party code on the fail-safe path gets neither the benefit of the
+    doubt nor the chance to stall the loop: an exception is a failure, and so
+    is not returning in time (the thread is a daemon and is abandoned — there
+    is no safe way to kill it, and the caller's next move is `stop()`).
+    """
+    outcome: list[str | None] = []
+
+    def run() -> None:
+        try:
+            call()
+        except BaseException as exc:  # this IS the fault barrier, SystemExit included
+            outcome.append(f"raised {type(exc).__name__}: {exc}"[:200])
+        else:
+            outcome.append(None)
+
+    worker = threading.Thread(target=run, name="lucen-device-guarded", daemon=True)
+    worker.start()
+    worker.join(timeout)
+    if not outcome:
+        return f"did not return within {timeout:g} s"
+    return outcome[0]
+
+
+def probe_fail_safe(
+    factory: Callable[[], Any], *, timeout: float = PROBE_TIMEOUT_S
+) -> tuple[bool, str]:
+    """(passed, "passed" | "failed: <why>") — `hold()` then `stop()` on a fresh instance."""
+    try:
+        adapter = factory()
+    except AdapterError as exc:
+        return False, f"failed: {exc}"[:256]
+    except Exception as exc:  # third-party constructor
+        return False, f"failed: constructor raised {type(exc).__name__}: {exc}"[:256]
+    for method in ("hold", "stop"):
+        bound = getattr(adapter, method, None)
+        if not callable(bound):
+            return False, f"failed: no {method}()"
+        call = (lambda b=bound: b("probe")) if method == "hold" else bound
+        problem = guarded_call(call, timeout=timeout)
+        if problem is not None:
+            if method == "hold":  # leave nothing half-held behind a failed probe
+                stop = getattr(adapter, "stop", None)
+                if callable(stop):
+                    guarded_call(stop, timeout=timeout)
+            return False, f"failed: {method}() {problem}"[:256]
+    return True, "passed"
+
+
+__all__ = [
+    "CHUNK_METHODS",
+    "POLICY_METHODS",
+    "PROBE_TIMEOUT_S",
+    "Capabilities",
+    "guarded_call",
+    "inspect_adapter",
+    "probe_fail_safe",
+]