@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.8 → 0.10.1-dev.0

package/cli/src/devId.mjs

@@ -0,0 +1,54 @@
+// The plugin id a dev session runs under.
+//
+// Machines developing the same plugin against one robot register the same topics on its gateway, and
+// requests (rb.action, external routes) then reach whichever backend registered last — with no error,
+// so one developer's button runs the other's code. Against a remote robot each machine therefore runs
+// as <manifest id>.dev-<user>-<random>. The random part is kept in ~/.muscat-pk/dev-id: the id stays the
+// same across runs (stable external URLs) and differs between machines even when host or user names match.
+// --keep-id runs under the manifest id (program execute, external clients that use the real id); then only
+// one machine may be connected to that robot.
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { dirname, resolve } from "node:path";
+import { PLUGIN_ID_RE } from "./manifest.mjs";
+import { log } from "./util.mjs";
+import { isRemoteRobot } from "./zenohDev.mjs";
+
+const DEV_ID_FILE = resolve(homedir(), ".muscat-pk", "dev-id");
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+// `dev` decides once; its dev:back child gets no CLI args and reads the id from here.
+const ENV = "MUSCAT_PK_DEV_PLUGIN_ID";
+
+function machineToken() {
+  const saved = existsSync(DEV_ID_FILE) ? readFileSync(DEV_ID_FILE, "utf8").trim() : "";
+  if (/^[a-z0-9]{6}$/.test(saved)) return saved;
+  const token = [...randomBytes(6)].map((b) => ALPHABET[b % ALPHABET.length]).join("");
+  mkdirSync(dirname(DEV_ID_FILE), { recursive: true });
+  writeFileSync(DEV_ID_FILE, `${token}\n`);
+  return token;
+}
+
+function userName() {
+  try {
+    return userInfo().username.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 12);
+  } catch {
+    return "";
+  }
+}
+
+/** The id for this dev session (UI, backend, ROS namespace and external routes all use it). */
+export function devPluginId(manifestId, { robotIp, args = [] }) {
+  if (process.env[ENV]) return process.env[ENV];
+  let id = manifestId;
+  if (manifestId && isRemoteRobot(robotIp) && !args.includes("--keep-id")) {
+    const candidate = `${manifestId}.${["dev", userName(), machineToken()].filter(Boolean).join("-")}`;
+    if (PLUGIN_ID_RE.test(candidate)) id = candidate;
+  }
+  if (id !== manifestId) {
+    log.step(`dev plugin id ${id} — this machine's own on the shared robot (--keep-id runs as ${manifestId})`);
+    log.step(`external routes: http://${robotIp}:3000/common/plugin/${id}/<path>`);
+  }
+  if (id) process.env[ENV] = id;
+  return id;
+}

package/cli/src/devSession.mjs

