awp-python 0.1.0a1__py3-none-any.whl

awp_sim/audit.py

@@ -0,0 +1,138 @@
+"""The per-session audit log (spec/safety/audit-log): JSON Lines, redacted, hash-chained."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import IO, Any
+
+from awp.jsonrpc import Message
+
+CREDENTIAL_KEYS = frozenset({"session_token", "transfer_token", "snapshot_token"})
+
+
+def redacted(value: Any) -> str:
+    digest = hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest()
+    return f"[redacted:sha256:{digest[:8]}]"
+
+
+def redact(msg: Message, paths: Iterable[str] = ()) -> Message:
+    """Replace credentials and `redact_paths` values, relative to params or result (AWP-AUD-006)."""
+
+    def walk(node: Any) -> Any:
+        if isinstance(node, dict):
+            return {k: redacted(v) if k in CREDENTIAL_KEYS else walk(v) for k, v in node.items()}
+        if isinstance(node, list):
+            return [walk(v) for v in node]
+        return node
+
+    out: Message = walk(msg)
+    for pointer in paths:
+        for root in ("params", "result"):
+            _redact_pointer(out.get(root), pointer)
+    return out
+
+
+def _redact_pointer(node: Any, pointer: str) -> None:
+    parts = [p.replace("~1", "/").replace("~0", "~") for p in pointer.lstrip("/").split("/")]
+    for part in parts[:-1]:
+        if isinstance(node, dict):
+            node = node.get(part)
+        elif isinstance(node, list) and part.isdigit() and int(part) < len(node):
+            node = node[int(part)]
+        else:
+            return
+    last = parts[-1]
+    if isinstance(node, dict) and last in node:
+        node[last] = redacted(node[last])
+    elif isinstance(node, list) and last.isdigit() and int(last) < len(node):
+        node[int(last)] = redacted(node[int(last)])
+
+
+class AuditLog:
+    """Writes `<directory>/<session_id>.jsonl`, one audit record per line (AWP-AUD-001..007).
+
+    Frames are recorded as their header plus the SHA-256 of the payload, so a log is an audit
+    record, not a replay bundle. With the inline binding frames travel as control messages; they
+    are still logged by hash, as frames on any other channel would be.
+    """
+
+    def __init__(
+        self, directory: Path | str, *, redact_paths: Iterable[str] = (), bundle: bool = False
+    ) -> None:
+        self.bundle = bundle  # a replay bundle: full payloads and the initial state (AWP-AUD-007)
+        self.directory = Path(directory)
+        self.directory.mkdir(parents=True, exist_ok=True)
+        self.redact_paths = list(redact_paths)
+        self._files: dict[str, IO[str]] = {}
+        self._prev: dict[str, str] = {}
+
+    def open(self, session_id: str, header: dict[str, Any]) -> None:
+        if not self.bundle:  # only a replay bundle carries the initial snapshot
+            header = {
+                k: v for k, v in header.items() if k not in ("snapshot_token", "initial_state")
+            }
+        self._files[session_id] = (self.directory / f"{session_id}.jsonl").open(
+            "a", encoding="utf-8"
+        )
+        self._write(
+            session_id,
+            {
+                "class": "replay_bundle" if self.bundle else "audit_record",
+                "ts_mono_ns": 0,
+                "direction": "world",
+                "kind": "header",
+                "body": header,
+            },
+        )
+
+    def record(self, session_id: str, ts_mono_ns: int, direction: str, msg: Message) -> None:
+        if session_id not in self._files:
+            return
+        if msg.get("method") in ("obs.frame", "cmd.frame"):
+            params = msg["params"]
+            payload = base64.b64decode(params.get("payload_b64", ""))  # the payload, not its text
+            keep = self.bundle  # a bundle keeps what the agent saw; a record, only its hash
+            body: dict[str, Any] = {k: v for k, v in params.items() if keep or k != "payload_b64"}
+            body["method"] = msg["method"]
+            body["payload_sha256"] = hashlib.sha256(payload).hexdigest()
+            kind = "frame"
+        else:
+            body = redact(msg, self.redact_paths)
+            kind = "message"
+        self._write(
+            session_id,
+            {"ts_mono_ns": ts_mono_ns, "direction": direction, "kind": kind, "body": body},
+        )
+
+    def close(self, session_id: str) -> None:
+        f = self._files.pop(session_id, None)
+        self._prev.pop(session_id, None)
+        if f is not None:
+            f.close()
+
+    def close_all(self) -> None:
+        for session_id in list(self._files):
+            self.close(session_id)
+
+    def _write(self, session_id: str, record: dict[str, Any]) -> None:
+        record["prev_hash"] = self._prev.get(session_id)
+        line = json.dumps(record, separators=(",", ":"), ensure_ascii=False)
+        self._prev[session_id] = hashlib.sha256(line.encode()).hexdigest()
+        f = self._files[session_id]
+        f.write(line + "\n")
+        f.flush()
+
+
+def verify_chain(lines: Iterable[str]) -> bool:
+    """True if every record's prev_hash is the SHA-256 of the line before it (AWP-AUD-003)."""
+    prev: str | None = None
+    for line in lines:
+        record = json.loads(line)
+        if record.get("prev_hash") != prev:
+            return False
+        prev = hashlib.sha256(line.rstrip("\n").encode()).hexdigest()
+    return True

