@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.52 → 0.1.2-dev.53

package/README.md

@@ -129,6 +129,37 @@ Could not create .venv (no local Python/uv?) — skipping, Docker dev still work
 
 Install `uv` (recommended) or a system Python 3.12, then re-run `muscat-pk new` (or `muscat-pk type change`) to create it.
 
+## AI coding agent setup (`muscat-pk mcp`)
+
+`muscat-pk mcp` runs an MCP server (stdio) that gives an AI coding agent grounded info about `rb-components`, design tokens, and the Python `rainbow-rb-sdk` — actual prop types, real Storybook examples, and live-introspected SDK signatures/docstrings, instead of the agent guessing from training data. Use it while working inside a plugin project scaffolded by `muscat-pk new`.
+
+### Claude Code
+
+Claude Code reads a project-scoped `.mcp.json` at the plugin's root:
+
+```json
+{
+  "mcpServers": {
+    "muscat": {
+      "command": "muscat-pk",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Codex
+
+Codex has no project-scoped config file — it reads a single, per-user `~/.codex/config.toml`. Add:
+
+```toml
+[mcp_servers.muscat]
+command = "muscat-pk"
+args = ["mcp"]
+```
+
+You don't run `muscat-pk mcp` yourself either way — the agent spawns and manages it automatically once it's registered.
+
 ## Package roles
 
 | Package | Role |

package/cli/src/dev.mjs

@@ -1,8 +1,10 @@
 // muscat-pk dev — run the Socket.IO bridge (Docker), dev:ui, and dev:back together.
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { connect as netConnect } from "node:net";
 import { release } from "node:os";
 import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack, stopDevBackContainers } from "./devBack.mjs";
 import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
@@ -17,64 +19,66 @@ import {
   promptRobotConnection,
   venvPython,
 } from "./util.mjs";
-import { detectRouteAddress, ensureRemoteZenohEnv, getFreePort, isRemoteRobot } from "./zenohDev.mjs";
+import { ensureRemoteZenohEnv, isRemoteRobot } from "./zenohDev.mjs";
 
-const DEFAULT_HOST_AGENT_PORT = 18080;
+const HOST_AGENT_PATH = fileURLToPath(new URL("./host_agent.py", import.meta.url));
 const isWsl = () => process.platform === "linux" && /microsoft|wsl/i.test(release());
 const canAutoStartHostAgent = () => process.platform === "darwin" || isWsl();
 
 function waitForHostAgent(port, { timeoutMs = 30_000 } = {}) {
   const deadline = Date.now() + timeoutMs;
-  const url = `http://127.0.0.1:${port}/health`;
   return new Promise((resolve, reject) => {
-    const probe = async () => {
-      try {
-        const res = await fetch(url);
-        if (res.ok) return resolve(true);
-      } catch {
-        // keep polling
-      }
-      if (Date.now() >= deadline) {
-        reject(new Error(`host SDK agent did not become ready at ${url}`));
-        return;
-      }
-      setTimeout(probe, 300);
+    const probe = () => {
+      const sock = netConnect(port, "127.0.0.1");
+      sock.once("connect", () => { sock.destroy(); resolve(true); });
+      sock.once("error", () => {
+        sock.destroy();
+        if (Date.now() >= deadline) {
+          reject(new Error(`host SDK agent did not open port ${port} in time`));
+          return;
+        }
+        setTimeout(probe, 300);
+      });
     };
     probe();
   });
 }
 
