roboapi 0.4.2__py3-none-any.whl

roboapi/mcp.py

@@ -0,0 +1,497 @@
+"""MCP instructions, schemas and tool registration.
+
+Thin on purpose: every tool is a guarded pass-through to `Runtime`, which is where the
+mode and the mutual exclusion actually live.
+
+Two things are load-bearing about the docs here and neither is decoration:
+
+  * The workflow ("run a task with start_policy, poll get_observation") lives in the server
+    `instructions`, which the client MAY inject.
+  * Every expected failure carries a `hint` that is an imperative. That is what stops an LLM
+    from retrying blindly.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import time
+from typing import Literal
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict, Field
+
+from .errors import CalibrationError, PolicyUnavailable, RobotError
+from .images import preview_jpeg
+from .runtime import Runtime
+
+INSTRUCTIONS = """
+A single arm with a parallel gripper and a wrist fisheye RGB camera, using the specified model API.
+All observations and Cartesian targets use the training frame. Positions are metres;
+MCP roll/pitch/yaw use degrees. Relative translations follow training +X/+Y/+Z.
+The control point is the flange centre. Training Home is xyz [-0.13,-0.46,0.49],
+quaternion wxyz [0,0,1,0]. Model actions are absolute targets at a fixed 30 Hz.
+Training +Z is world up; +X/+Y lie in the horizontal plane, regardless of base mounting.
+
+If calibration is missing, use the roboapi-calibrate skill or Devices > Calibrate in the web interface.
+The operator teaches
+Home above a confirmed level reference surface, then points A, B and C through the native
+robot interface (UR PolyScope or Franka's guiding buttons). Keep Home orientation, gripper opening and
+the same fixed tool contact point for all three surface samples. A to B defines task +X;
+C lies off line AB. The plane normal toward Home defines +Z; +Y = +Z cross +X.
+Capturing C automatically returns the arm to recorded Home once; authorize this motion
+before beginning. Fresh feedback verifies the return, then inspect the axes and save.
+If an automatic return fails, use robot_calibration_return_home to retry after addressing
+the reported cause. Retain the captured points when retrying the return.
+Use robot_calibration_undo to remove the most recent record and return to its teaching step;
+earlier records and saved calibration remain intact. Undo sends no motion targets.
+Beginning teaching exits ordinary control. Franka prepares its load and native
+guiding in Programming mode using Desk pose feedback. Select one native translation axis
+after Home; these axes are not the training axes. FCI is used only for automatic returns.
+Release the guiding buttons before capture or axis changes; Home capture initially selects Z.
+Enable ordinary control separately after saving.
+
+Use observations to judge task outcomes. A completed action chunk means its action periods
+have ended; it does not guarantee target tracking or task success. Stop ends the current
+run; robot_disconnect closes device and model connections while idle and discards unfinished teaching.
+"""
+
+
+def _guard(runner: Runtime):
+    """The closed set of expected conditions returns a structured dict; everything else
+    raises and reaches the model as a tool error.
+
+    "Reaches the model" needs one step: the SDK forwards a `ToolError`'s text but scrubs any
+    other exception down to "Error executing tool <name>", which nobody can act on."""
+    from mcp.server.mcpserver.exceptions import ToolError
+
+    def decorate(fn):
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            _record(runner, fn.__name__, kwargs)
+            try:
+                return fn(*args, **kwargs)
+            except RobotError as exc:
+                _record(runner, fn.__name__, kwargs, error=exc.error)
+                return {"ok": False, "error": exc.error, "hint": exc.hint, "detail": str(exc)}
+            except PolicyUnavailable as exc:
+                _record(runner, fn.__name__, kwargs, error="policy_unavailable")
+                return {
+                    "ok": False,
+                    "error": "policy_unavailable",
+                    "hint": (
+                        "call robot_get_policy_config(); check the endpoint, model, and API key; "
+                        "use robot_configure_policy() to update the connection or key"
+                    ),
+                    "detail": str(exc),
+                }
+            except Exception as exc:
+                detail = f"{type(exc).__name__}: {exc}"
+                _record(runner, fn.__name__, kwargs, error=detail)
+                raise ToolError(detail) from exc
+
+        return wrapper
+
+    return decorate
+
+def _record(runner: Runtime, tool: str, kwargs: dict, error: str | None = None) -> None:
+    def safe(value):
+        if isinstance(value, BaseModel):
+            return safe(value.model_dump(exclude_none=True))
+        if isinstance(value, dict):
+            return {
+                str(key): (
+                    "<redacted>"
+                    if any(mark in str(key).lower() for mark in ("api_key", "token", "password", "secret"))
+                    else safe(item)
+                )
+                for key, item in value.items()
+            }
+        if isinstance(value, (list, tuple)):
+            return [safe(item) for item in value]
+        if isinstance(value, str):
+            return value[:60]
+        return value
+
+    runner.records.call_log.append({
+        "t": __import__("time").time(),
+        "tool": tool,
+        "args": {
+            k: (
+                "<redacted>"
+                if any(mark in k.lower() for mark in ("api_key", "token", "password", "secret"))
+                else safe(v)
+            )
+            for k, v in kwargs.items()
+        },
+        "error": error,
+    })
+
+class Waypoint(BaseModel):
+    """One point of a robot_move_waypoints path. The schema is the agent's contract: every
+    field is named with its unit, unknown fields are refused rather than ignored."""
+
+    model_config = ConfigDict(extra="forbid")
+    x: float | None = Field(None, description="metres, observation eef_frame")
+    y: float | None = Field(None, description="metres, observation eef_frame")
+    z: float | None = Field(None, description="metres, observation eef_frame")
+    roll: float | None = Field(None, description="degrees about training X")
+    pitch: float | None = Field(None, description="degrees about training Y")
+    yaw: float | None = Field(None, description="degrees about training Z")
+    gripper: float | None = Field(None, description="opening ratio, 0 closed .. 1 open, reached as this waypoint is reached")
+    relative: bool = Field(False, description="x/y/z/roll/pitch/yaw are offsets from the previous waypoint (the first: from the arm)")
+    blend: float | None = Field(None, description="metres. >0: round the corner and pass through without stopping, staying within this of the point (default 0.02). 0: reach the point exactly and stop there. Ignored on the last waypoint, which always stops")
+
+
+def make_server(runner: Runtime):
+    from mcp.server.mcpserver import Image, MCPServer
+    from mcp.types import ToolAnnotations
+
+    def _observe(with_image: bool) -> list:
+        obs, image = runner.observation(with_image=with_image)
+        out: list = [json.dumps(obs, indent=2)]
+        if image is not None:
+            out.append(Image(data=preview_jpeg(image), format="jpeg"))
+        return out
+
+    def _after(result: dict, with_image: bool) -> list:
+        """Return the completed operation and a fresh observation."""
+        obs, image = runner.observation(with_image=with_image)
+        out: list = [json.dumps({**result, "observation": obs}, indent=2)]
+        if image is not None:
+            out.append(Image(data=preview_jpeg(image), format="jpeg"))
+        return out
+
+    def _calibrate(action, data=None):
+        try:
+            return runner.calibration.action(action, data)
+        except RobotError:
+            raise
+        except (ValueError, OSError, RuntimeError) as exc:
+            raise CalibrationError(str(exc)) from exc
+
+    def _calibration_result(result: dict, with_image: bool) -> list:
+        """Return the safe calibration state and, when available, the current wrist image."""
+        if not with_image:
+            return [json.dumps(result, indent=2)]
+        out_result = dict(result)
+        image = None
+        if with_image and runner.emb.camera.live:
+            try:
+                image, age = runner.emb.get_camera()
+                out_result["image_age_ms"] = round(age * 1e3, 1)
+                out_result["image_available"] = True
+            except Exception:
+                out_result["image_available"] = False
+                out_result["image_missing"] = True
+        else:
+            out_result["image_available"] = False
+            if with_image:
+                out_result["image_missing"] = True
+        out: list = [json.dumps(out_result, indent=2)]
+        if image is not None:
+            out.append(Image(data=preview_jpeg(image), format="jpeg"))
+        return out
+
+    server = MCPServer(name="roboapi", instructions=INSTRUCTIONS)
+    guard = _guard(runner)
+    moves = lambda title: ToolAnnotations(title=title, destructive_hint=True, idempotent_hint=False)
+    reads = lambda title: ToolAnnotations(title=title, read_only_hint=True)
+    holds = lambda title: ToolAnnotations(title=title, destructive_hint=False, idempotent_hint=True)
+    configures = lambda title: ToolAnnotations(title=title, destructive_hint=True, idempotent_hint=True)
+
+    @server.tool(annotations=reads("Inspect manual teaching calibration"))
+    @guard
+    def robot_calibration_status(with_image: bool = False) -> list:
+        """Inspect the teaching phase, axes, local profile path and control gate; does not connect hardware."""
+        return _calibration_result(runner.calibration.status(), with_image)
+
+    @server.tool(annotations=configures("Begin Cartesian teaching"))
+    @guard
+    def robot_calibration_begin(safety_confirmed: bool, with_image: bool = False) -> list:
+        """Begin teaching; Franka prepares native guiding in Programming mode. Authorize the automatic return after C."""
+        return _calibration_result(_calibrate("acquire", {"confirmed": safety_confirmed}), with_image)
+
+    @server.tool(annotations=configures("Capture Home"))
+    @guard
+    def robot_calibration_accept_home(with_image: bool = False) -> list:
+        """Capture Home above the level reference surface, using the orientation kept for A/B/C."""
+        return _calibration_result(_calibrate("confirm_home"), with_image)
+
+    @server.tool(annotations=configures("Select a native guiding axis"))
+    @guard
+    def robot_calibration_set_guiding_axis(axis: Literal["x", "y", "z"], with_image: bool = False) -> list:
+        """Franka A/B/C teaching: allow one native translation axis and lock all rotations.
+
+        Release the arm buttons before changing axes. These are native guiding axes,
+        not the task axes that calibration will determine. Does not send motion targets.
+        """
+        return _calibration_result(_calibrate("set_guiding_axis", {"axis": axis}), with_image)
+
+    @server.tool(annotations=configures("Capture reference-plane A"))
+    @guard
+    def robot_calibration_accept_plane_a(with_image: bool = False) -> list:
+        """Read the first surface point, with Home orientation and a fixed tool contact point. No motion."""
+        return _calibration_result(_calibrate("confirm_plane_a"), with_image)
+
+    @server.tool(annotations=configures("Capture reference-plane B"))
+    @guard
+    def robot_calibration_accept_plane_b(with_image: bool = False) -> list:
+        """Read B on the same level surface from A toward task +X, keeping orientation and contact point. No motion."""
+        return _calibration_result(_calibrate("confirm_plane_b"), with_image)
+
+    @server.tool(annotations=moves("Capture reference-plane C and return Home"))
+    @guard
+    def robot_calibration_accept_plane_c(with_image: bool = False) -> list:
+        """Read C off line AB on the same surface, then return Home and verify fresh feedback. MOVES THE ARM."""
+        return _calibration_result(_calibrate("confirm_plane_c"), with_image)
+
+    @server.tool(annotations=moves("Retry return Home"))
+    @guard
+    def robot_calibration_return_home(with_image: bool = False) -> list:
+        """Retry an interrupted automatic Home return. MOVES THE ARM; retains all plane samples."""
+        return _calibration_result(_calibrate("return_home"), with_image)
+
+    @server.tool(annotations=moves("Return to reference-plane A"))
+    @guard
+    def robot_calibration_return_a(with_image: bool = False) -> list:
+        """Return to captured A during B/C teaching and resume read-only sampling. MOVES THE ARM."""
+        return _calibration_result(_calibrate("return_a"), with_image)
+
+    @server.tool(annotations=configures("Save taught calibration"))
+    @guard
+    def robot_calibration_finish(save_confirmed: bool, with_image: bool = False) -> list:
+        """Save the calibration after a verified Home return. No motion or control connection."""
+        return _calibration_result(_calibrate("save", {"confirmed": save_confirmed}), with_image)
+
+    @server.tool(annotations=ToolAnnotations(title="Undo the last calibration record", destructive_hint=True, idempotent_hint=False))
+    @guard
+    def robot_calibration_undo(with_image: bool = False) -> list:
+        """Remove the last unsaved record and return to its teaching step without moving.
+
+        Retains earlier records and the saved calibration. After C or the Home return,
+        removes C and its draft so the operator can record C again.
+        """
+        return _calibration_result(_calibrate("undo"), with_image)
+
+    @server.tool(annotations=moves("Enable calibrated hardware control"))
+    @guard
+    def robot_calibration_enable_control(safety_confirmed: bool, initialization_confirmed: bool,
+                                         with_image: bool = True) -> list:
+        """Acquire real control; may upload scripts and initialize/open the gripper.
+
+        Requires separate explicit on-site authorization and a valid installation calibration.
+        Does not issue reset/motion targets, but acquisition itself can actuate hardware.
+        """
+        return _calibration_result(_calibrate("enable_control", {"confirmed": safety_confirmed, "initialization_confirmed": initialization_confirmed}), with_image)
+
+    @server.tool(annotations=reads("Inspect direction check readiness"))
+    @guard
+    def robot_get_direction_check() -> dict:
+        """Read proximity to calibrated Home and the active direction check. No motion."""
+        return runner.direction_check_status()
+
+    @server.tool(annotations=moves("Check calibrated movement directions"))
+    @guard
+    def robot_check_direction(direction: Literal["forward", "left", "up", "home"],
+                              with_image: bool = True) -> list:
+        """From calibrated Home, translate 5 cm and rotate 30 degrees, then return.
+
+        Forward is task -Y with roll -30; left is +X with pitch -30; up is +Z
+        with yaw +30. Rotations are about fixed task axes at the flange centre.
+        Uses the policy full-pose execution and calibrated coordinate mapping.
+        The gripper opening is held throughout.
+        'home' only returns to Home with the current gripper opening. Requires
+        enabled idle control. Stop abandons the remaining path, including return.
+        Motion completion is not a judgment that the observed direction is correct.
+        """
+        return _after(runner.check_direction(direction), with_image)
+
+    @server.tool(annotations=moves("Disconnect devices"))
+    @guard
+    def robot_disconnect() -> dict:
+        """Disconnect devices while idle and discard unfinished teaching. Retain saved calibration."""
+        return runner.release()
+
+    @server.tool(annotations=reads("Inspect policy configuration"))
+    @guard
+    def robot_get_policy_config() -> dict:
+        """Return the model connection, chunk wait in seconds and credential status.
+
+        These settings are shared by web and MCP runs. Never returns the API key.
+        """
+        return runner.policy_config()
+
+    @server.tool(annotations=configures("Configure the policy"))
+    @guard
+    def robot_configure_policy(url: str, model: str, inter_chunk_pause_s: float,
+                               api_key: str | None = None) -> dict:
+        """Save the shared model connection and action-chunk wait while idle, without motion.
+
+        Read robot_get_policy_config first and retain values that should stay unchanged.
+        inter_chunk_pause_s is a non-negative wait before sampling the next observation;
+        the default is 0.5 seconds. Runs have no automatic time limit. Omit api_key to keep
+        the saved key. Connection is verified against /models before settings take effect.
+        A rejected update preserves previous settings and credentials. Use a trusted connection.
+        """
+        return runner.configure_policy(url=url, model=model, inter_chunk_pause_s=inter_chunk_pause_s,
+                                       api_key=api_key)
+
+    @server.tool(annotations=reads("Observe the robot"))
+    @guard
+    def robot_get_observation(with_image: bool = True) -> list:
+        """The robot's state and its wrist camera view, sampled at one instant.
+
+        Returns mode / alive / instruction / eef_pose / gripper_state / progress, plus the
+        current wrist image. Prefer this over any other way of checking progress; set
+        with_image=False only for a cheap liveness poll.
+        """
+        return _observe(with_image)
+
+    @server.tool(annotations=moves("Start the policy"))
+    @guard
+    def robot_start_policy(instruction: str) -> dict:
+        """Start the VLA policy on a task, e.g. "pick up the banana".
+
+        RETURNS IMMEDIATELY. The policy keeps running in the background until you call
+        robot_stop() or a fault ends the run. There is no automatic time limit. Watch it with
+        robot_get_observation().
+        """
+        return runner.start(instruction)
+
+    @server.tool(annotations=holds("Change the instruction"))
+    @guard
+    def robot_set_instruction(instruction: str) -> dict:
+        """Change what the RUNNING policy is trying to do, without stopping it.
+
+        Applies at the next inference, so allow roughly one chunk. For anything urgent use
+        robot_stop() instead. Meant for a loop that is already running: robot_start_policy
+        takes the task itself, so there is nothing to set beforehand.
+        """
+        return runner.set_instruction(instruction)
+
+    @server.tool(annotations=holds("Pause the policy"))
+    @guard
+    def robot_pause(with_image: bool = True) -> list:
+        """Hold position: stop sending new targets, keep the arm where it is.
+
+        Returns the observation from where it stopped.
+        """
+        return _after(runner.pause(), with_image)
+
+    @server.tool(annotations=holds("Resume the policy"))
+    @guard
+    def robot_resume() -> dict:
+        """Resume a paused policy. It re-observes before acting."""
+        return runner.resume()
+
+    @server.tool(annotations=holds("Stop the policy"))
+    @guard
+    def robot_stop(with_image: bool = True) -> list:
+        """Stop the policy loop. Takes effect within one frame; the arm holds position.
+
+        Returns the observation from where it stopped.
+        """
+        return _after(runner.stop(), with_image)
+
+    @server.tool(annotations=moves("Move to a pose"))
+    @guard
+    def robot_move_to_pose(x: float | None = None, y: float | None = None, z: float | None = None,
+                           roll: float | None = None, pitch: float | None = None,
+                           yaw: float | None = None, gripper: float | None = None,
+                           relative: bool = False, with_image: bool = True) -> list:
+        """Move the gripper to a pose you choose. MOVES THE ARM.
+
+        Positions x/y/z are METRES in the training frame; roll/pitch/yaw are DEGREES about
+        the training X/Y/Z axes. Any axis you leave out keeps its current value, so you only pass
+        what you want to change.
+
+        relative=False (default): the values are absolute.
+            robot_move_to_pose(x=0.4, y=-0.3)      -> go there, same height, same orientation
+        relative=True: the values are offsets from where the arm is now.
+            robot_move_to_pose(z=0.05, relative=True)   -> lift 5 cm
+            robot_move_to_pose(yaw=15, relative=True)   -> rotate 15 deg about training Z
+
+        `gripper` is an opening ratio: 0.0 closed, 1.0 open, omitted holds. It is ALWAYS
+        absolute -- `relative` applies to the pose only. The gripper is driven along the path
+        together with the pose, exactly as a policy chunk drives them, so it arrives as the
+        move arrives rather than after it:
+            robot_move_to_pose(x=0.4, z=0.2, gripper=1.0)  -> travel there, opening on the way
+            robot_move_to_pose(gripper=0.0)                -> close in place
+        A grasp is therefore two calls: reach the object open, then close. Do not close on the
+        approach to something you mean to grip -- the fingers meet it before the pose does.
+
+        The move follows a smooth Cartesian path at a fixed, conservative speed, and stays
+        compliant throughout, so it yields if it touches something. Speed is not adjustable.
+        Nothing checks that the pose is reachable or clear -- keep moves small. The result
+        carries `target` (planned) and `observation` (measured once the arm came to rest, with
+        the wrist image): compare them to see whether it arrived or was stopped short.
+        with_image=False skips the image on intermediate steps of a sequence. For a path of
+        several points use robot_move_waypoints instead. Only available while the policy loop
+        is stopped.
+        """
+        return _after(runner.move_to_pose(x=x, y=y, z=z, roll=roll, pitch=pitch, yaw=yaw,
+                                          gripper=gripper, relative=relative), with_image)
+
+    @server.tool(annotations=moves("Move along waypoints"))
+    @guard
+    def robot_move_waypoints(waypoints: list[Waypoint], with_image: bool = True) -> list:
+        """Drive the arm and gripper through several waypoints as ONE continuous motion.
+        MOVES THE ARM.
+
+        Use this instead of a series of robot_move_to_pose calls: one call, one path, no stop
+        between points. Same units and frame as robot_move_to_pose. In each waypoint an
+        omitted field holds the previous waypoint's value, and relative=True makes the pose
+        fields offsets from the PREVIOUS waypoint (the first: from where the arm is now), so a
+        path needs no arithmetic:
+            [{"z": 0.05, "relative": true},     -- lift 5 cm
+             {"x": 0.10, "relative": true},     -- 10 cm along +x
+             {"z": -0.05, "relative": true},    -- lower 5 cm
+             {"gripper": 0.0}]                  -- close, in place
+
+        `blend` (metres) says what happens AT a waypoint. > 0 (default 0.02): the path rounds
+        the corner and passes through without stopping, staying within `blend` of the point,
+        on the inside of the corner. 0: the arm reaches the point exactly and comes to rest.
+        The last waypoint always comes to rest, whatever its blend says. The path never bulges
+        outside the polyline you gave, so it cannot dip past a point; give a point you must
+        reach exactly, such as the last one before contact, blend=0.
+
+        The gripper value at a waypoint is reached as the arm reaches it, spread over the leg
+        before it. To move the gripper with the arm STILL -- a grasp or a release -- repeat the
+        point with the new gripper value, as in the example: a zero-length leg is a dwell.
+
+        Speed is fixed and conservative, the move stays compliant throughout, and nothing
+        checks reachability or clearance: keep legs short and the path clear. The result
+        carries each waypoint's planned pose and gripper, `reached` (how many were passed:
+        fewer than given means it was stopped), and `observation` from where the arm came to
+        rest. Only available while the policy loop is stopped.
+        """
+        return _after(runner.move_waypoints([w.model_dump(exclude_none=True) for w in waypoints]),
+                      with_image)
+
+    @server.tool(annotations=moves("Reset to home"))
+    @guard
+    def robot_reset(with_image: bool = True) -> list:
+        """Open the gripper and return to the training Home pose.
+
+        UR e-Series requests force sensor zeroing on arrival, without an extra wait.
+        A zeroing failure is a warning and does not fail Home.
+
+        MOVES THE ARM. Use it before starting a task, or to recover from a bad pose. Returns
+        the observation from home.
+        """
+        return _after(runner.reset(), with_image)
+
+    @server.tool(annotations=moves("Recover the arm"))
+    @guard
+    def robot_recover(with_image: bool = True) -> list:
+        """Bring a non-live arm back: stop the loop, reconnect, return to the training Home pose.
+
+        MOVES THE ARM, and the user is asked to approve it. Call this when `alive` is false.
+        If it keeps failing, a person has to clear the robot physically (emergency stop,
+        safeguard, or an obstruction) -- say so rather than retrying. Returns the observation
+        from home.
+        """
+        return _after(runner.recover(), with_image)
+
+    return server

roboapi/motion.py

@@ -0,0 +1,125 @@
+"""Shared 30 Hz Cartesian dispatch for policy actions, manual moves and calibration."""
+
+from contextlib import nullcontext
+import time
+
+import numpy as np
+
+from . import geometry as geo
+from .semantics import ACTION_DT
+
+
+def workspace_targets(poses, workspace):
+    """Project position targets onto the box without changing orientation or input data."""
+    values = np.asarray(poses, dtype=np.float64)
+    if values.ndim != 2 or values.shape[1] != 7 or not np.all(np.isfinite(values)):
+        raise ValueError("poses must be an Nx7 finite array")
+    if workspace is None or not workspace.enabled:
+        return values
+    values = values.copy()
+    values[:, :3] = np.clip(values[:, :3], workspace.min_xyz_m, workspace.max_xyz_m)
+    return values
+
+
+def pose_reached(target, measured):
+    position, angle = geo.pose_delta(target, measured)
+    return position <= 0.05 and angle <= np.deg2rad(20)
+
+
+def wait_for_pose(arm, target, should_stop=None, *, name="Home"):
+    """Verify an explicit return using live Cartesian feedback."""
+    deadline = time.monotonic() + 10.0
+    while True:
+        if should_stop is not None and should_stop():
+            raise RuntimeError(f"Return {name} was stopped")
+        if not arm.live:
+            raise RuntimeError(arm.last_error or "Arm control is unavailable.")
+        pose = arm.get_eef_pose()
+        if pose_reached(target, pose):
+            return pose
+        if time.monotonic() >= deadline:
+            raise ValueError(f"{name} was not reached. Check the robot and retry Return {name}.")
+        wait_until(time.monotonic() + 0.02, should_stop)
+
+
+def wait_until(deadline, should_stop=None) -> bool:
+    """Wait on a monotonic deadline, returning False when interrupted."""
+    while True:
+        if should_stop is not None and should_stop():
+            return False
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            return True
+        time.sleep(min(0.005, remaining))
+
+
+def dispatch(arm, poses, grips=None, *, gripper=None, should_stop=None, on_executed=None,
+             command_lock=None, position_only=False, workspace=None) -> dict:
+    """Execute every target, including the final target's full action period.
+
+    Poses use the coordinate frame exposed by the supplied arm: the mapped arm
+    for ordinary motion, or the native arm for installation calibration.
+    """
+    dt = ACTION_DT
+    command_lock = command_lock if command_lock is not None else nullcontext()
+    poses = workspace_targets(poses, workspace)
+    twists = geo.pose_twists(poses, dt)
+    if workspace is not None and workspace.enabled:
+        linear = twists[:, :3]
+        # Central differences must not feed velocity through a box face.
+        outward = ((poses[:, :3] <= workspace.min_xyz_m) & (linear < 0)
+                   | (poses[:, :3] >= workspace.max_xyz_m) & (linear > 0))
+        linear[outward] = 0.0
+    t0 = time.monotonic()
+    late = 0
+    executed = 0
+    last_sent_at = t0
+    n = len(poses)
+    for i in range(n):
+        if should_stop is not None and should_stop():
+            break
+        deadline = t0 + i * dt
+        now = time.monotonic()
+        if now < deadline:
+            if not wait_until(deadline, should_stop):
+                break
+        elif now > deadline + dt:
+            late += 1
+        if should_stop is not None and should_stop():
+            break
+        with command_lock:
+            if should_stop is not None and should_stop():
+                break
+            arm.servo_pose(poses[i], twists[i], position_only=position_only)
+            if grips is not None:
+                gripper.set_ratio(float(grips[i]))
+        executed += 1
+        if on_executed is not None:
+            on_executed(executed)
+        last_sent_at = time.monotonic()
+    aborted = executed < n
+    if n and not aborted:
+        # The final target owns a full action period too, including when dispatch ran
+        # late. Sending N targets spans only N-1 intervals; it is not completion.
+        deadline = max(t0 + n * dt, last_sent_at + dt)
+        aborted = not wait_until(deadline, should_stop)
+    dispatch_done = time.monotonic()
+    # A servo target is not an arrival guarantee, especially with contact or
+    # compliant control. Observe after the final commanded period, without
+    # requiring the measured pose to equal the policy's nominal target.
+    endpoint_error = {}
+    if n and not aborted:
+        position_error, orientation_error = geo.pose_delta(arm.get_eef_pose(), poses[-1])
+        endpoint_error = {
+            "endpoint_position_error_m": round(position_error, 5),
+            "endpoint_orientation_error_deg": round(float(np.degrees(orientation_error)), 2),
+        }
+    return {
+        "executed": executed,
+        "late_frames": late,
+        "elapsed_s": round(time.monotonic() - t0, 3),
+        "dispatch_s": round(dispatch_done - t0, 3),
+        "action_period_completed_at_monotonic": dispatch_done if not aborted else None,
+        **endpoint_error,
+        "aborted": aborted,
+    }

roboapi/naming.py

@@ -0,0 +1,7 @@
+"""Display names; technical namespaces are fixed by the package migration."""
+
+import json
+from importlib.resources import files
+
+NAMES = json.loads(files("roboapi").joinpath("product-names.json").read_text(encoding="utf-8"))
+PRODUCT_NAME = NAMES["product"]["name"]

roboapi/operations.py

@@ -0,0 +1,45 @@
+"""One interruptible writer shared by task and installation operations."""
+
+import functools
+import threading
+
+from .errors import LoopRunning
+
+
+class OperationGate:
+    """One non-blocking writer plus an abort signal that STOP sets without waiting."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self.abort = threading.Event()
+
+    def acquire(self) -> bool:
+        return self._lock.acquire(blocking=False)
+
+    def release(self) -> None:
+        self._lock.release()
+
+    def interrupt(self) -> None:
+        self.abort.set()
+
+    def reset_abort(self) -> None:
+        self.abort.clear()
+
+    @property
+    def busy(self) -> bool:
+        return self._lock.locked()
+
+
+def exclusive(method):
+    """Runtime commands share one writer; STOP never waits for this gate."""
+    @functools.wraps(method)
+    def guarded(self, *args, **kwargs):
+        if not self.operations.acquire():
+            raise LoopRunning("another operation is in progress; stop it or wait for completion")
+        try:
+            return method(self, *args, **kwargs)
+        finally:
+            self.operations.release()
+    return guarded
+
+