awp_sim/cli.py

@@ -0,0 +1,238 @@
+"""The `awp-sim` command."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import signal
+import ssl
+import sys
+from pathlib import Path
+
+from . import __version__, scenarios
+from .audit import AuditLog
+from .config import FEATURES, WorldConfig
+from .server import Server
+from .world import World
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="awp-sim", description="Agent World Protocol reference world.")
+    p.add_argument("--version", action="version", version=f"awp-sim {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("serve", help="run the reference world")
+    s.add_argument("--mode", choices=["streaming", "lockstep"], default="streaming")
+    s.add_argument("--host", default="127.0.0.1")
+    s.add_argument("--port", type=int, default=8710)
+    s.add_argument(
+        "--token",
+        default=os.environ.get("AWP_SIM_TOKEN"),
+        help="require this bearer token (default: $AWP_SIM_TOKEN)",
+    )
+    s.add_argument("--tls-cert", type=Path)
+    s.add_argument("--tls-key", type=Path)
+    s.add_argument(
+        "--insecure", action="store_true", help="allow a non-loopback bind without a token or TLS"
+    )
+    s.add_argument(
+        "--audit-dir",
+        type=Path,
+        default=Path("awp-audit"),
+        help="per-session audit logs (AWP-AUD-001; default: ./awp-audit)",
+    )
+    s.add_argument(
+        "--no-audit",
+        action="store_true",
+        help="disable the audit log (not conformant; for development only)",
+    )
+    s.add_argument("--record-dir", type=Path, help="write per-session wire traces here")
+    s.add_argument(
+        "--replay-dir",
+        type=Path,
+        help="write replay bundles instead of audit records (lockstep, --features sim)",
+    )
+    s.add_argument(
+        "--features",
+        default="",
+        help=f"comma-separated features beyond Core: {', '.join(sorted(FEATURES))}",
+    )
+    s.add_argument(
+        "--approver-token",
+        default=os.environ.get("AWP_SIM_APPROVER_TOKEN"),
+        help="bearer token of approver connections (with --features approval)",
+    )
+    s.add_argument("--approval-timeout-ms", type=int, default=60000)
+    s.add_argument(
+        "--stream-binding",
+        choices=["inline", "ws"],
+        default="inline",
+        help="offer frames on a ws stream connection as well as inline (AWP-TRN-003)",
+    )
+    for name, default in (
+        ("watchdog-ms", 2000),
+        ("heartbeat-ms", 5000),
+        ("reconnect-window-ms", 30000),
+        ("tick-ms", 20),
+        ("max-duration-ms", 10000),
+    ):
+        s.add_argument(f"--{name}", type=int, default=default)
+    s.add_argument("--log-level", default="INFO")
+
+    sc = sub.add_parser("scenarios", help="run the scripted scenarios")
+    sc.add_argument("names", nargs="*", help="scenarios to run (default: all)")
+    sc.add_argument("--list", action="store_true", help="list scenarios and exit")
+    sc.add_argument("--out", type=Path, help="write traces and report.json here")
+
+    d = sub.add_parser("demo", help="drive a running world with a scripted agent")
+    d.add_argument("--url", default="ws://127.0.0.1:8710")
+    d.add_argument("--token", default=os.environ.get("AWP_SIM_TOKEN"))
+
+    r = sub.add_parser("replay", help="replay a replay bundle and compare (AWP-REP-003)")
+    r.add_argument("bundle", type=Path)
+
+    m = sub.add_parser("manifest", help="print the world manifest")
+    m.add_argument("--mode", choices=["streaming", "lockstep"], default="streaming")
+    m.add_argument("--features", default="")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "manifest":
+        features = frozenset(f for f in args.features.split(",") if f)
+        print(json.dumps(WorldConfig(mode=args.mode, features=features).manifest(), indent=2))
+        return 0
+    if args.command == "scenarios":
+        return _scenarios(args)
+    if args.command == "replay":
+        from .replay import replay
+
+        outcome = replay(args.bundle)
+        if outcome.reproduced:
+            print(f"reproduced {outcome.frames} frames and {outcome.transitions} transitions")
+            return 0
+        print(f"not reproduced: {outcome.difference}", file=sys.stderr)
+        return 1
+    if args.command == "demo":
+        from websockets.exceptions import InvalidHandshake
+
+        from awp.errors import AwpError
+
+        from .demo import run_demo
+
+        try:
+            asyncio.run(run_demo(args.url, token=args.token))
+        except (OSError, InvalidHandshake, AwpError, TimeoutError) as err:
+            print(f"awp-sim demo: {err}", file=sys.stderr)
+            return 1
+        return 0
+    return _serve(args)
+
+
+def _scenarios(args: argparse.Namespace) -> int:
+    if args.list:
+        for name, (description, _) in scenarios.SCENARIOS.items():
+            print(f"{name:24} {description}")
+        return 0
+    unknown = [n for n in args.names if n not in scenarios.SCENARIOS]
+    if unknown:
+        print(f"unknown scenario(s): {', '.join(unknown)}", file=sys.stderr)
+        return 2
+    results = scenarios.run_all(args.names or None)
+    for r in results:
+        metrics = " ".join(f"{k}={v}" for k, v in r.metrics.items())
+        print(f"{'PASS' if r.passed else 'FAIL'}  {r.name:24} {metrics}")
+        for check, ok in r.checks:
+            if not ok:
+                print(f"      ✗ {check}")
+        if r.error:
+            print(f"      ✗ {r.error}")
+    if args.out:
+        scenarios.write(results, args.out)
+        print(f"traces and report written to {args.out}")
+    return 0 if all(r.passed for r in results) else 1
+
+
+def _serve(args: argparse.Namespace) -> int:
+    logging.basicConfig(
+        level=args.log_level.upper(), format="%(asctime)s %(levelname)s %(message)s"
+    )
+    try:
+        config = _config(args)
+    except ValueError as err:
+        print(f"awp-sim: {err}", file=sys.stderr)
+        return 2
+    tls = None
+    if args.tls_cert:
+        tls = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+        tls.load_cert_chain(args.tls_cert, args.tls_key)
+    return _run_server(args, config, tls)
+
+
+def _config(args: argparse.Namespace) -> WorldConfig:
+    return WorldConfig(
+        mode=args.mode,
+        watchdog_ms=args.watchdog_ms,
+        heartbeat_interval_ms=args.heartbeat_ms,
+        reconnect_window_ms=args.reconnect_window_ms,
+        tick_ms=args.tick_ms,
+        max_duration_ms=args.max_duration_ms,
+        features=frozenset(f for f in args.features.split(",") if f),
+        approval_timeout_ms=args.approval_timeout_ms,
+    )
+
+
+def _run_server(args: argparse.Namespace, config: WorldConfig, tls: ssl.SSLContext | None) -> int:
+    if args.replay_dir is not None:
+        if not config.has("sim"):
+            print("awp-sim: --replay-dir needs --mode lockstep --features sim", file=sys.stderr)
+            return 2
+        audit: AuditLog | None = AuditLog(args.replay_dir, bundle=True)
+    else:
+        audit = None if args.no_audit else AuditLog(args.audit_dir)
+    world = World(config, audit=audit)
+    try:
+        server = Server(
+            world,
+            host=args.host,
+            port=args.port,
+            token=args.token,
+            ssl_context=tls,
+            allow_insecure=args.insecure,
+            record_dir=args.record_dir,
+            stream_binding=args.stream_binding == "ws",
+            approver_token=args.approver_token,
+        )
+    except ValueError as err:
+        print(f"awp-sim: {err}", file=sys.stderr)
+        return 2
+
+    async def run() -> None:
+        stop = asyncio.Event()
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            with contextlib.suppress(NotImplementedError):
+                loop.add_signal_handler(sig, stop.set)
+        # Operator e-stop: SIGUSR1 engages, SIGUSR2 releases (AWP-EVT-002).
+        for name, handler in (("SIGUSR1", server.engage_estop), ("SIGUSR2", server.release_estop)):
+            usr = getattr(signal, name, None)
+            if usr is not None:
+                loop.add_signal_handler(usr, handler)
+        async with server:
+            await stop.wait()
+
+    try:
+        asyncio.run(run())
+    finally:
+        if audit is not None:
+            audit.close_all()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

awp_sim/config.py

@@ -0,0 +1,225 @@
+"""Reference world configuration and the manifest it declares."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from . import __version__
+
+Mode = Literal["lockstep", "streaming"]
+
+EMBODIMENT = "arm_01"
+HOME: tuple[float, float, float] = (0.0, 0.0, 0.4)
+PARK: tuple[float, float, float] = (0.0, 0.0, 0.25)
+SERVO_CHANNEL = "servo_arm"
+
+# Beyond Core, each off by default: task (AWP-TSK), approval of `park` (AWP-APR), blend preemption
+# (AWP-PRE-004), embodiment transfer (AWP-EMB-003), sim-profile seeding, snapshots, and replay
+# (AWP-REP, lockstep), and a servo command channel (AWP-CMD, streaming).
+FEATURES = frozenset({"task", "approval", "blend", "transfer", "sim", "servo"})
+
+
+@dataclass(frozen=True, slots=True)
+class WorldConfig:
+    mode: Mode = "streaming"
+    heartbeat_interval_ms: int = 5000
+    reconnect_window_ms: int = 30000
+    watchdog_ms: int = 2000
+    max_basis_age_ms: int = 500
+    max_abort_ms: int = 1500
+    max_duration_ms: int = 10000
+    tick_ms: int = 20
+    proprio_hz: float = 100.0
+    state_hz: float = 10.0
+    telemetry_interval_ms: int = 1000
+    progress_interval_ms: int = 200
+    aabb_m: tuple[tuple[float, float, float], tuple[float, float, float]] = (
+        (-0.5, -0.5, 0.0),
+        (0.5, 0.5, 0.8),
+    )
+    max_velocity_mps: float = 0.5
+    max_action_rate_hz: float = 20.0
+    accel_mps2: float = 2.0
+    features: frozenset[str] = frozenset()
+    approval_timeout_ms: int = 60000
+    servo_watchdog_ms: int = 200
+    servo_hz: float = 200.0
+    extensions: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.watchdog_ms > self.reconnect_window_ms:
+            raise ValueError("watchdog_ms must be ≤ reconnect_window_ms (AWP-SAF-003)")
+        if self.heartbeat_interval_ms < 100:
+            raise ValueError("heartbeat_interval_ms must be ≥ 100")
+        unknown = set(self.features) - FEATURES
+        if unknown:
+            raise ValueError(f"unknown features {sorted(unknown)}; known: {sorted(FEATURES)}")
+        if "servo" in self.features and self.mode != "streaming":
+            raise ValueError("command channels are streaming-only (AWP-CMD-001)")
+        if "sim" in self.features and self.mode != "lockstep":
+            raise ValueError("the sim feature needs lockstep: its determinism is lockstep's")
+
+    @property
+    def envelope(self) -> dict[str, Any]:
+        return {
+            "embodiment": EMBODIMENT,
+            "spatial": {"frame": "base", "aabb_m": [list(self.aabb_m[0]), list(self.aabb_m[1])]},
+            "max_velocity_mps": self.max_velocity_mps,
+            "max_action_rate_hz": self.max_action_rate_hz,
+            "enforcement": "command_check",
+            "on_violation": "reject",
+        }
+
+    def has(self, feature: str) -> bool:
+        return feature in self.features
+
+    def manifest(self) -> dict[str, Any]:
+        lockstep = self.mode == "lockstep"
+        safety: dict[str, Any] = {"envelopes": [self.envelope]}
+        if self.has("approval"):
+            safety["approval_timeout_ms"] = self.approval_timeout_ms
+        capabilities: dict[str, Any] = {}
+        if self.has("task"):
+            capabilities["task"] = True
+        if self.has("sim"):
+            capabilities.update(seed=True, snapshot=True, replay=True)
+        if self.has("servo"):
+            capabilities["command_channels"] = True
+        action_types = ["move_to_pose", "stop"]
+        if self.has("approval"):
+            action_types.append("park")
+        if self.has("servo"):
+            action_types.append("servo")
+        channels = ["proprio", "arm_state"] + ([SERVO_CHANNEL] if self.has("servo") else [])
+        move_policies = ["replace", "queue", "reject"] + (["blend"] if self.has("blend") else [])
+        if not lockstep:
+            safety["safe_state"] = {"behavior": "safe_stop", "watchdog_ms": self.watchdog_ms}
+            safety["max_basis_age_ms"] = self.max_basis_age_ms
+        manifest: dict[str, Any] = {
+            "protocol_version": "0.1",
+            "world": {"name": "awp-sim", "version": __version__, "vendor": "hyperduality"},
+            "time_models": [self.mode],
+            "capabilities": capabilities,
+            "initial_states": ["home"],
+            "embodiments": [
+                {
+                    "id": EMBODIMENT,
+                    "kind": "manipulator",
+                    "action_types": action_types,
+                    "channels": channels,
+                }
+            ],
+            "observation_channels": [
+                {
+                    "id": "proprio",
+                    "modality": "proprio/json",
+                    "rate_hz": None if lockstep else self.proprio_hz,
+                    "loss_class": "latest-wins",
+                    "stale_after_ms": max(1, round(5000 / self.proprio_hz)),
+                    "schema": {"fields": ["p_m", "v_mps"], "frame": "base"},
+                },
+                {
+                    "id": "arm_state",
+                    "modality": "text/event+json",
+                    "rate_hz": None if lockstep else self.state_hz,
+                    "loss_class": "reliable",
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "phase": {"enum": ["idle", "moving", "stopping", "servo"]},
+                            "target_m": {"type": ["array", "null"]},
+                            "action_id": {"type": ["string", "null"]},
+                        },
+                        "required": ["phase", "target_m", "action_id"],
+                    },
+                },
+            ],
+            "action_schemas": [
+                {
+                    "type": "move_to_pose",
+                    "params_schema": {"$ref": "#/$defs/move_to_pose_params"},
+                    "duration": "extended",
+                    "preemption": move_policies,
+                    "concurrency_group": "arm_motion",
+                    "max_queue": 4,
+                    "max_abort_ms": self.max_abort_ms,
+                    "max_duration_ms": self.max_duration_ms,
+                    "description": "Move the end effector in a straight line to a position.",
+                },
+                {
+                    "type": "stop",
+                    "params_schema": {"type": "object", "additionalProperties": False},
+                    "duration": "instant",
+                    "preemption": "replace",
+                    "concurrency_group": "arm_motion",
+                    "description": "Decelerate to rest; replaces any motion.",
+                },
+            ],
+            "safety_policy": safety,
+            "$defs": {
+                "move_to_pose_params": {
+                    "type": "object",
+                    "properties": {
+                        "pose": {
+                            "$ref": "https://agentworldprotocol.com/schemas/v0.1/common.schema.json#/$defs/pose"
+                        },
+                        "max_velocity_mps": {"type": "number", "exclusiveMinimum": 0},
+                    },
+                    "required": ["pose"],
+                    "additionalProperties": False,
+                }
+            },
+        }
+        if self.has("approval"):
+            manifest["action_schemas"].append(
+                {
+                    "type": "park",
+                    "params_schema": {"type": "object", "additionalProperties": False},
+                    "duration": "extended",
+                    "preemption": "queue",
+                    "concurrency_group": "arm_motion",
+                    "max_queue": 4,
+                    "requires_approval": True,
+                    "max_abort_ms": self.max_abort_ms,
+                    "max_duration_ms": self.max_duration_ms,
+                    "description": "Move to the park pose; needs an approver's decision.",
+                }
+            )
+        if self.has("servo"):
+            manifest["command_channels"] = [
+                {
+                    "id": SERVO_CHANNEL,
+                    "modality": "servo/json",
+                    "rate_hz": self.servo_hz,
+                    "loss_class": "latest-wins",
+                    "schema": {"fields": ["v_mps"], "frame": "base"},
+                }
+            ]
+            manifest["action_schemas"].append(
+                {
+                    "type": "servo",
+                    "params_schema": {"type": "object", "additionalProperties": False},
+                    "duration": "streaming",
+                    "command_channel": SERVO_CHANNEL,
+                    "watchdog_ms": self.servo_watchdog_ms,
+                    "preemption": ["replace", "reject"],
+                    "concurrency_group": "arm_motion",
+                    "max_abort_ms": self.max_abort_ms,
+                    "description": "Follow end-effector velocity setpoints on servo_arm.",
+                }
+            )
+        if lockstep:
+            manifest["tick_policy"] = "on_tick"
+            manifest["tick_authority"] = "any_session"
+        if self.extensions:
+            manifest["extensions"] = self.extensions
+        return manifest
+
+
+FRAME_TREE: dict[str, Any] = {
+    "frames": [
+        {"id": "world", "parent": None},
+        {"id": "base", "parent": "world", "transform": {"p_m": [0, 0, 0], "q": [0, 0, 0, 1]}},
+    ]
+}

