@rainbow-robotics/muscat-plugin-kit 1.1.5 → 1.3.0

package/cli/storybook-dist/iframe.html

@@ -509,7 +509,7 @@
   }
 </script>
 
-    <script type="module" crossorigin src="./assets/iframe-BwCxSq5d.js"></script>
+    <script type="module" crossorigin src="./assets/iframe-DsvRKHwc.js"></script>
   </head>
 
   <body>

package/cli/storybook-dist/project.json

@@ -1 +1 @@
-{"generatedAt":1787013792240,"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":1789632370434,"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/cli/templates/common/README.md

@@ -398,6 +398,103 @@ if __name__ == "__main__":
         time.sleep(1)
 ```
 
+#### External endpoints (`plugin.router`)
+
+`plugin.serve` / `plugin.subscribe` / `plugin.publish` are **internal only** (plugin
+UI ↔ backend, plugin ↔ plugin). To expose an endpoint to the outside world —
+REST, Socket.IO, TCP, MQTT, WebRTC — use `plugin.router`. Declaring one is a
+single decorator; the running Muscat (`common`) picks it up without a restart,
+and it disappears when the plugin stops or is removed.
+
+> Requires a robot running `rainbow-rb-sdk` **0.0.9.dev5 or newer** (the SDK is
+> provided by the plugin container at runtime). On older robots `plugin.router`
+> does not exist and raises `AttributeError`.
+
+```python
+from rainbow.rb_sdk import RBPluginCall
+from rainbow.rb_sdk.plugin import PluginRouteError
+
+plugin = RBPluginCall()  # plugin_id comes from env RB_PLUGIN_ID
+
+
+@plugin.router.on("/hello")                                  # all 5 transports
+def hello(payload: dict, meta: dict):
+    return {"msg": f"hi {payload.get('name')}"}              # return value = response body
+
+
+@plugin.router.on("/admin", explicit_routes=["api"])         # REST only
+def admin(payload, meta):
+    if not (meta.get("principal") or {}).get("is_admin"):
+        raise PluginRouteError(403, "admin only")            # becomes the external status
+    ...
+
+
+@plugin.router.subscribe("/cmd", explicit_events=["tcp"])    # receive external TCP publish
+def on_cmd(payload: dict):
+    ...
+
+
+plugin.router.emit("/state", {"busy": True})                 # push to external subscribers
+```
+
+| API | Meaning | External address |
+| --- | --- | --- |
+| `router.on(path, explicit_routes=None)` | request/response handler | `common/plugin/{plugin_id}/{path}` (REST is always `POST`) |
+| `router.subscribe(topic, explicit_events=None)` | receive external publishes | external side publishes to `common/plugin/{plugin_id}/{topic}` |
+| `router.emit(topic, payload)` | plugin → external push | external side subscribes to `common/plugin/{plugin_id}/{topic}` |
+
+- The `plugin_id` prefix is added by the SDK — write only the path in plugin code.
+- Paths may have several segments (`/tool/echo`). Declaring the same path twice raises `ValueError`.
+- Transport names: `api | socket | tcp | mqtt | webrtc`. `subscribe` accepts only `tcp | mqtt | webrtc`. Unknown names raise `ValueError`.
+- `explicit_routes` / `explicit_events` of `None` means every transport. A request on a transport not listed gets 404.
+
+Handler contract:
+
+- Signature `(payload, meta)`, `(payload)` or `()` — only the arguments you declare are injected. Sync and async both work.
+- `payload`: what the caller sent (for REST: JSON body merged with query params). The shape is up to the plugin.
+- `meta`: `{"transport": "api"|"socket"|"tcp"|"mqtt"|"webrtc", "principal": dict | None}`. When the robot's login policy is on, `principal` holds the token subject. **Role checks are the plugin's job** — inspect `meta["principal"]` yourself.
+- The return value is the response body (must be JSON-serialisable). `None` → empty response.
+- Status codes: `raise PluginRouteError(code, message)`. Any other exception → 500 with `str(exc)` as the message.
+- `subscribe` handlers take `(payload)` only and return nothing.
+
+#### Calling plugin endpoints from outside
+
+| Transport | How |
+| --- | --- |
+| REST | `POST /common/plugin/{plugin_id}/{path}` (through the api-gateway), JSON body |
+| Socket.IO | emit event `common/plugin/{plugin_id}/{path}`, response arrives in the ack |
+| TCP | topic `common/plugin/{plugin_id}/{path}` request / publish |
+| MQTT | request: `common/plugin/{plugin_id}/{path}/__req__`, publish: `common/plugin/{plugin_id}/{topic}` |
+| WebRTC | data channel topic `common/plugin/{plugin_id}/{path}` |
+
+Auth: when the robot's login policy is on, a token is **required** (any role — GUEST passes). When it is off, calls go straight through. REST uses the same Bearer token as the other Muscat APIs.
+
+```bash
+curl -s -X POST http://<robot>/common/plugin/my-plugin/hello \
+  -H 'Content-Type: application/json' -d '{"name":"kim"}'
+```
+
+| Situation | Status |
+| --- | --- |
+| No plugin declares that path / plugin is down / transport not allowed | 404 |
+| Plugin did not answer within 10 s | 504 |
+| `common` ↔ gateway not connected | 503 |
+| Handler raised | 500 (`PluginRouteError` → its `code`) |
+
+Known limits:
+
+- A plugin path named `install` cannot be called over REST (`POST /common/plugin/{id}/install` is taken by the registry install route first). Socket/TCP are unaffected.
+- Swagger shows one catch-all route, not per-plugin paths.
+- The MQTT broker echoes to the sender: a plugin that `emit`s and `subscribe`s the same topic receives its own push over `mqtt`. Drop `mqtt` from `explicit_events` or use separate topics. (TCP is filtered by `sender_id`.)
+- `on` and `subscribe` may share a name — they live in separate tables.
+
+During `muscat-pk dev` / `dev:back` the local bridge (port `10000`) accepts the
+`router.*` registrations, but **external calls need a running `common`** — it is
+`common` that routes `common/plugin/...` to the gateway. Use a robot (or a local
+`common`) to exercise the external addresses. After restarting the plugin process,
+external calls may return 504 for up to about a minute (until the gateway notices
+the old socket is gone), then 404 — that is expected.
+
 #### Program command backend (`program.panel`)
 
 A `program.panel` contribution defines a **custom command** your plugin adds to
@@ -439,34 +536,206 @@ ctx = PluginProgramContext(plugin_id="my-plugin")
 
 @ctx.on_execute
 async def handle(args: dict) -> None:
-    message = args.get("message", "")
-    print(f"[my-plugin] execute called: message={message}", flush=True)
+    """Called once when my Step executes. Variable writes apply to the
+    running program immediately + broadcast to other robots' main tasks."""
+    count = await ctx.get_variable("counter")          # read an existing program variable
+    await ctx.set_variable("counter", count + 1)       # update an existing variable — allowed
+    await ctx.set_variable("RBP_TEST", 1)              # NEW variables must start with RBP_
 
-    # check stop/pause during long-running work
-    for _ in range(10):
-        await ctx.check_stop()
-        await asyncio.sleep(0.1)
+    for i in range(100):
+        await ctx.check_stop()   # auto-scoped to this Step's robot model
+        await asyncio.sleep(0.5)
 
-    # read a program variable
-    counter = await ctx.get_variable("counter")
-    print(f"[my-plugin] counter={counter}", flush=True)
+    await ctx.done()
 
-    # update a variable
-    await ctx.set_variable("result", f"done: {message}")
 
-    # finish the step
-    await ctx.done()
+async def background_monitor() -> None:
+    """Resident task outside any Step. If no program is running,
+    get returns None and set is silently ignored — always safe to call."""
+    while True:
+        await asyncio.sleep(1.0)
 
+        # targets every running main task (no robot_model param — always broadcast)
+        await ctx.set_variable("RBP_TEST", 3)
 
-if __name__ == "__main__":
-    asyncio.run(ctx.start())
+        # get options
+        v1 = await ctx.get_variable("counter")                           # first value found in the whole tree
+        v2 = await ctx.get_variable("counter", robot_model="C500920")    # a specific robot
+        v3 = await ctx.get_variable("RBP_TEST", plugin_id="my-plugin")   # the value my-plugin last wrote
+
+        if ctx.executor_state("C500920") == "paused":
+            print("C500920 program is paused")
+
+
+async def main() -> None:
+    asyncio.create_task(background_monitor())
+    await ctx.start()  # stays resident
+
+
+asyncio.run(main())
+```
+
+#### Program variables & executor state (`PluginProgramContext`)
+
+`rainbow.rb_sdk.PluginProgramContext` lets the plugin process interact with the
+running program (PyFM): read/write program variables and observe execution
+state — inside a Step handler or from a resident task, at any time.
+
+- The `on_execute` handler is called **only when PyFM executes this plugin's
+  Step**. One Step execution = one handler call, and the Step does not finish
+  until you call `ctx.done()` — always call it.
+- The plugin process itself stays resident after `ctx.start()`; executor state
+  queries and variable access below keep working whether or not a Step is
+  executing.
+
+#### Variable naming rules (important)
+
+PyFM variables are a **program-wide shared namespace**. One rule:
+
+- **Modifying an existing variable** — the name passes as-is. Exchanging
+  variables between the program and the plugin is the intended usage.
+- **Creating a variable that doesn't exist** — the `RBP_` prefix is
+  **required** (enforced by the SDK/server; a violation raises
+  `RuntimeError`). Applies equally inside and outside Step execution.
+
+For new variable names, a convention that includes the plugin id is strongly
+recommended:
+
+```
+RBP_{plugin_id}_{name}
+
+e.g. RBP_vision_detect_count, RBP_gripper_last_error
+```
+
+Why:
+
+- `RBP_` — instantly identifies plugin-created variables in the program
+  editor/UI.
+- `{plugin_id}` — **prevents name collisions with other plugins.** If two
+  plugins use the same name they overwrite the same variable (`RBP_` alone is
+  not something the SDK guards against).
+
+#### Reading / writing variables
+
+```python
+value = await ctx.get_variable("counter")                 # read (no name restriction)
+await ctx.set_variable("counter", value + 1)              # modify existing variable — allowed
+await ctx.set_variable("RBP_my-plugin_result", 42)        # create new variable — RBP_ required
+```
+
+`set_variable` always applies to **every running main task** (a plugin belongs
+to muscat, not to a specific robot — there is no `robot_model` parameter):
+
+| When | Own program | Other robots' main tasks |
+|---|---|---|
+| During own Step execution | via the control queryable — **immediate** | broadcast — each at its next Step boundary |
+| Outside a Step (resident task, …) | resident endpoint — next Step boundary | same |
+
+`get_variable` has options:
+
+```python
+await ctx.get_variable("counter")                          # search all main tasks (first value found)
+await ctx.get_variable("counter", robot_model="C500920")   # a specific robot's value
+await ctx.get_variable("RBP_TEST", plugin_id="A.plugin")   # the value that plugin last wrote
+```
+
+Caveats:
+
+- If no program is running, `set_variable` is **silently ignored** and
+  `get_variable` returns `None`. (`RuntimeError` is raised only for real
+  errors, like the `RBP_` violation on a new variable — the message is tagged
+  `[plugin:{id}]` with the offending plugin.)
+- Rarely, a write can be lost if it races the worker's variable flush
+  (lock-free read-modify-write). For important values, re-check and retry on
+  the next cycle.
+
+#### Per-plugin value storage (meta)
+
+Besides the shared value, each variable entry records which plugin last wrote
+what:
+
+```python
+# state_dict["variables"] — after A wrote 1 and B wrote 2
+"RBP_TEST": {
+    "value": 2,                                # shared slot = last written value
+    "type": "local",
+    "meta": {"writers": {"A.plugin": 1, "B.plugin": 2}},   # per-plugin record
+}
+```
+
+So the exact value is recoverable even when names collide:
+
+- Plugin SDK: `ctx.get_variable("RBP_TEST", plugin_id="A.plugin")` → `1`
+- Program step expression: `COUNT = get_var("A.plugin", "RBP_TEST") + 1` → `2`
+- A plain name (`RBP_TEST += 1`) uses the shared slot (last written value) → `3`
+
+#### Executor state
+
+Subscribes to the `muscat/executor/state` publish (0.8 s interval) and exposes
+per-robot-model state:
+
+```python
+ctx.executor_state("C500920")   # "running" | "paused" | "waiting" | ... | None
+ctx.executor_state()            # {"C500920": "paused", "amr": "running"}
+ctx.is_paused("C500920")        # whether that model is paused
+ctx.is_stopped("C500920")       # stop/error transition of a model seen active this run
+```
+
+- States: `idle | running | paused | waiting | stopped | post_start | completed | error`
+- A model with no running task is `None` / absent from the dict.
+- The publish interval is 0.8 s, so expect up to ~1 s of latency.
+- With `IS_DEV=true` there is no publish at all — always `None`.
+
+To get a callback at the moment the state changes, without polling:
+
+```python
+@ctx.on_executor_state_change
+async def on_change(robot_model: str, state: str) -> None:
+    if state == "paused":
+        print(f"{robot_model} paused")
 ```
 
+- Not called for repeated publishes of the same state — fires exactly once
+  per per-model state change.
+- An exception in the handler is only logged; state tracking keeps running.
+
+#### Responding to pause / stop
+
+```python
+@ctx.on_execute
+async def handle(args: dict) -> None:
+    for i in range(100):
+        # stop → CancelledError (propagated to the executor as a stop),
+        # pause → waits here until resumed.
+        # Inside on_execute this automatically watches only the robot model
+        # executing this Step.
+        await ctx.check_stop()
+
+        ...  # actual work
+        await asyncio.sleep(0.5)
+
+    await ctx.done()
+```
+
+Scope priority for `check_stop` / `is_paused` / `is_stopped`:
+
+1. `robot_model` given — that model only
+2. Omitted inside `on_execute` — **only the model executing this Step**
+   (passed in by the executor)
+3. Omitted elsewhere (resident task, …) — all models
+
+A handler doing long-running work must call `check_stop()` every loop
+iteration so it reacts to pause/stop immediately. Without it, the plugin keeps
+running even after the operator presses Stop.
+
+Variables your plugin wants the Program page variable picker to offer must be
+pre-declared in `manifest.json` under `"variables"` (see the manifest section
+below).
+
 ### C++
 
-C++ plugins use `cpp/` and are built with CMake inside Docker. The current C++
-template is a build/run skeleton; wire it to the plugin gateway when the C++ SDK
-is available.
+C++ plugins use `cpp/` and are built with CMake inside Docker against the
+Rainbow Robotics C++ SDK (see _C++ SDK_ below).
 
 ```cpp
 #include <chrono>
@@ -488,6 +757,25 @@ int main() {
 }
 ```
 
+#### C++ SDK (`rainbow-rb-sdk-dev`)
+
+Both C++ runtimes (`cpp`, `ros2` + `rclcpp`) link the Rainbow Robotics C++ SDK
+from the apt package `rainbow-rb-sdk-dev`. The `muscat-pk` dev containers already
+have it, so `muscat-pk dev` / `build` need nothing extra. To build outside the
+container (your own Ubuntu 24.04 machine, or the robot PC):
+
+```bash
+curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/rb-sdk-apt.gpg
+echo 'deb [signed-by=/usr/share/keyrings/rb-sdk-apt.gpg] https://rainbowrobotics.github.io/rb-sdk dev main' | sudo tee /etc/apt/sources.list.d/rb-sdk.list
+sudo apt update && sudo apt install rainbow-rb-sdk-dev=0.1.2~dev1
+```
+
+- CMake: `find_package(rb_sdk REQUIRED)` + `target_link_libraries(<target> rb_sdk::rb_sdk)` (C++20). pkg-config: `rb_sdk`.
+- Headers: `<rainbow/rb_sdk/manipulate/rb_manipulate_sdk.hpp>` (`RBManipulateSDK`),
+  `<rainbow/rb_sdk/program/plugin_program_context.hpp>` (`rb_plugin::PluginProgramContext`, for `program.panel` commands — the header's top comment has a full `main()` example).
+- The binary is linked **dynamically** (`librb_sdk.so.<version>` by SONAME) and the robot provides that `.so`. Pin the SDK to the robot's version: the dev image default is `0.1.2~dev1`; change it with `MUSCAT_PK_RB_SDK_VERSION=<version> MUSCAT_PK_REBUILD_IMAGE=1 muscat-pk dev`. Do not bundle or static-link the SDK.
+- UI ↔ backend messaging (`RBPluginCall` pub/sub/serve) is Python-only for now.
+
 ### ROS2 (rclpy)
 
 ROS2 Python plugins use `ros2_ws/` with `runtime.rosClient: "rclpy"`. The node
@@ -511,7 +799,8 @@ class __PLUGIN_CLASS__Node(Node):
 
 ### ROS2 (rclcpp)
 
-ROS2 C++ plugins use `ros2_ws/` with `runtime.rosClient: "rclcpp"`.
+ROS2 C++ plugins use `ros2_ws/` with `runtime.rosClient: "rclcpp"`. The node links
+the Rainbow C++ SDK the same way as the `cpp` runtime (see _C++ SDK_ above).
 
 ```cpp
 #include "rclcpp/rclcpp.hpp"
@@ -588,6 +877,15 @@ public:
     }
   ],
 
+  // optional: variables this plugin exposes to pyfm programs — the Program
+  // page variable picker lists ONLY declared variables. name must start with
+  // RBP_; description is optional but without it the UI can't explain the
+  // variable, so write one.
+  "variables": [
+    { "name": "RBP_grip_force", "type": "number", "init": 0.5, "description": { "ko": "그리퍼 힘", "en": "Gripper force" } },
+    { "name": "RBP_target_pose", "type": "array", "init": [0, 0, 0] }
+  ],
+
   // runtime — one of:
   //   { "type": "none" }
   //   { "type": "python", "entry": "main.py" }
@@ -654,15 +952,36 @@ public:
 - `commandInfo` — required when `point` is `"program.panel"`
 - `ports` — optional `number[]`; every port must be within `28600-28999`
   and must not be a reserved robot/industrial/internal port
+- `variables` — optional array of `{ name, type, init, description? }`:
+  - `name` — must start with `RBP_`, then letters/digits/underscore; unique per plugin
+  - `type` — `"number" | "string" | "array"`
+  - `init` — required initial value, must match `type`
+  - `description` — optional `string` or i18n object (`en` required in object form)
 
-`muscat-pk build` throws on any validation error. `muscat-pk dev` prints warnings.
+`muscat-pk build` throws on any validation error. `muscat-pk dev` prints
+warnings — except `variables` errors (e.g. a name without the `RBP_` prefix),
+which are hard errors in `dev` / `dev:back` too.
 
 **Backend port rules:**
 - Declare a port only if your backend opens a TCP server/listener.
-- `muscat-pk dev` and `muscat-pk dev:back` stop the backend if it opens an
-  undeclared managed port.
+- **Every listening TCP port must be declared.** `muscat-pk dev` and
+  `muscat-pk dev:back` watch the backend and stop it the moment it opens a port
+  that is not in `ports`. A port outside `28600-28999` can't be declared, so it
+  must not be opened either — picking e.g. `5500` is not a way around the rule.
+  It would escape this check *and* the robot's install-time conflict check, and
+  only collide once it's running on a robot.
 - Reserved ports include `502`, `2222`, `4840`, `5170-5179`, `8000-8999`,
   `10000`, `30004`, `34964`, `44818`, `50000-50005`, and `50051`.
+- The robot rejects installation (HTTP 409) if a declared port is reserved,
+  out of range, or already claimed by another enabled plugin.
+
+**Reaching your backend's ports during development:**
+- Declared ports are published to `127.0.0.1` on your machine, so
+  `curl http://127.0.0.1:28600` works from the host on macOS, Windows, and Linux.
+- On native Linux the dev container uses host networking, so the ports are on
+  the host already.
+- If a declared port is already taken on your machine, `muscat-pk dev` warns and
+  skips publishing that one — the backend still listens inside the container.
 
 ---
 
@@ -740,7 +1059,9 @@ letting it guess. `muscat-pk mcp` is an MCP server exposing:
 - `search_rb_sdk` — how to use `useRb()`, `rb.*`, `useRbFormData`/`useRbSave`, and
   the backend runtimes.
 - `list_rb_sdk` / `get_rb_sdk_api` — the installed `rainbow-rb-sdk` (Python
-  backend) classes and signatures.
+  backend) classes and signatures; with `lang: "cpp"`, the C++ SDK headers
+  (`rainbow-rb-sdk-dev`, read out of the `muscat-pk` cpp dev image — build it
+  once with `muscat-pk dev:back`).
 
 **Browse the components live** with `muscat-pk storybook`.
 
@@ -760,7 +1081,14 @@ it works out of the box:
 }
 ```
 
-**Codex** — add to `~/.codex/config.toml`:
+**Codex** — register once with:
+
+```bash
+muscat-pk mcp --install codex
+```
+
+This appends the server to `~/.codex/config.toml` (idempotent — safe to run
+again). Equivalent manual config:
 
 ```toml
 [mcp_servers.muscat]

