@rainbow-robotics/muscat-plugin-kit 1.3.6-dev.8 → 1.3.7

package/cli/src/devBack.mjs

@@ -8,11 +8,12 @@
 //   ros2   : Jazzy + Python 3.12 container, colcon build, run the node, restart
 //            on source changes (rclcpp rebuilds on change).
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, watch } from "node:fs";
-import { resolve } from "node:path";
-import { ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
+import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "node:fs";
+import { isIP } from "node:net";
+import { dirname, resolve } from "node:path";
+import { dockerUserFlags, ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
 import { ensureRemoteZenohEnv, usesHostNetwork } from "./zenohDev.mjs";
-import { assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
+import { PLUGIN_ID_RE, assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, rosNamespace, validateManifest } from "./manifest.mjs";
 import {
   formatPortRanges,
   portEnvFlags,
@@ -52,6 +53,67 @@ export function stopDevBackContainers() {
   }
 }
 
+// Where the backend's 127.0.0.1 points. A local Muscat container (muscat-dev): join its
+// netns so the gateway and MediaMTX resolve like on the robot. Under `dev`: the bridge's
+// netns. Standalone dev:back: its own netns, gateway via the host.
+function backendNetwork(portRanges) {
+  const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
+  if (muscat) return { run: ["--network", `container:${muscat}`], env: [], shared: true };
+  if (usesHostNetwork()) return { run: ["--network", "host"], env: [], shared: true };
+  const bridge = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
+  if (bridge) return { run: ["--network", `container:${bridge}`], env: [], shared: true };
+  return {
+    // host.docker.internal is automatic on Docker Desktop; this makes it resolve on Linux too.
+    run: [...publishPortFlags(portRanges), "--add-host", "host.docker.internal:host-gateway"],
+    env: ["-e", "RB_PLUGIN_GATEWAY_URL=http://host.docker.internal:10000"],
+    shared: false,
+  };
+}
+
+// rb.rosPeers in dev: answer muscat/plugin/<id>/ros_peers/{get,set} on the gateway the way
+// Muscat (common) does on the robot — keep the list in .muscat-dev/ and restart the node
+// with ROS_STATIC_PEERS.
+const ROS_PEERS_FILE = ".muscat-dev/ros-peers.json";
+
+function readRosPeers(root) {
+  try {
+    return JSON.parse(readFileSync(resolve(root, ROS_PEERS_FILE), "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+async function serveRosPeers(root, pluginId, restart) {
+  if (!pluginId) return;
+  const { RbWs } = await import("@rainbow-robotics/plugin-ui/ws");
+  const ws = await Promise.race([
+    RbWs.connect("http://127.0.0.1:10000", pluginId).catch(() => null),
+    new Promise((r) => setTimeout(() => r(null), 5000)),
+  ]);
+  if (!ws) return log.warn("rb.rosPeers unavailable in dev: plugin gateway not reachable on :10000");
+  const base = `/muscat/plugin/${pluginId}/ros_peers`;
+  await ws.serve(`${base}/get`, () => ({ peers: readRosPeers(root) }));
+  await ws.serve(`${base}/set`, (payload) => {
+    const peers = payload?.peers;
+    if (!Array.isArray(peers) || !peers.every((p) => typeof p === "string" && isIP(p))) {
+      return { ok: false, error: "peers must be a list of IP addresses" };
+    }
+    const file = resolve(root, ROS_PEERS_FILE);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(peers) + "\n");
+    log.step(`ROS_STATIC_PEERS → ${peers.join(";") || "(none)"} — restarting node`);
+    restart();
+    return { ok: true, peers };
+  });
+}
+
+// Our own MediaMTX, only when `dev` found its ports free (a local Muscat brings its own).
+function startMediaServer(container) {
+  if (process.env.MUSCAT_PK_MEDIA !== "1") return;
+  spawnSync("docker", ["exec", "-d", container, "mediamtx", "/etc/mediamtx/mediamtx.yml"], { stdio: "ignore" });
+  log.step("MediaMTX: publish rtsp://127.0.0.1:8554/<path> · play http://localhost:8889/<path>");
+}
+
 // ── IDE tooling venv (best-effort, non-blocking) ────────────────────────────
 // `muscat-pk new` already creates this up front (see new.mjs); this just
 // refreshes it on every `dev`/`dev:back` in case requirements.txt changed.
@@ -95,39 +157,18 @@ async function runPython(root, portRanges) {
   // container shares the host's network stack, so it reaches the bridge at
   // localhost:10000 and the robot's Zenoh router / reverse-dial path directly
   // — no netns sharing, port publishing, host.docker.internal, or byte-proxy.
-  const useHostNet = usesHostNetwork();
-  // Share the bridge container's network namespace so localhost:10000 is the
-  // bridge (set by `muscat-pk dev`). Standalone dev:back has no bridge to join.
-  const bridgeContainer = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
-  const netFlags = useHostNet
-    ? ["--network", "host"]
-    : bridgeContainer ? ["--network", `container:${bridgeContainer}`] : [];
+  const net = backendNetwork(portRanges);
   // Only the container's OWN reverse-dial path needs to publish a listen port.
-  // With host networking the port is already on the host; with the byte-proxy
+  // With a shared netns the port is already reachable; with the byte-proxy
   // the container just connects out — neither needs -p.
   const standaloneZenohPortFlags =
-    !useHostNet && !bridgeContainer && !proxyEndpoint && zenohPort
-      ? ["-p", `${zenohPort}:${zenohPort}`]
-      : [];
-  // Standalone dev:back owns its netns, so it publishes its own declared ports.
-  // Under `dev` the bridge owns the netns and published them already.
-  const pluginPortFlags =
-    !useHostNet && !bridgeContainer ? publishPortFlags(portRanges) : [];
-  const hostGatewayFlags = useHostNet || bridgeContainer
-    ? []
-    : ["--add-host", "host.docker.internal:host-gateway"];
-  // With host networking or the bridge's netns, 127.0.0.1:10000 (the SDK's
-  // gateway default) already reaches the bridge. Otherwise the container's own
-  // 127.0.0.1 is itself — host.docker.internal reaches the host.
-  const gatewayFlags = useHostNet || bridgeContainer
-    ? []
-    : ["-e", "RB_PLUGIN_GATEWAY_URL=http://host.docker.internal:10000"];
+    !net.shared && !proxyEndpoint && zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : [];
   const envFlags = [
     // docker exec below has no -t (no pseudo-TTY), so Python defaults to
     // block-buffered stdout — print() output wouldn't show up until the
     // buffer fills or the process exits. Force unbuffered.
     "-e", "PYTHONUNBUFFERED=1",
-    ...gatewayFlags,
+    ...net.env,
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
@@ -143,19 +184,18 @@ async function runPython(root, portRanges) {
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
 
-  // start a warm, long-lived container with the plugin mounted
+  // start a warm, long-lived container with the plugin mounted.
+  // 호스트 uid 로 돌린다(dockerUserFlags) — root 로 쓴 build/·install/ 은 사용자가 지우지 못한다.
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting Python dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags, ...pluginPortFlags, ...realtimeFlags(),
-      // host.docker.internal is automatic on Docker Desktop (macOS/Windows);
-      // this makes it resolve on Linux too, for the no-bridge gateway fallback above.
-      ...hostGatewayFlags,
+    ["run", "-d", "--name", container, ...net.run, ...standaloneZenohPortFlags, ...realtimeFlags(), ...dockerUserFlags(),
       "-e", "PIP_ROOT_USER_ACTION=ignore",
       "-v", `${root}:/plugin`, "-w", "/plugin", PYTHON_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [zenohPort] });
 
   log.step("pip install requirements + watchfiles (in container)…");
@@ -373,7 +413,7 @@ runpy.run_path("/plugin/py/main.py", run_name="__main__")
 PY`]);
 
   if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
-  if (useHostNet) log.step("network: host (native Linux — direct robot/bridge access)");
+  if (usesHostNetwork()) log.step("network: host (native Linux — direct robot/bridge access)");
   if (proxyEndpoint) log.step(`Zenoh via host byte-proxy → ${proxyEndpoint}`);
   else if (zenohAdvertiseHost && zenohPort) log.step(`Zenoh advertise → ${zenohAdvertiseHost}:${zenohPort}`);
   log.step("watchfiles → py/main.py (reload on any .py change in py/)");
@@ -429,10 +469,14 @@ async function runRos2(root, portRanges) {
   const container = `${ROS2_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const net = backendNetwork(portRanges);
   const envFlags = [
     // Same rationale as runPython(): no -t on docker exec below means
     // rclpy's Python process stdout is block-buffered, not line-buffered.
     "-e", "PYTHONUNBUFFERED=1",
+    // Same as the robot: ROS discovery stays on this host (allow a PC with ROS_STATIC_PEERS).
+    "-e", "ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST",
+    ...net.env,
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
@@ -445,10 +489,11 @@ async function runRos2(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting ROS2 dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), ...realtimeFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...net.run, ...realtimeFlags(), ...dockerUserFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   // one-time deps + symlink build (edits to .py reflect without rebuilding)
@@ -459,15 +504,24 @@ async function runRos2(root, portRanges) {
   let child = null;
   const startNode = () => {
     if (child) child.kill();
-    log.step(`ros2 run ${pkg} ${pkg}_node`);
+    // killing the `docker exec` client doesn't stop the node inside the container
+    spawnSync("docker", ["exec", container, "pkill", "-f", `${pkg}_node|${manifest.runtime?.launch || pkg}`], { stdio: "ignore" });
+    const peers = readRosPeers(root);
+    // Same command the robot runs: rclpy execs the console script, rclcpp uses `ros2 run`;
+    // relative topics land under the plugin's namespace (rosNamespace).
+    const launch = manifest.runtime?.launch || `${pkg}_node`;
+    const nsArgs = PLUGIN_ID_RE.test(pluginId) ? ` --ros-args -r __ns:=${rosNamespace(pluginId)}` : "";
+    const run = (isRclcpp ? `ros2 run ${pkg} ${launch}` : `exec ${launch}`) + nsArgs;
+    log.step(run);
     child = spawn(
       "docker",
-      ["exec", ...envFlags, container, "bash", "-lc",
-        `cd ros2_ws && source install/setup.bash && ros2 run ${pkg} ${pkg}_node`],
+      ["exec", ...envFlags, ...(peers.length ? ["-e", `ROS_STATIC_PEERS=${peers.join(";")}`] : []), container, "bash", "-lc",
+        `cd ros2_ws && source install/setup.bash && ${run}`],
       { cwd: root, stdio: "inherit" },
     );
   };
   startNode();
+  serveRosPeers(root, pluginId, startNode);
 
   // restart node on source change. rclpy reflects .py edits live (symlink-install);
   // rclcpp (C++) and package-metadata changes require a colcon rebuild.
@@ -513,7 +567,9 @@ async function runCpp(root, portRanges) {
   const container = `${CPP_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const net = backendNetwork(portRanges);
   const envFlags = [
+    ...net.env,
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
@@ -526,10 +582,11 @@ async function runCpp(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting C++ dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), ...realtimeFlags(), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...net.run, ...realtimeFlags(), ...dockerUserFlags(), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   const build = () => {

package/cli/src/host_agent.py

@@ -1,10 +1,7 @@
-"""Host-side raw Zenoh byte-proxy.
+"""Host-side Zenoh byte-proxy for Docker Desktop containers (Mac/WSL remote dev).
 
-Runs on the host as a normal Zenoh peer (reverse-dials the robot, same as the
-SDK's own connect()) and serves a tiny domain-agnostic byte protocol over TCP
-— {query, put, subscribe} by keyexpr + bytes only — so a Docker Desktop
-container, which cannot join the robot's Zenoh mesh itself, can talk to a
-process that can.
+Joins the robot's Zenoh mesh with eclipse-zenoh (no rainbow SDK) and relays
+{query, put, subscribe} bytes over TCP to the dev container.
 
 Env: MUSCAT_ROBOT_HOST, MUSCAT_ROBOT_TOKEN, MUSCAT_ZENOH_ADVERTISE_HOST,
 MUSCAT_ZENOH_PORT (robot-facing), MUSCAT_PROXY_PORT (container-facing).
@@ -12,13 +9,21 @@ MUSCAT_ZENOH_PORT (robot-facing), MUSCAT_PROXY_PORT (container-facing).
 
 from __future__ import annotations
 
-import asyncio
 import contextlib
 import json
 import os
+import signal
 import socket
 import struct
+import sys
 import threading
+import urllib.error
+import urllib.request
+
+import zenoh
+
+PEER_TTL = 30
+QUERY_TARGETS = {0: zenoh.QueryTarget.BEST_MATCHING, 1: zenoh.QueryTarget.ALL, 2: zenoh.QueryTarget.ALL_COMPLETE}
 
 
 def _send_frame(conn: socket.socket, lock: threading.Lock, obj: dict) -> None:
@@ -44,102 +49,156 @@ def _recv_frame(conn: socket.socket) -> dict | None:
     return json.loads(buf.decode())
 
 
-def _handle_conn(conn: socket.socket, zenoh_client) -> None:
+def _att(sample) -> str:
+    return sample.attachment.to_string() if sample.attachment is not None else ""
+
+
+def _query(session: zenoh.Session, req: dict) -> list[dict]:
+    payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else None
+    replies = session.get(
+        req["keyexpr"],
+        payload=payload,
+        timeout=req.get("timeout_ms", 2000) / 1000,
+        target=QUERY_TARGETS.get(req.get("target", 0), zenoh.QueryTarget.BEST_MATCHING),
+    )
+    out = []
+    for reply in replies:
+        if reply.ok is not None:
+            s = reply.ok
+            out.append({"key": str(s.key_expr), "payload_hex": s.payload.to_bytes().hex(),
+                        "att": _att(s), "encoding": str(s.encoding), "is_error": False})
+        else:
+            e = reply.err
+            out.append({"key": req["keyexpr"], "payload_hex": e.payload.to_bytes().hex(),
+                        "att": "", "encoding": str(e.encoding), "is_error": True})
+    return out
+
+
+def _handle_conn(conn: socket.socket, session: zenoh.Session) -> None:
     send_lock = threading.Lock()
-    sub_ids: dict[str, int] = {}
+    subs: dict[str, zenoh.Subscriber] = {}
     try:
         while True:
             req = _recv_frame(conn)
             if req is None:
                 return
             op = req.get("type")
+            rid = req.get("id")
 
-            if op == "query":
-                payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else None
-                try:
-                    replies = zenoh_client._client.query(
-                        req["keyexpr"], payload, req.get("timeout_ms", 2000), req.get("target", 0)
-                    )
-                    out = {
-                        "type": "query_resp", "id": req["id"], "ok": True,
-                        "replies": [
-                            {"key": k, "payload_hex": bytes(p).hex(), "att": a, "encoding": e, "is_error": ie}
-                            for (k, p, a, e, ie) in replies
-                        ],
-                    }
-                except Exception as exc:
-                    out = {"type": "query_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
-                _send_frame(conn, send_lock, out)
-
-            elif op == "put":
-                payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else b""
-                try:
-                    zenoh_client._client.publish(req["keyexpr"], payload, "", 0, 5, False)
-                    out = {"type": "put_resp", "id": req["id"], "ok": True}
-                except Exception as exc:
-                    out = {"type": "put_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
-                _send_frame(conn, send_lock, out)
-
-            elif op == "subscribe":
-                keyexpr = req["keyexpr"]
-
-                def on_sample(topic: str, payload_bytes: bytes, att: str, _ke: str = keyexpr) -> None:
-                    _send_frame(conn, send_lock, {
-                        "type": "sample", "keyexpr": _ke, "key": topic,
-                        "payload_hex": bytes(payload_bytes).hex(), "att": att,
-                    })
-
-                try:
-                    sub_id = zenoh_client._client.declare_subscriber(keyexpr, on_sample)
-                    sub_ids[keyexpr] = sub_id
-                    out = {"type": "subscribe_resp", "id": req["id"], "ok": True}
-                except Exception as exc:
-                    out = {"type": "subscribe_resp", "id": req["id"], "ok": False, "error": f"{type(exc).__name__}: {exc}"}
-                _send_frame(conn, send_lock, out)
-
-            elif op == "unsubscribe":
-                keyexpr = req["keyexpr"]
-                sub_id = sub_ids.pop(keyexpr, None)
-                if sub_id is not None:
-                    try:
-                        zenoh_client._client.undeclare_subscriber(sub_id)
-                    except Exception:
-                        pass
-                _send_frame(conn, send_lock, {"type": "unsubscribe_resp", "id": req["id"], "ok": True})
-
-            else:
-                _send_frame(conn, send_lock, {"type": "error", "error": f"unknown op {op!r}"})
+            try:
+                if op == "query":
+                    out = {"type": "query_resp", "id": rid, "ok": True, "replies": _query(session, req)}
+
+                elif op == "put":
+                    payload = bytes.fromhex(req["payload_hex"]) if req.get("payload_hex") else b""
+                    session.put(req["keyexpr"], payload)
+                    out = {"type": "put_resp", "id": rid, "ok": True}
+
+                elif op == "subscribe":
+                    keyexpr = req["keyexpr"]
+
+                    def on_sample(s, _ke: str = keyexpr) -> None:
+                        _send_frame(conn, send_lock, {
+                            "type": "sample", "keyexpr": _ke, "key": str(s.key_expr),
+                            "payload_hex": s.payload.to_bytes().hex(), "att": _att(s),
+                        })
+
+                    old = subs.pop(keyexpr, None)
+                    if old is not None:
+                        old.undeclare()
+                    subs[keyexpr] = session.declare_subscriber(keyexpr, on_sample)
+                    out = {"type": "subscribe_resp", "id": rid, "ok": True}
+
+                elif op == "unsubscribe":
+                    sub = subs.pop(req["keyexpr"], None)
+                    if sub is not None:
+                        with contextlib.suppress(Exception):
+                            sub.undeclare()
+                    out = {"type": "unsubscribe_resp", "id": rid, "ok": True}
+
+                else:
+                    out = {"type": "error", "error": f"unknown op {op!r}"}
+            except Exception as exc:
+                out = {"type": f"{op}_resp", "id": rid, "ok": False, "error": f"{type(exc).__name__}: {exc}"}
+            _send_frame(conn, send_lock, out)
     except (ConnectionResetError, BrokenPipeError, OSError):
         pass
     finally:
-        for sub_id in sub_ids.values():
-            try:
-                zenoh_client._client.undeclare_subscriber(sub_id)
-            except Exception:
-                pass
+        for sub in subs.values():
+            with contextlib.suppress(Exception):
+                sub.undeclare()
         conn.close()
 
 
-def main() -> None:
-    from rainbow.rb_sdk.base import RBBaseSDK
+class Peer:
+    """Registers this host with the robot's common: POST /zenoh/peer, heartbeat, DELETE."""
+
+    def __init__(self, host: str, token: str, ip: str, port: int) -> None:
+        self.base = f"http://{host}:8000"
+        self.headers = {"Content-Type": "application/json"}
+        if token:
+            self.headers["Authorization"] = f"Bearer {token}"
+        self.body = {"ip": ip, "port": port, "ttl": PEER_TTL}
+        self.peer_id: str | None = None
+        self.stop = threading.Event()
+
+    def _http(self, method: str, path: str, body: dict | None = None) -> dict:
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(self.base + path, data=data, headers=self.headers, method=method)
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            raw = resp.read()
+            return json.loads(raw) if raw else {}
+
+    def register(self) -> None:
+        self.peer_id = self._http("POST", "/zenoh/peer", self.body)["peer_id"]
+        print(f"[host-agent] registered with {self.base} as zenoh peer {self.peer_id}", flush=True)
 
+    def maintain(self) -> None:
+        while True:
+            wait = PEER_TTL / 2 if self.peer_id else 3
+            if self.stop.wait(wait):
+                return
+            try:
+                if self.peer_id is None:
+                    self.register()
+                elif not self._http("POST", f"/zenoh/peer/{self.peer_id}/heartbeat", {"ttl": PEER_TTL}).get("ok"):
+                    print(f"[host-agent] heartbeat rejected for {self.peer_id}, re-registering", flush=True)
+                    self.peer_id = None
+            except Exception as exc:
+                print(f"[host-agent] peer maintenance failed ({exc}); retrying", flush=True)
+                if self.peer_id is not None and isinstance(exc, urllib.error.HTTPError) and exc.code == 404:
+                    self.peer_id = None
+
+    def close(self) -> None:
+        self.stop.set()
+        if self.peer_id:
+            with contextlib.suppress(Exception):
+                self._http("DELETE", f"/zenoh/peer/{self.peer_id}")
+
+
+def main() -> None:
+    # dev stops us with SIGTERM; exit via `finally` to deregister.
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
     host = os.environ["MUSCAT_ROBOT_HOST"]
     token = os.environ.get("MUSCAT_ROBOT_TOKEN", "")
     advertise = os.environ["MUSCAT_ZENOH_ADVERTISE_HOST"]
     zenoh_port = int(os.environ["MUSCAT_ZENOH_PORT"])
     proxy_port = int(os.environ["MUSCAT_PROXY_PORT"])
 
-    # The robot reverse-dials the advertised host:port; force it to the host's
-    # real LAN IP (matches what dev.mjs computed via ensureRemoteZenohEnv).
-    RBBaseSDK._detect_local_ip = staticmethod(lambda _host: advertise)
+    # Listen only; the robot dials in after registration.
+    conf = zenoh.Config()
+    conf.insert_json5("mode", '"peer"')
+    conf.insert_json5("listen/endpoints", json.dumps([f"tcp/0.0.0.0:{zenoh_port}"]))
+    conf.insert_json5("scouting/multicast/enabled", "false")
+    session = zenoh.open(conf)
 
-    peer = RBBaseSDK()
-    connect_kwargs = {"host": host, "zenoh_port": zenoh_port, "mesh_timeout": 15.0}
-    if token:
-        connect_kwargs["token"] = token
-
-    asyncio.run(peer.connect(**connect_kwargs))
-    print(f"[host-agent] zenoh peer joined robot mesh (listening :{zenoh_port})", flush=True)
+    peer = Peer(host, token, advertise, zenoh_port)
+    try:
+        peer.register()
+    except Exception as exc:
+        print(f"[host-agent] registration with {peer.base} failed, retrying in background: {exc}", flush=True)
+    threading.Thread(target=peer.maintain, daemon=True, name="zenoh-peer").start()
+    print(f"[host-agent] zenoh peer listening :{zenoh_port} (advertised as {advertise})", flush=True)
 
     srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
@@ -150,12 +209,13 @@ def main() -> None:
     try:
         while True:
             conn, _addr = srv.accept()
-            threading.Thread(target=_handle_conn, args=(conn, peer.zenoh_client), daemon=True).start()
+            threading.Thread(target=_handle_conn, args=(conn, session), daemon=True).start()
     except KeyboardInterrupt:
         pass
     finally:
+        peer.close()
         with contextlib.suppress(Exception):
-            asyncio.run(peer.disconnect())
+            session.close()
 
 
 if __name__ == "__main__":

package/cli/src/manifest.mjs

@@ -11,6 +11,15 @@ export const CONTRIBUTION_POINTS = [
   "program.panel",
 ];
 const ICON_SIZES = ["16", "48", "128"];
+// Reverse-domain id: "."-separated parts of lowercase letters/digits joined by single "-",
+// each part starting with a letter. Keeps the ROS namespace derived from it (rosNamespace)
+// valid and collision-free (no "_" in ids, so "." and "-" map to distinct characters).
+export const PLUGIN_ID_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*)*$/;
+
+/** ROS namespace for a plugin id: "." → "/", "-" → "_" (com.example.my-plugin → /com/example/my_plugin). */
+export function rosNamespace(id) {
+  return "/" + id.replace(/\./g, "/").replace(/-/g, "_");
+}
 const RUNTIME_TYPES = ["none", "python", "cpp", "ros2"];
 const ROS_CLIENTS = ["rclpy", "rclcpp"];
 const I18N_LANGS = ["ko", "en", "ja", "zh", "vi", "th", "es"];
@@ -192,6 +201,8 @@ export function validateManifest(manifest) {
     if (typeof manifest[key] !== "string" || manifest[key].length === 0)
       errors.push(`"${key}" is required`);
   }
+  if (typeof manifest.id === "string" && manifest.id && !PLUGIN_ID_RE.test(manifest.id))
+    errors.push(`"id" must be "."-separated parts of lowercase letters/digits and single "-", each starting with a letter (e.g. com.example.my-plugin)`);
   if (typeof manifest.author !== "string" || manifest.author.length === 0)
     errors.push(`"author" is required`);
   if (typeof manifest.email !== "string" || manifest.email.length === 0)