+const DEFAULT_PROXY_PORT = 47100;
+
+// Start the host-side Zenoh byte-proxy (host_agent.py) for a remote robot —
+// see host_agent.py for why a Docker Desktop container can't join the
+// robot's Zenoh mesh itself. Sets MUSCAT_PROXY_ENDPOINT for dev:back.
+// Returns the child process, or null if not applicable / disabled.
 async function maybeStartHostAgent(root, { robotIp, robotToken }) {
-  if (process.env.MUSCAT_HOST_AGENT_URL) {
-    log.step(`host SDK agent → ${process.env.MUSCAT_HOST_AGENT_URL}`);
+  if (process.env.MUSCAT_PROXY_ENDPOINT) {
+    log.step(`Zenoh via host byte-proxy → ${process.env.MUSCAT_PROXY_ENDPOINT}`);
     return null;
   }
   if (process.env.MUSCAT_HOST_AGENT_DISABLE === "1") return null;
   if (!canAutoStartHostAgent() || !isRemoteRobot(robotIp)) return null;
 
-  const agentPath = resolve(root, "py", "host_agent.py");
+  const agentPath = process.env.MUSCAT_HOST_AGENT_SCRIPT || HOST_AGENT_PATH;
   if (!existsSync(agentPath)) return null;
 
-  const wsl = isWsl();
-  if (wsl) await ensureRemoteZenohEnv(robotIp, { log });
-
-  const bindHost = wsl ? "0.0.0.0" : "127.0.0.1";
-  const containerHost = wsl
-    ? process.env.MUSCAT_HOST_AGENT_CONTAINER_HOST || await detectRouteAddress(robotIp)
-    : "host.docker.internal";
-
-  if (!containerHost) {
-    log.warn("host SDK agent skipped: could not determine container-reachable host");
+  if (!ensureIdeVenv(root)) {
+    log.warn("host Zenoh byte-proxy skipped: could not prepare .venv");
     return null;
   }
 
-  log.step("starting host SDK agent (Docker Desktop workaround)...");
-  if (!ensureIdeVenv(root)) {
-    log.warn("host SDK agent skipped: could not prepare .venv");
+  // advertiseHost/zenohPort = the host_agent's OWN robot-facing Zenoh session
+  // (host LAN IP + port the robot reverse-dials into). The container never
+  // sees or needs these — it only talks to the proxyPort below.
+  const zenoh = await ensureRemoteZenohEnv(robotIp, { log });
+  const advertiseHost = zenoh?.advertiseHost || process.env.MUSCAT_ZENOH_ADVERTISE_HOST;
+  const zenohPort = zenoh?.zenohPort || Number(process.env.MUSCAT_ZENOH_PORT);
+  if (!advertiseHost || !zenohPort) {
+    log.warn("host Zenoh byte-proxy skipped: could not determine host LAN IP / port");
     return null;
   }
+  const proxyPort = Number(process.env.MUSCAT_PROXY_PORT) || DEFAULT_PROXY_PORT;
 
-  const port = await getFreePort(Number(process.env.MUSCAT_HOST_AGENT_PORT || DEFAULT_HOST_AGENT_PORT));
+  log.step("starting host Zenoh byte-proxy (Docker Desktop query-routing workaround)...");
   const py = venvPython(resolve(root, ".venv"));
   const child = spawn(py, [agentPath], {
     cwd: root,
@@ -83,21 +87,27 @@ async function maybeStartHostAgent(root, { robotIp, robotToken }) {
       ...process.env,
       MUSCAT_ROBOT_HOST: robotIp,
       MUSCAT_ROBOT_TOKEN: robotToken,
-      MUSCAT_HOST_AGENT_BIND: bindHost,
-      MUSCAT_HOST_AGENT_PORT: String(port),
+      MUSCAT_ZENOH_ADVERTISE_HOST: advertiseHost,
+      MUSCAT_ZENOH_PORT: String(zenohPort),
+      MUSCAT_PROXY_PORT: String(proxyPort),
     },
   });
 
   try {
-    await waitForHostAgent(port);
+    await waitForHostAgent(proxyPort);
   } catch (e) {
     child.kill();
     throw e;
   }
 
-  const containerUrl = `http://${containerHost}:${port}`;
-  process.env.MUSCAT_HOST_AGENT_URL = containerUrl;
-  log.step(`host SDK agent → ${containerUrl}`);
+  // advertiseHost (not host.docker.internal): a Docker Desktop container run
+  // under `dev` may share the bridge container's netns (--network container:),
+  // which has no host-gateway alias configured — the host's real LAN IP
+  // always resolves regardless of netns mode.
+  const proxyEndpoint = `${advertiseHost}:${proxyPort}`;
+  process.env.MUSCAT_PROXY_ENDPOINT = proxyEndpoint;
+  process.env.MUSCAT_PROXY_PORT = String(proxyPort);
+  log.step(`Zenoh via host byte-proxy → ${proxyEndpoint}`);
   return child;
 }
 
@@ -115,18 +125,14 @@ export async function runDev(args = []) {
 
   const remoteRobot = isRemoteRobot(robotIp);
   const hostAgent = await maybeStartHostAgent(root, { robotIp, robotToken });
-  const hostAgentUrl = process.env.MUSCAT_HOST_AGENT_URL || "";
-  // Compute the Zenoh advertise host/port up front — startBridge() needs the
-  // port to publish it on the bridge container so the robot can reach back.
-  if (hostAgentUrl && !hostAgent) {
-    log.step(`host SDK agent → ${hostAgentUrl}`);
-  } else if (!hostAgentUrl) {
-    await ensureRemoteZenohEnv(robotIp, { log });
-  }
+  const proxyEndpoint = process.env.MUSCAT_PROXY_ENDPOINT || "";
+  // No proxy (Linux, disabled, ...): fall back to the container reverse-dialing
+  // the robot itself — startBridge() then publishes the zenoh port for it.
+  if (!proxyEndpoint) await ensureRemoteZenohEnv(robotIp, { log });
 
   log.step("starting Socket.IO bridge (Docker) + dev:ui + dev:back");
   const bridgeStarted = await startBridge({
-    zenohPort: remoteRobot && !hostAgentUrl ? Number(process.env.MUSCAT_ZENOH_PORT) : null,
+    zenohPort: remoteRobot && !proxyEndpoint ? Number(process.env.MUSCAT_ZENOH_PORT) : null,
   });
 
   if (!bridgeStarted) {

package/cli/src/devBack.mjs

@@ -87,20 +87,23 @@ async function runPython(root, portRanges) {
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
   const zenohAdvertiseHost = process.env.MUSCAT_ZENOH_ADVERTISE_HOST ?? "";
   const zenohPort = process.env.MUSCAT_ZENOH_PORT ?? "";
-  const hostAgentUrl = process.env.MUSCAT_HOST_AGENT_URL ?? "";
+  // See host_agent.py: a Docker Desktop container can't join the robot's
+  // Zenoh mesh, so it speaks a byte protocol to the host-side proxy instead.
+  const proxyEndpoint = process.env.MUSCAT_PROXY_ENDPOINT ?? "";
   // 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 = bridgeContainer ? ["--network", `container:${bridgeContainer}`] : [];
-  const standaloneZenohPortFlags = !bridgeContainer && zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : [];
+  // Only the container's OWN reverse-dial path needs to publish a listen port.
+  // With the byte-proxy, the container just connects out to host.docker.internal
+  // — nothing to publish.
+  const standaloneZenohPortFlags =
+    !bridgeContainer && !proxyEndpoint && zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : [];
   const hostGatewayFlags = bridgeContainer
     ? []
     : ["--add-host", "host.docker.internal:host-gateway"];
-  // Without the bridge's netns, this container is isolated — its own
-  // 127.0.0.1 (rainbow.rb_sdk's gateway default) is itself, not the host, so
-  // it can never see a gateway already running on the host (e.g. the user's
-  // own robot stack occupying port 10000, the reason the bridge start above
-  // was skipped in the first place). host.docker.internal reaches the host.
+  // Without the bridge's netns, 127.0.0.1 (the SDK's gateway default) is the
+  // container itself, not the host — host.docker.internal reaches the host.
   const gatewayFlags = bridgeContainer
     ? []
     : ["-e", "RB_PLUGIN_GATEWAY_URL=http://host.docker.internal:10000"];
@@ -113,9 +116,13 @@ async function runPython(root, portRanges) {
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
-    ...(!hostAgentUrl && zenohAdvertiseHost ? ["-e", `MUSCAT_ZENOH_ADVERTISE_HOST=${zenohAdvertiseHost}`] : []),
-    ...(!hostAgentUrl && zenohPort ? ["-e", `MUSCAT_ZENOH_PORT=${zenohPort}`] : []),
-    ...(hostAgentUrl ? ["-e", `MUSCAT_HOST_AGENT_URL=${hostAgentUrl}`] : []),
+    // Byte-proxy mode: the container has no Zenoh session of its own — the
+    // entry script's shim speaks the raw query/put/subscribe protocol to the
+    // host_agent process at this address instead.
+    ...(proxyEndpoint ? ["-e", `MUSCAT_PROXY_ENDPOINT=${proxyEndpoint}`] : []),
+    // Fallback (no proxy): the container reverse-dials the robot itself.
+    ...(!proxyEndpoint && zenohAdvertiseHost ? ["-e", `MUSCAT_ZENOH_ADVERTISE_HOST=${zenohAdvertiseHost}`] : []),
+    ...(!proxyEndpoint && zenohPort ? ["-e", `MUSCAT_ZENOH_PORT=${zenohPort}`] : []),
     ...portEnvFlags(portRanges),
   ];
   const docker = (args, opts = {}) =>
@@ -142,69 +149,196 @@ async function runPython(root, portRanges) {
     " && { [ -f requirements.txt ] && pip install --break-system-packages --ignore-installed -q -r requirements.txt || true; }"]);
 
   docker(["exec", container, "bash", "-lc", `cat > /tmp/muscat-pk-python-dev-entry.py <<'PY'
-import json
 import os
-import urllib.request
-
-def install_host_agent_sdk_patch(host_agent_url):
-    from rainbow.rb_sdk.base import RBBaseSDK
-    from rainbow.rb_sdk.manipulate_sdk.manipulate_move import RBManipulateMoveSDK
-
-    base_url = host_agent_url.rstrip("/")
-
-    def post_json(path, payload):
-        req = urllib.request.Request(
-            f"{base_url}{path}",
-            data=json.dumps(payload).encode("utf-8"),
-            headers={"Content-Type": "application/json"},
-            method="POST",
-        )
-        with urllib.request.urlopen(req, timeout=30) as resp:
-            data = json.loads(resp.read().decode("utf-8"))
-        if not data.get("ok"):
-            raise RuntimeError(data.get("error") or "host SDK agent request failed")
-        return data.get("result")
-
-    async def connect_via_host_agent(self, *args, **kwargs):
-        print(f"[muscat-pk] SDK connect routed through host agent: {base_url}", flush=True)
-        return "host-agent"
-
-    async def disconnect_via_host_agent(self, *args, **kwargs):
-        return None
-
-    def call_move_j_via_host_agent(
-        self,
-        *,
-        robot_model,
-        target,
-        reference_value=None,
-        speed=None,
-        flow_manager_args=None,
-    ):
-        result = post_json("/move_j", {
-            "robot_model": robot_model,
-            "values": target.get("tar_values") if isinstance(target, dict) else None,
-            "target": target,
-            "reference_value": reference_value,
-            "speed": speed,
-        })
-        if flow_manager_args is not None:
-            flow_manager_args.done()
-        return result
-
-    RBBaseSDK.connect = connect_via_host_agent
-    RBBaseSDK.disconnect = disconnect_via_host_agent
-    RBManipulateMoveSDK.call_move_j = call_move_j_via_host_agent
 
 try:
-    advertise_host = os.getenv("MUSCAT_ZENOH_ADVERTISE_HOST")
-    zenoh_port = os.getenv("MUSCAT_ZENOH_PORT")
-    host_agent_url = os.getenv("MUSCAT_HOST_AGENT_URL")
+    proxy_endpoint = os.getenv("MUSCAT_PROXY_ENDPOINT")
+    if proxy_endpoint:
+        # Byte-proxy mode: this container has no Zenoh session of its own.
+        # ZenohClient's C++ core is replaced with a shim that speaks a raw
+        # query/put/subscribe byte protocol to host_agent.py instead.
+        import json
+        import socket
+        import struct
+        import threading
+
+        _proxy_host, _proxy_port_s = proxy_endpoint.rsplit(":", 1)
+        _proxy_port = int(_proxy_port_s)
+
+        def _send_frame(conn, lock, obj):
+            body = json.dumps(obj).encode()
+            with lock:
+                conn.sendall(struct.pack(">I", len(body)) + body)
+
+        def _recv_frame(conn):
+            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())
+
+        class _ProxyRawClient:
+            """Drop-in replacement for ZenohClient's C++ core, backed by the
+            host_agent byte-proxy instead of a local Zenoh session."""
+
+            sender = "RRS"
+            sender_id = ""
+
+            def __init__(self, host, port):
+                self._conn = socket.create_connection((host, port), timeout=10)
+                # create_connection() leaves the connect timeout applied to
+                # the socket permanently; the background read loop below does
+                # a long-lived blocking recv() for async "sample" pushes, so
+                # it must not time out on an idle connection.
+                self._conn.settimeout(None)
+                self._send_lock = threading.Lock()
+                self._req_id = 0
+                self._req_lock = threading.Lock()
+                self._pending = {}
+                self._subs = {}  # sub_id -> callback
+                self._sub_by_keyexpr = {}
+                threading.Thread(target=self._read_loop, daemon=True).start()
+
+            def _next_id(self):
+                with self._req_lock:
+                    self._req_id += 1
+                    return self._req_id
+
+            def _read_loop(self):
+                while True:
+                    frame = _recv_frame(self._conn)
+                    if frame is None:
+                        return
+                    ftype = frame.get("type")
+                    if ftype == "sample":
+                        cb = self._sub_by_keyexpr.get(frame["keyexpr"])
+                        if cb is not None:
+                            try:
+                                cb(frame["key"], bytes.fromhex(frame["payload_hex"]), frame.get("att", ""))
+                            except Exception as exc:
+                                print(f"[muscat-pk] proxy subscriber callback error: {exc}", flush=True)
+                    elif "id" in frame:
+                        ev = self._pending.pop(frame["id"], None)
+                        if ev is not None:
+                            ev[1] = frame
+                            ev[0].set()
+
+            def _request(self, obj, timeout=30):
+                req_id = self._next_id()
+                obj["id"] = req_id
+                ev = threading.Event()
+                slot = [ev, None]
+                self._pending[req_id] = slot
+                _send_frame(self._conn, self._send_lock, obj)
+                if not ev.wait(timeout):
+                    self._pending.pop(req_id, None)
+                    raise TimeoutError(f"proxy request timed out: {obj.get('type')} {obj.get('keyexpr')}")
+                return slot[1]
+
+            def query(self, keyexpr, payload, timeout_ms, target):
+                resp = self._request({
+                    "type": "query", "keyexpr": keyexpr,
+                    "payload_hex": payload.hex() if payload else None,
+                    "timeout_ms": timeout_ms, "target": target,
+                }, timeout=(timeout_ms / 1000) + 5)
+                if not resp.get("ok"):
+                    raise RuntimeError(resp.get("error", "proxy query failed"))
+                return [
+                    (r["key"], bytes.fromhex(r["payload_hex"]), r["att"], r["encoding"], r["is_error"])
+                    for r in resp["replies"]
+                ]
+
+            def query_all(self, keyexpr, payload, timeout_ms, target):
+                return self.query(keyexpr, payload, timeout_ms, target)
+
+            def publish(self, topic, payload, att, congestion_control, priority, express):
+                resp = self._request({
+                    "type": "put", "keyexpr": topic,
+                    "payload_hex": bytes(payload).hex() if payload else None,
+                })
+                if not resp.get("ok"):
+                    raise RuntimeError(resp.get("error", "proxy put failed"))
+
+            def has_subscriber(self, topic):
+                return topic in self._sub_by_keyexpr
+
+            def declare_subscriber(self, topic, callback, opts=None):
+                resp = self._request({"type": "subscribe", "keyexpr": topic})
+                if not resp.get("ok"):
+                    raise RuntimeError(resp.get("error", "proxy subscribe failed"))
+                sub_id = self._next_id()
+                self._subs[sub_id] = topic
+                self._sub_by_keyexpr[topic] = callback
+                return sub_id
+
+            def undeclare_subscriber(self, sub_id):
+                topic = self._subs.pop(sub_id, None)
+                if topic is None:
+                    return
+                self._sub_by_keyexpr.pop(topic, None)
+                self._request({"type": "unsubscribe", "keyexpr": topic})
+
+            def unsubscribe_topic(self, topic):
+                for sub_id, t in list(self._subs.items()):
+                    if t == topic:
+                        self.undeclare_subscriber(sub_id)
+
+            def unsubscribe_all(self):
+                for sub_id in list(self._subs):
+                    self.undeclare_subscriber(sub_id)
+
+            def get_sub_stats(self, sub_id):
+                return {}
+
+            def declare_queryable(self, keyexpr, handler):
+                raise NotImplementedError("byte-proxy mode does not support declare_queryable")
+
+            def undeclare_queryable_by_topic(self, keyexpr):
+                pass
+
+        # ZenohClient is a process-wide singleton whose __init__ eagerly
+        # calls connect() on first construction. rainbow.rb_sdk.base
+        # transitively imports rainbow.rb_log.log, which constructs one at
+        # module level — so this patch must land before RBBaseSDK is
+        # imported, or that eager construction wins with a real session.
+        from rainbow.rb_zenoh.client import ZenohClient
+
+        def _proxy_connect(self, *, config_pairs=None, sender=None, max_attempts=8, initial_delay_s=0.5, max_delay_s=3.0):
+            if self._client is not None:
+                return
+            if sender is not None:
+                self._sender = sender
+            print(f"[muscat-pk] zenoh via host byte-proxy → {proxy_endpoint} (no local Zenoh session)", flush=True)
+            self._client = _ProxyRawClient(_proxy_host, _proxy_port)
+
+        ZenohClient.connect = _proxy_connect
 
-    if host_agent_url:
-        print(f"[muscat-pk] host SDK agent mode: {host_agent_url}", flush=True)
-        install_host_agent_sdk_patch(host_agent_url)
+        from rainbow.rb_sdk.base import RBBaseSDK
+
+        async def _sdk_connect_via_proxy(self, *args, **kwargs):
+            # No HTTP registration with common — host_agent already handles
+            # that. Just make sure the (proxy-backed) shared ZenohClient exists.
+            self._ensure_zenoh_client_alive()
+            return None
+
+        async def _sdk_disconnect_via_proxy(self, *args, **kwargs):
+            return None
+
+        RBBaseSDK.connect = _sdk_connect_via_proxy
+        RBBaseSDK.disconnect = _sdk_disconnect_via_proxy
     else:
+        # Fallback: no host byte-proxy — the container reverse-dials the robot itself.
+        advertise_host = os.getenv("MUSCAT_ZENOH_ADVERTISE_HOST")
+        zenoh_port = os.getenv("MUSCAT_ZENOH_PORT")
         from rainbow.rb_sdk.base import RBBaseSDK
         if advertise_host:
             RBBaseSDK._detect_local_ip = staticmethod(lambda host: advertise_host)
@@ -224,8 +358,8 @@ runpy.run_path("/plugin/py/main.py", run_name="__main__")
 PY`]);
 
   if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
-  if (!hostAgentUrl && zenohAdvertiseHost && zenohPort) log.step(`Zenoh advertise → ${zenohAdvertiseHost}:${zenohPort}`);
-  if (hostAgentUrl) log.step(`host SDK agent → ${hostAgentUrl}`);
+  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/)");
   const child = spawn(
     "docker",
@@ -445,9 +579,9 @@ export async function runDevBack(args = []) {
   if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
   // Standalone `dev:back` against a remote robot needs the Zenoh reverse-path
   // advertise host/port too (idempotent — `muscat-pk dev` already set these).
-  // Host-agent mode routes robot SDK calls through the mac host, so the Docker
-  // backend does not need its own remote Zenoh peer.
-  if (!process.env.MUSCAT_HOST_AGENT_URL) await ensureRemoteZenohEnv(robotIp, { log });
+  // Byte-proxy mode (a host-side host_agent set MUSCAT_PROXY_ENDPOINT) makes
+  // the container speak the proxy protocol instead, so it needs no reverse-dial.
+  if (!process.env.MUSCAT_PROXY_ENDPOINT) await ensureRemoteZenohEnv(robotIp, { log });
   const type = manifestRuntime(root);
   if (type === "ros2") return await runRos2(root, portRanges);
   if (type === "cpp") return await runCpp(root, portRanges);

package/cli/src/host_agent.py

@@ -0,0 +1,162 @@
+"""Host-side raw Zenoh byte-proxy.
+
+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.
+
+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 asyncio
+import contextlib
+import json
+import os
+import socket
+import struct
+import threading
+
+
+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 _handle_conn(conn: socket.socket, zenoh_client) -> None:
+    send_lock = threading.Lock()
+    sub_ids: dict[str, int] = {}
+    try:
+        while True:
+            req = _recv_frame(conn)
+            if req is None:
+                return
+            op = req.get("type")
+
+            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}"})
+    except (ConnectionResetError, BrokenPipeError, OSError):
+        pass
+    finally:
+        for sub_id in sub_ids.values():
+            try:
+                zenoh_client._client.undeclare_subscriber(sub_id)
+            except Exception:
+                pass
+        conn.close()
+
+
+def main() -> None:
+    from rainbow.rb_sdk.base import RBBaseSDK
+
+    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)
+
+    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)
+
+    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, peer.zenoh_client), daemon=True).start()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        with contextlib.suppress(Exception):
+            asyncio.run(peer.disconnect())
+
+
+if __name__ == "__main__":
+    main()

package/cli/src/new.mjs

@@ -12,7 +12,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
-import { ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
+import { color, ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
 
 // Like cpSync(src, dst, {recursive:true}) but reads from the embedded snapshot
 // when the templates dir doesn't exist on disk (compiled binary mode).
@@ -40,6 +40,33 @@ export const TYPE_CHOICES = {
 const TYPES = Object.keys(TYPE_CHOICES);
 const PMS = ["npm", "yarn", "pnpm", "bun"];
 
+function printNewSuccess({ targetName, type, pm }) {
+  const mark = [
+    "             /\\",
+    "            /  \\_",
+    "       ____||__",
+    "      /  \\__/  \\",
+    "   __ \\__/  \\__/ __",
+    "  /  \\__/\\__/\\__/  \\",
+    "  \\__/  \\__/  \\__/",
+    "     \\__/  \\__/",
+    "        \\__/",
+  ].map((line) => color.green(line)).join("\n");
+
+  log.info("");
+  log.info(mark);
+  log.info(color.bold(color.green("Welcome to Muscat Plugin Kit!")));
+  log.info(color.dim("A fresh plugin workspace is ready."));
+  log.info("");
+  log.ok(`created ${color.bold(targetName)} ${color.dim(`(type: ${type}, pm: ${pm})`)}`);
+  log.info("");
+  log.info(color.bold("Next steps"));
+  log.info(`  ${color.cyan("cd")} ${targetName}`);
+  log.info(`  ${color.cyan("muscat-pk dev")}      ${color.dim("# preview in mini-Muscat + back end")}`);
+  log.info(`  ${color.cyan("muscat-pk build")}    ${color.dim("# build + distributable ZIP")}`);
+  log.info("");
+}
+
 // Build the manifest runtime object for a given type choice + plugin slug.
 export function runtimeForChoice(choice, slug) {
   switch (choice.type) {
@@ -130,7 +157,7 @@ export async function runNew(args) {
 
   const dirArg = opts._[0];
   const targetName =
-    dirArg || (await prompt("Plugin directory name: ", "my-plugin"));
+    dirArg || (await prompt(color.cyan("Plugin directory name: "), "my-plugin"));
   const target = resolve(process.cwd(), targetName);
   if (existsSync(target) && readdirSync(target).length > 0) {
     throw new Error(`directory not empty: ${target}`);
@@ -141,19 +168,19 @@ export async function runNew(args) {
   let descriptionArg = opts.description;
 
   if (!opts.yes) {
-    if (!authorArg) authorArg = await prompt("Author name: ", "");
-    if (!emailArg) emailArg = await prompt("Email (required): ", "");
-    if (!descriptionArg) descriptionArg = await prompt("Description (English): ", "");
+    if (!authorArg) authorArg = await prompt(color.cyan("Author name: "), "");
+    if (!emailArg) emailArg = await prompt(`${color.cyan("Email")} ${color.yellow("(required)")}: `, "");
+    if (!descriptionArg) descriptionArg = await prompt(color.cyan("Description (English): "), "");
   }
 
   let type = opts.type;
   if (!type && !opts.yes) {
-    console.log("\nSelect the plugin type:");
-    console.log("  1) Python");
-    console.log("  2) C++");
-    console.log("  3) ROS2 (rclpy / Python)");
-    console.log("  4) ROS2 (rclcpp / C++)");
-    const choice = await prompt("\n선택 [1/2/3/4, default: 1]: ", "1");
+    console.log(`\n${color.bold(color.cyan("Select the plugin type:"))}`);
+    console.log(`  ${color.green("1)") } ${color.bold("Python")}`);
+    console.log(`  ${color.green("2)") } ${color.bold("C++")}`);
+    console.log(`  ${color.green("3)") } ${color.bold("ROS2")} ${color.dim("(rclpy / Python)")}`);
+    console.log(`  ${color.green("4)") } ${color.bold("ROS2")} ${color.dim("(rclcpp / C++)")}`);
+    const choice = await prompt(`\n${color.cyan("선택")} ${color.dim("[1/2/3/4, default: 1]")}: `, "1");
     type = { "2": "cpp", "3": "ros2", "4": "ros2-cpp" }[choice] ?? "python";
   }
   type = TYPES.includes(type) ? type : "python";
@@ -173,7 +200,10 @@ export async function runNew(args) {
   let pm = opts.pm;
   if (!pm && !opts.yes) {
     const defaultPm = isInsideYarnWorkspace(process.cwd()) ? "yarn" : "npm";
-    pm = await prompt(`Front-end package manager (${PMS.join("/")}) [${defaultPm}]: `, defaultPm);
+    pm = await prompt(
+      `${color.cyan("Front-end package manager")} ${color.dim(`(${PMS.join("/")})`)} ${color.dim(`[${defaultPm}]`)}: `,
+      defaultPm,
+    );
   }
   pm = PMS.includes(pm) ? pm : "npm";
 
@@ -244,15 +274,29 @@ export async function runNew(args) {
     }
   }
 
+  // git init (best-effort, matches create-react-app/vite scaffolds). Skipped
+  // if git isn't installed or the target is already inside a repo (nested
+  // packages in a monorepo shouldn't get their own .git).
+  if (hasBin("git")) {
+    try {
+      execSync("git rev-parse --is-inside-work-tree", { cwd: target, stdio: "ignore" });
+    } catch {
+      try {
+        execSync("git init", { cwd: target, stdio: "ignore" });
+        execSync("git add -A", { cwd: target, stdio: "ignore" });
+        execSync('git commit -m "Initial commit from muscat-pk new" --no-verify', { cwd: target, stdio: "ignore" });
+      } catch {
+        log.warn("git init failed — run it manually if you want version control here.");
+      }
+    }
+  }
+
   // The back end (python / cpp / ros2) runs in a Docker container that matches
   // the robot — no local Python/toolchain setup needed. Only `none` skips it.
   const needsDocker = runtimeChoice.type !== "none";
   const noDocker = needsDocker && !hasBin("docker");
 
-  log.ok(`created ${targetName} (type: ${type}, pm: ${pm})`);
-  log.info(`\n  cd ${targetName}`);
-  log.info(`  muscat-pk dev      # preview in mini-Muscat + back end`);
-  log.info(`  muscat-pk build    # build + distributable ZIP\n`);
+  printNewSuccess({ targetName, type, pm });
 
   // ── post-scaffold environment warnings ───────────────────────────────────
   const noNode = !hasBin("node");

package/cli/src/util.mjs

@@ -141,16 +141,26 @@ export function findPluginRoot(start = process.cwd()) {
   );
 }
 
-const RED    = "\x1b[31m";
-const ORANGE = "\x1b[33m";
-const RESET  = "\x1b[0m";
+const useColor = process.env.NO_COLOR !== "1" && (process.stdout.isTTY || process.env.FORCE_COLOR);
+const ansi = (code) => (s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+
+export const color = {
+  bold: ansi("1"),
+  dim: ansi("2"),
+  red: ansi("31"),
+  green: ansi("32"),
+  yellow: ansi("33"),
+  blue: ansi("34"),
+  magenta: ansi("35"),
+  cyan: ansi("36"),
+};
 
 export const log = {
   info:  (...m) => console.log(...m),
-  step:  (...m) => console.log("›", ...m),
-  ok:    (...m) => console.log("✓", ...m),
-  warn:  (...m) => console.warn(`${ORANGE}⚠${RESET}`, ...m.map(s => `${ORANGE}${s}${RESET}`)),
-  error: (...m) => console.error(`${RED}✖${RESET}`, ...m.map(s => `${RED}${s}${RESET}`)),
+  step:  (...m) => console.log(color.cyan("›"), ...m),
+  ok:    (...m) => console.log(color.green("✓"), ...m),
+  warn:  (...m) => console.warn(color.yellow("⚠"), ...m.map(s => color.yellow(s))),
+  error: (...m) => console.error(color.red("✖"), ...m.map(s => color.red(s))),
 };
 
 // dev / dev:back / build run the plugin back end, the dev bridge, and cpp/ros2

package/cli/storybook-dist/project.json

@@ -1 +1 @@
-{"generatedAt":1783659929067,"userSince":1750932757926,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}
+{"generatedAt":1783908008319,"userSince":1750932757926,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "0.1.2-dev.52",
+  "version": "0.1.2-dev.53",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -53,8 +53,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@rainbow-robotics/plugin-ui": "0.1.2-dev.52",
-    "@rainbow-robotics/preview-host": "0.1.2-dev.52",
+    "@rainbow-robotics/plugin-ui": "0.1.2-dev.53",
+    "@rainbow-robotics/preview-host": "0.1.2-dev.53",
     "postcss": "^8.5.8",
     "socket.io": "^4.8.1",
     "typescript": "^5.8.0",