package/cli/templates/common/manifest.json

@@ -21,5 +21,6 @@
       "opens": "popover"
     }
   ],
+  "variables": [],
   "runtime": { "type": "__RUNTIME_TYPE__", "entry": "main.py" }
 }

package/cli/templates/common/py/main.py

@@ -10,6 +10,13 @@ Remote dev (from your laptop):
     MUSCAT_ROBOT_HOST=192.168.1.100
     MUSCAT_ROBOT_TOKEN=<service token>
   Then: muscat-pk dev:back
+
+Handlers:
+  plugin.serve / plugin.subscribe / plugin.publish  -> plugin UI <-> backend only
+  plugin.router.on / subscribe / emit               -> external endpoints
+    (REST / Socket.IO / TCP / MQTT / WebRTC at common/plugin/<plugin_id>/<path>).
+    Needs a robot running rainbow-rb-sdk >= 0.0.9.dev5; older robots have no
+    `plugin.router` (AttributeError). See README "External endpoints".
 """
 
 import asyncio
@@ -29,6 +36,8 @@ def register_handlers():
     # Register handlers here — called after connect() so subscriptions survive
     # session reconnection in remote-dev mode.
 
+    # --- Plugin UI <-> backend (not reachable from outside Muscat) ---
+
     @plugin.subscribe("event")
     def on_ui_event(payload: dict[str, Any] | None = None):
         """Handle messages published from the plugin UI with rb.pub("event", ...)."""
@@ -47,6 +56,19 @@ def register_handlers():
         """Small query example callable from the UI with rb.action("tool/echo", ...)."""
         return {"echo": payload, "plugin": PLUGIN_NAME}
 
+    # --- External endpoints (REST / Socket.IO / TCP / MQTT / WebRTC) ---
+    # Exposed as common/plugin/<plugin_id>/hello, e.g.
+    #   curl -X POST http://<robot>/common/plugin/<plugin_id>/hello \
+    #        -H 'Content-Type: application/json' -d '{"name": "kim"}'
+    # Restrict transports with explicit_routes=["api"] (REST only), etc.
+    # Raise PluginRouteError(403, "msg") to set the response status.
+
+    @plugin.router.on("/hello")
+    def hello(payload: dict[str, Any] | None = None, meta: dict[str, Any] | None = None):
+        """meta = {"transport": "api"|"socket"|"tcp"|"mqtt"|"webrtc", "principal": dict | None}."""
+        name = (payload or {}).get("name", "there")
+        return {"msg": f"hi {name}", "via": (meta or {}).get("transport")}
+
 
 def move_j_example():
     """