@@ -0,0 +1,67 @@
+// One Muscat plugin dev environment per PC: the backend container, the local Muscat runtime (and
+// the plugin ports it publishes) and the host_agent relay port are shared. A new dev / dev:ui /
+// dev:back offers to stop the running one and take over.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { log, prompt } from "./util.mjs";
+
+export const DEV_CONTAINER = "muscat-pk-dev-run";
+// Per-runtime names from older kits.
+const OLD_CONTAINERS = ["muscat-pk-python-dev-run", "muscat-pk-ros2-dev-run", "muscat-pk-cpp-dev-run"];
+const LOCK = resolve(homedir(), ".muscat-pk", "dev-session.json");
+
+export function stopDevBackContainers() {
+  for (const c of [DEV_CONTAINER, ...OLD_CONTAINERS]) spawnSync("docker", ["rm", "-f", c], { stdio: "ignore" });
+}
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+};
+
+function runningSession() {
+  try {
+    const s = JSON.parse(readFileSync(LOCK, "utf8"));
+    return s.pid !== process.pid && alive(s.pid) ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+async function stopSession(pid) {
+  // SIGINT runs its own cleanup (UI, host_agent, containers). Windows has no signals — kill the tree.
+  if (process.platform === "win32") spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+  else process.kill(pid, "SIGINT");
+  for (let i = 0; i < 60 && alive(pid); i++) await new Promise((r) => setTimeout(r, 500));
+  if (alive(pid)) process.kill(pid, "SIGKILL");
+}
+
+export async function claimDevSession(root, command) {
+  if (process.env.MUSCAT_PK_MANAGED_DEV === "1") return; // `dev` claimed it for its dev:ui / dev:back
+  const other = runningSession();
+  if (other?.pid === process.ppid) return; // `dev`'s own dev:back child
+  if (other) {
+    log.warn(`A Muscat plugin dev environment is already running: muscat-pk ${other.command} in ${other.root} (pid ${other.pid}).`);
+    log.warn("Only one can run per PC — they share the backend container, the local Muscat and its ports.");
+    const answer = (await prompt("  Stop it and start this one? [y/N]: ")).toLowerCase();
+    if (answer !== "y" && answer !== "yes") throw new Error("another plugin dev environment is running — stop it first.");
+    await stopSession(other.pid);
+    stopDevBackContainers(); // whatever it could not clean up
+    log.ok("stopped the other plugin dev environment");
+  }
+  mkdirSync(dirname(LOCK), { recursive: true });
+  writeFileSync(LOCK, JSON.stringify({ pid: process.pid, root, command }));
+  process.on("exit", () => {
+    try {
+      if (JSON.parse(readFileSync(LOCK, "utf8")).pid === process.pid) rmSync(LOCK, { force: true });
+    } catch {
+      /* already gone */
+    }
+  });
+}

package/cli/src/devUi.mjs

@@ -1,38 +1,62 @@
-// muscat-pk dev:ui — preview the plugin inside a mini-Muscat (preview-host).
+
 import { spawn, spawnSync } from "node:child_process";
+import { createServer as createNetServer } from "node:net";
 import { createRequire } from "node:module";
-import { existsSync, mkdirSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, watch, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { buildPlugin } from "./build.mjs";
-import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log } from "./util.mjs";
+import { fileURLToPath } from "node:url";
+import { checkKitUpdate, ensureDevDir, findPluginRoot, hasBin, kitRoot, log, openBrowser, parseArgs, prompt } from "./util.mjs";
+import { devPluginId } from "./devId.mjs";
+import { readManifest } from "./manifest.mjs";
+import { ensureLocalMuscat, GATEWAY_PORT, localFullMuscat, robotHasMuscat } from "./muscatLocal.mjs";
+import { isRemoteRobot } from "./zenohDev.mjs";
+import { claimDevSession } from "./devSession.mjs";
+
+
+const DEV_PLUGIN_PORT = 4181;
+
+function getFreePort(preferred) {
+  return new Promise((res) => {
+    const srv = createNetServer();
+    srv.once("error", () => {
+      const s2 = createNetServer();
+      s2.listen(0, () => {
+        const { port } = s2.address();
+        s2.close(() => res(port));
+      });
+    });
+    srv.listen(preferred, () => srv.close(() => res(preferred)));
+  });
+}
 
 const PREVIEW_PKG = "@rainbow-robotics/preview-host";
 const CACHE_DIR = resolve(homedir(), ".muscat-pk");
 const CACHE_ROOT = resolve(CACHE_DIR, "node_modules", "@rainbow-robotics", "preview-host");
 
-/**
- * Resolve preview-host root in order:
- *  1. Standard require (npm/yarn global install)
- *  2. Monorepo sibling (dev workspace)
- *  3. ~/.muscat-pk cache (previous auto-install)
- *  4. Auto-install to ~/.muscat-pk via npm (binary users who have Node.js)
- */
+
+
+function findNodeBin() {
+  if (typeof Bun === "undefined") return process.execPath;
+  for (const c of ["node", "node20", "node18"]) {
+    if (hasBin(c)) return c;
+  }
+  return null;
+}
+
 function findPreviewHostRoot() {
-  // 1. npm/yarn 설치 경로
   try {
     const req = createRequire(import.meta.url);
     return dirname(req.resolve(`${PREVIEW_PKG}/package.json`));
-  } catch {}
+  } catch {
+    console.log("Try the sibling and cached package locations below.")
+  }
 
-  // 2. 모노레포 sibling
   const sibling = resolve(kitRoot, "../preview-host");
   if (existsSync(resolve(sibling, "package.json"))) return sibling;
 
-  // 3. 캐시
   if (existsSync(resolve(CACHE_ROOT, "package.json"))) return CACHE_ROOT;
 
-  // 4. npm 자동 설치 → 캐시
   if (!hasBin("npm")) {
     throw new Error(
       `preview-host를 찾을 수 없습니다.\n` +
@@ -53,32 +77,197 @@ function findPreviewHostRoot() {
   return CACHE_ROOT;
 }
 
+function syncAssets(pluginRoot, outDir) {
+  const assetsSrc = resolve(pluginRoot, "assets");
+  if (existsSync(assetsSrc)) cpSync(assetsSrc, resolve(outDir, "assets"), { recursive: true });
+}
+
+
+// "(dev)" after every name the plugin shows, so a dev session is never mistaken for an installed copy.
+const devLabel = (v) =>
+  typeof v === "string"
+    ? `${v} (dev)`
+    : v && typeof v === "object"
+      ? Object.fromEntries(Object.entries(v).map(([lang, s]) => [lang, `${s} (dev)`]))
+      : v;
+
+// preview-host takes the plugin id from this copy, so the UI talks under the session's dev id.
+function stageDevAssets(pluginRoot, pluginId) {
+  const outDir = ensureDevDir(pluginRoot);
+  const manifestSrc = resolve(pluginRoot, "manifest.json");
+  if (existsSync(manifestSrc)) {
+    const manifest = JSON.parse(readFileSync(manifestSrc, "utf8"));
+    if (pluginId) manifest.id = pluginId;
+    manifest.name = devLabel(manifest.name);
+    for (const c of manifest.contributes ?? []) {
+      c.label = devLabel(c.label);
+      if (c.commandInfo?.name) c.commandInfo.name = devLabel(c.commandInfo.name);
+    }
+    writeFileSync(resolve(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  }
+  syncAssets(pluginRoot, outDir);
+  return outDir;
+}
+
+function watchAssets(pluginRoot, outDir) {
+  const assetsSrc = resolve(pluginRoot, "assets");
+  if (!existsSync(assetsSrc)) return;
+  watch(assetsSrc, { recursive: true }, () => syncAssets(pluginRoot, outDir));
+}
+
+
+function findViteBin(pluginRoot) {
+  try {
+    const req = createRequire(resolve(pluginRoot, "package.json"));
+    const vitePkg = req.resolve("vite/package.json");
+    return resolve(dirname(vitePkg), "bin", "vite.js");
+  } catch {
+    return null;
+  }
+}
+
+
+function spawnPluginDevServer(pluginRoot, node, port, readyFile, sharedRuntimeBase) {
+  if (!node || !findViteBin(pluginRoot)) return null;
+  const runner = fileURLToPath(new URL("./pluginDevServer.mjs", import.meta.url));
+
+  rmSync(resolve(pluginRoot, "node_modules", ".vite"), { recursive: true, force: true });
+
+  return spawn(node, [runner, pluginRoot, String(port), readyFile], {
+    cwd: pluginRoot,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      VITE_PLUGIN_PREVIEW: "true",
+      MUSCAT_PLUGIN_SHARED_RUNTIME_BASE: sharedRuntimeBase,
+    },
+  });
+}
+
+// The ready file is the signal and an exit the failure; the timeout only guards a hang. A cold vite start
+// takes ~11s on Windows and more while `dev`'s first docker build loads the machine, so a tight limit
+// stopped a healthy `dev`.
+function waitForPluginDevPort(readyFile, proc, timeoutMs = 120_000) {
+  const start = Date.now();
+  const slow = setTimeout(() => log.info("plugin dev server (vite) is still starting…"), 15_000);
+  return new Promise((res, rej) => {
+    let exited = false;
+    proc.once("exit", (code) => {
+      exited = true;
+      rej(new Error(`plugin dev server exited before ready (code ${code ?? 0})`));
+    });
+
+    const tick = () => {
+      if (existsSync(readyFile)) {
+        try {
+          const { port } = JSON.parse(readFileSync(readyFile, "utf8"));
+          if (Number.isInteger(port)) return res(port);
+        } catch {
+          console.log("Keep polling until the ready file contains valid JSON.")
+        }
+      }
+      if (Date.now() - start > timeoutMs)
+        return rej(new Error("plugin dev server did not become ready in time"));
+      if (!exited) setTimeout(tick, 100);
+    };
+    tick();
+  }).finally(() => clearTimeout(slow));
+}
+
 export async function runDevUi(args = []) {
-  const portIdx = args.indexOf("--port");
-  const port = portIdx !== -1 ? args[portIdx + 1] : "4180";
+  const parsed = parseArgs(args);
+  const requestedPort = Number(parsed.port ?? "4180");
+  await claimDevSession(findPluginRoot(), "dev:ui");
+  const robotIp = parsed["robot-ip"] ?? process.env.MUSCAT_ROBOT_HOST ?? await prompt("  Robot IP (skip if no robot): ");
 
   await checkKitUpdate();
-  const { distDir } = await buildPlugin();
+  const pluginRoot = findPluginRoot();
+  const outDir = stageDevAssets(pluginRoot, devPluginId(readManifest(pluginRoot).id, { robotIp, args }));
+  const port = await getFreePort(requestedPort);
+
+  // No robot: the bundle talks to localhost:3000, so put a Muscat there (`dev` already did).
+  if (!isRemoteRobot(robotIp) && process.env.MUSCAT_PK_MANAGED_DEV !== "1") {
+    await ensureLocalMuscat().catch((e) => log.warn(`local Muscat: ${e.message}`));
+  }
+
+  watchAssets(pluginRoot, outDir);
+
+  const node = findNodeBin();
+  const readyFile = resolve(outDir, "plugin-dev-port.json");
+  rmSync(readyFile, { force: true });
+  const sharedRuntimeBase = `http://localhost:${port}/plugin-shared`;
+  const viteProc = spawnPluginDevServer(
+    pluginRoot,
+    node,
+    DEV_PLUGIN_PORT,
+    readyFile,
+    sharedRuntimeBase,
+  );
+  let devPort = DEV_PLUGIN_PORT;
+
+  if (!viteProc) {
+    log.warn("vite not found — UI will not load. Run `npm install` in the plugin project.");
+  } else {
+    devPort = await waitForPluginDevPort(readyFile, viteProc);
+    viteProc.on("exit", (code) => {
+      if (code) log.warn(`plugin dev server exited (code ${code}) — UI won't load (is :${devPort} free?).`);
+    });
+  }
+
+  // muscat-dev, or our own Muscat with a simulator (`dev --sim`): a full local Muscat to show.
+  const localDevMuscat = !!process.env.MUSCAT_PK_SIM || (await localFullMuscat(robotIp));
+  const uiHost = isRemoteRobot(robotIp) ? robotIp : localDevMuscat ? "localhost" : "";
 
   const previewRoot = findPreviewHostRoot();
   const serveEntry = resolve(previewRoot, "serve.mjs");
   if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
     log.step("building preview-host bundle (first run)…");
     await new Promise((res, rej) => {
-      const p = spawn(process.execPath, [resolve(previewRoot, "build.mjs")], {
+      const p = spawn(node ?? process.execPath, [resolve(previewRoot, "build.mjs")], {
         stdio: "inherit",
+        env: { ...process.env, VITE_PLUGIN_PREVIEW: "true" },
       });
       p.on("exit", (c) => (c === 0 ? res() : rej(new Error("preview-host build failed"))));
     });
   }
 
-  log.step(`starting preview-host on :${port}`);
   const child = spawn(
-    process.execPath,
-    [serveEntry, "--plugin", distDir, "--port", String(port)],
-    { stdio: "inherit" },
+    node ?? process.execPath,
+    [
+      serveEntry,
+      "--plugin", outDir,
+      "--port", String(port),
+      "--dev-server-url", `http://localhost:${devPort}`,
+      // A remote robot (or a local muscat-dev) turns the bundle into that Muscat's UI; otherwise
+      // it stays the mock preview.
+      ...(uiHost ? ["--robot-host", uiHost] : []),
+      // The dev plugin's socket goes to that Muscat's gateway; otherwise to the local runtime.
+      ...((await robotHasMuscat(robotIp)) || localDevMuscat ? ["--socket-url", `ws://${uiHost}:${GATEWAY_PORT}`] : []),
+    ],
+    // preview-host only prints its address and paths; the "UI →" line below says what matters.
+    { stdio: ["inherit", "ignore", "inherit"] },
   );
-  child.on("exit", (code) => process.exit(code ?? 0));
+
+  for (let i = 0; i < 50 && !(await fetch(`http://localhost:${port}/`).then(() => true, () => false)); i++)
+    await new Promise((r) => setTimeout(r, 200));
+  log.ok(`UI → http://localhost:${port}`);
+  // Only for a person at a terminal — not CI, scripts or `--no-open`.
+  if (process.stdout.isTTY && !process.env.CI && !parsed["no-open"]) openBrowser(`http://localhost:${port}`);
+
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    if (viteProc && !viteProc.killed && viteProc.exitCode === null) viteProc.kill();
+    if (!child.killed && child.exitCode === null) child.kill();
+  };
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  process.once("SIGHUP", cleanup);
+  child.on("exit", (code) => {
+    cleanup();
+    process.exit(code ?? 0);
+  });
 }
 
 export { findPluginRoot, findPreviewHostRoot };

package/cli/src/esbuild.mjs

@@ -20,20 +20,37 @@ async function buildWithBun(options) {
   }
 }
 
+async function buildWithWasm(options) {
+  const wasm = await import("esbuild-wasm");
+  return wasm.build(options);
+}
+
+function isNativeMissing(err) {
+  const msg = String(err?.message || err?.code || err || "");
+  return (
+    msg.includes("another platform") ||
+    msg.includes("Cannot find module") ||
+    msg.includes("Cannot find package") ||
+    msg.includes("not found") ||
+    msg.includes("No such file") ||
+    msg.includes("ENOENT") ||
+    msg.includes("MODULE_NOT_FOUND")
+  );
+}
+
 export async function buildWithFallback(options) {
   if (typeof Bun !== "undefined") return buildWithBun(options);
 
-  const native = await import("esbuild");
+  // Try native esbuild (faster, no extra setup). Falls back to wasm when:
+  // - esbuild was not installed (removed from hard dependencies to avoid
+  //   postinstall script blocking npm i -g on Windows)
+  // - binary was built for a different platform
   try {
+    const native = await import("esbuild");
     return await native.build(options);
-  } catch (error) {
-    const message = String(error?.message || error);
-    if (!message.includes("another platform")) {
-      throw error;
-    }
-
-    const wasm = await import("esbuild-wasm");
-    console.warn("[muscat-pk] native esbuild binary mismatch; falling back to esbuild-wasm");
-    return wasm.build(options);
+  } catch (err) {
+    if (!isNativeMissing(err)) throw err;
   }
+
+  return buildWithWasm(options);
 }

package/cli/src/host_agent.py

@@ -0,0 +1,223 @@
+"""Host-side Zenoh byte-proxy for Docker Desktop containers (Mac/WSL remote dev).
+
+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).
+"""
+
+from __future__ import annotations
+
+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:
+    body = json.dumps(obj).encode()
+    with lock:
+        conn.sendall(struct.pack(">I", len(body)) + body)
+
+
+def _recv_frame(conn: socket.socket) -> dict | None:
+    hdr = b""
+    while len(hdr) < 4:
+        chunk = conn.recv(4 - len(hdr))
+        if not chunk:
+            return None
+        hdr += chunk
+    n = struct.unpack(">I", hdr)[0]
+    buf = b""
+    while len(buf) < n:
+        chunk = conn.recv(n - len(buf))
+        if not chunk:
+            return None
+        buf += chunk
+    return json.loads(buf.decode())
+
+
+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()
+    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")
+
+            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 in subs.values():
+            with contextlib.suppress(Exception):
+                sub.undeclare()
+        conn.close()
+
+
+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"])
+
+    # Listen only; the robot dials in after registration. Router mode so a C++ SDK dev container
+    # (native Zenoh session, no byte shim) can connect here and be routed to the robot.
+    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 = 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)
+    srv.bind(("0.0.0.0", proxy_port))
+    srv.listen(32)
+    print(f"[host-agent] byte-proxy listening :{proxy_port} (container connects via host.docker.internal)", flush=True)
+
+    try:
+        while True:
+            conn, _addr = srv.accept()
+            threading.Thread(target=_handle_conn, args=(conn, session), daemon=True).start()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        peer.close()
+        with contextlib.suppress(Exception):
+            session.close()
+
+
+if __name__ == "__main__":
+    main()