awp_sim/demo.py

@@ -0,0 +1,85 @@
+"""A scripted agent that exercises a running world: moves, a cancel, and an envelope refusal."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from awp.aio import AsyncClient
+from awp.client import ClientConnection
+from awp.errors import AwpError
+
+from . import __version__
+
+TARGETS = [(0.3, 0.2, 0.5), (-0.2, 0.1, 0.3), (0.0, -0.3, 0.45), (0.0, 0.0, 0.4)]
+
+
+def _pose(p: tuple[float, float, float]) -> dict[str, Any]:
+    return {"pose": {"frame": "base", "p_m": list(p), "q": [0, 0, 0, 1]}}
+
+
+def _pct(values: list[float], p: float) -> float:
+    ordered = sorted(values)
+    return ordered[min(len(ordered) - 1, round(p * (len(ordered) - 1)))]
+
+
+async def run_demo(url: str, *, token: str | None = None, echo: bool = True) -> dict[str, float]:
+    say = print if echo else (lambda *_: None)
+    conn = ClientConnection(
+        {"name": "awp-sim-demo", "version": __version__, "vendor": "hyperduality"},
+        ["proprio/json", "text/event+json"],
+    )
+    admission_ms: list[float] = []
+    async with AsyncClient(conn, url, token=token) as client:
+        manifest = await client.initialize()
+        mode = manifest["time_models"][0]
+        ready = await client.open_session(
+            mode, embodiment="arm_01", subscribe=["proprio", "arm_state"]
+        )
+        say(f"session {ready['session_id']} ({mode}) on {manifest['world']['name']}")
+        lockstep = mode == "lockstep"
+        if "move_to_pose" not in conn.granted_action_types:
+            say("  move_to_pose is not granted; nothing to do")
+            await client.close_session()
+            return {}
+
+        async def move(target: tuple[float, float, float], **kw: Any) -> str:
+            basis = None if lockstep else client.latest["proprio"].frame
+            validity = None if lockstep else 200
+            started = time.perf_counter()
+            record = await client.submit(
+                "move_to_pose", _pose(target), basis=basis, valid_for_ms=validity, **kw
+            )
+            admission_ms.append((time.perf_counter() - started) * 1000)
+            return record.action_id
+
+        for target in TARGETS:
+            action = await move(target)
+            while lockstep and not conn.actions[action].terminal:
+                await client.advance(10)
+            record = await client.wait_terminal(action)
+            say(f"  move to {target}: {record.state}")
+
+        if not lockstep:
+            action = await move(TARGETS[0])
+            await client.wait_for(lambda e: (conn.actions[action].progress or 0) > 0.2, 5)
+            await client.cancel(action)
+            record = await client.wait_terminal(action)
+            say(f"  cancelled move: {record.state} at {record.status.get('aborted_at_progress')}")
+
+        try:
+            await move((0.9, 0.0, 0.4))
+        except AwpError as err:
+            say(f"  outside the envelope: {err.message}")
+
+        await client.close_session()
+
+    metrics = {
+        "admission_p50_ms": _pct(admission_ms, 0.5),
+        "admission_p95_ms": _pct(admission_ms, 0.95),
+    }
+    say(
+        f"admission latency p50 {metrics['admission_p50_ms']:.2f} ms, "
+        f"p95 {metrics['admission_p95_ms']:.2f} ms"
+    )
+    return metrics