@@ -77,7 +99,8 @@ async def main():
 
     register_handlers()
 
-    plugin.publish("state", {"ready": True, "plugin": PLUGIN_NAME})
+    plugin.publish("state", {"ready": True, "plugin": PLUGIN_NAME})       # -> plugin UI
+    plugin.router.emit("/state", {"ready": True, "plugin": PLUGIN_NAME})  # -> external subscribers of common/plugin/<plugin_id>/state
     print(f"[{PLUGIN_NAME}] backend ready")
 
     try:

package/cli/templates/common/requirements.txt

@@ -1,4 +1,4 @@
-rainbow-rb-sdk==0.0.79
-rainbow-rb-flat-buffers==0.0.79
-rainbow-rb-zenoh==0.0.79
+rainbow-rb-sdk==0.1.1
+rainbow-rb-flat-buffers==0.1.1
+rainbow-rb-zenoh==0.1.1
 requests==2.34.2

package/cli/templates/cpp/cpp/CMakeLists.txt

@@ -1,14 +1,14 @@
 cmake_minimum_required(VERSION 3.16)
 project(__PLUGIN_SLUG__ CXX)
 
-set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
+# Rainbow Robotics C++ SDK — provided by the apt package rainbow-rb-sdk-dev
+# (pre-installed in the muscat-pk dev container). Linked dynamically: the robot
+# ships the matching librb_sdk.so, so do NOT bundle or static-link it.
+find_package(rb_sdk REQUIRED)
+
 # The executable name must match runtime.entry in manifest.json.
 add_executable(__PLUGIN_SLUG__ main.cpp)
-
-# TODO(cpp-sdk): link the rainbow cpp SDK dynamically (the robot provides the
-# .so at runtime — do NOT bundle/static-link it). Once the SDK ships an apt
-# package with CMake config, enable:
-#   find_package(rainbow_cpp_sdk REQUIRED)
-#   target_link_libraries(__PLUGIN_SLUG__ PRIVATE rainbow::cpp_sdk)
+target_link_libraries(__PLUGIN_SLUG__ PRIVATE rb_sdk::rb_sdk)

package/cli/templates/cpp/cpp/main.cpp

@@ -1,9 +1,16 @@
 // __PLUGIN_NAME__ — C++ plugin back end.
 //
-// The C++ plugin SDK is not available yet, so this is a build/run skeleton.
-// Once the SDK lands, connect to the plugin gateway here (the host exposes it
-// at the RB_PLUGIN_GATEWAY / RB_PLUGIN_ID environment variables) and wire up
-// pub / sub / serve, mirroring the Python rainbow.rb_sdk.RBPluginCall API.
+// The Rainbow Robotics C++ SDK (apt: rainbow-rb-sdk-dev) is installed in the
+// dev container and linked via CMake (rb_sdk::rb_sdk). Headers live under
+// <rainbow/rb_sdk/...>:
+//   - manipulate/rb_manipulate_sdk.hpp   RBManipulateSDK — control the robot
+//   - program/plugin_program_context.hpp rb_plugin::PluginProgramContext —
+//                                        program.panel commands (done/pause/stop,
+//                                        program variables); see the header's
+//                                        top comment for a full main() example
+// UI <-> backend messaging (RBPluginCall pub/sub/serve) is Python-only for now.
+
+#include <rainbow/rb_sdk/manipulate/rb_manipulate_sdk.hpp>
 
 #include <chrono>
 #include <cstdlib>
@@ -17,8 +24,8 @@ int main() {
             << (plugin_id ? std::string(" (id=") + plugin_id + ")" : "")
             << std::endl;
 
-  // TODO: connect to the plugin gateway and register handlers once the
-  //       C++ SDK is available. For now, just keep the process alive.
+  // e.g. RBManipulateSDK manipulate; manipulate.move.call_move_j(...);
+  // Keep the process alive.
   while (true) {
     std::this_thread::sleep_for(std::chrono::seconds(1));
   }

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/CMakeLists.txt

@@ -7,9 +7,13 @@ endif()
 
 find_package(ament_cmake REQUIRED)
 find_package(rclcpp REQUIRED)
+# Rainbow Robotics C++ SDK (apt: rainbow-rb-sdk-dev, pre-installed in the dev
+# container). Dynamically linked — the robot provides the matching librb_sdk.so.
+find_package(rb_sdk REQUIRED)
 
 add_executable(__PLUGIN_SLUG___node src/node.cpp)
 ament_target_dependencies(__PLUGIN_SLUG___node rclcpp)
+target_link_libraries(__PLUGIN_SLUG___node rb_sdk::rb_sdk)
 
 install(TARGETS __PLUGIN_SLUG___node
   DESTINATION lib/${PROJECT_NAME})

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/src/node.cpp

@@ -5,6 +5,8 @@
 // plain rclcpp node is all you need — relative topic names get the namespace
 // prefix applied automatically.
 #include "rclcpp/rclcpp.hpp"
+// Rainbow Robotics C++ SDK (linked as rb_sdk::rb_sdk): RBManipulateSDK etc.
+#include <rainbow/rb_sdk/manipulate/rb_manipulate_sdk.hpp>
 
 class __PLUGIN_CLASS__Node : public rclcpp::Node {
 public:

package/package.json

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