agenticros 0.1.18 → 0.2.0

package/runtime/packages/agenticros/src/tools/ros2-param.ts

@@ -2,7 +2,8 @@ import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "../plugin-api.js";
 import type { AgenticROSConfig } from "@agenticros/core";
 import { toNamespacedTopic } from "@agenticros/core";
-import { getTransport } from "../service.js";
+import { getTransportForRobot } from "../service.js";
+import { ROBOT_ID_SCHEMA, resolveRobotForTool } from "./_robot-helpers.js";
 
 /**
  * Register ros2_param_get and ros2_param_set tools with the AI agent.
@@ -13,18 +14,24 @@ export function registerParamTools(api: OpenClawPluginApi, config: AgenticROSCon
     label: "ROS2 Get Parameter",
     description:
       "Get the value of a ROS2 parameter from a node. " +
-      "Use this to check robot configuration values.",
+      "Use this to check robot configuration values. " +
+      "Pass robot_id (from ros2_list_robots) to target a specific robot.",
     parameters: Type.Object({
       node: Type.String({ description: "The fully qualified node name (e.g., '/turtlebot3/controller')" }),
       parameter: Type.String({ description: "The parameter name (e.g., 'max_velocity')" }),
+      ...ROBOT_ID_SCHEMA,
     }),
 
     async execute(_toolCallId, params) {
+      const resolved = resolveRobotForTool(config, params);
+      if ("error" in resolved) return resolved.error;
+      const { robot } = resolved;
+
       const rawNode = params["node"] as string;
-      const node = toNamespacedTopic(config, rawNode);
+      const node = toNamespacedTopic(robot.namespace, rawNode);
       const parameter = params["parameter"] as string;
 
-      const transport = getTransport();
+      const transport = await getTransportForRobot(config, robot);
       const response = await transport.callService({
         service: `${node}/get_parameters`,
         type: "rcl_interfaces/srv/GetParameters",
@@ -49,20 +56,26 @@ export function registerParamTools(api: OpenClawPluginApi, config: AgenticROSCon
     label: "ROS2 Set Parameter",
     description:
       "Set the value of a ROS2 parameter on a node. " +
-      "Use this to change robot configuration at runtime.",
+      "Use this to change robot configuration at runtime. " +
+      "Pass robot_id (from ros2_list_robots) to target a specific robot.",
     parameters: Type.Object({
       node: Type.String({ description: "The fully qualified node name" }),
       parameter: Type.String({ description: "The parameter name" }),
       value: Type.Unknown({ description: "The new parameter value" }),
+      ...ROBOT_ID_SCHEMA,
     }),
 
     async execute(_toolCallId, params) {
+      const resolved = resolveRobotForTool(config, params);
+      if ("error" in resolved) return resolved.error;
+      const { robot } = resolved;
+
       const rawNode = params["node"] as string;
-      const node = toNamespacedTopic(config, rawNode);
+      const node = toNamespacedTopic(robot.namespace, rawNode);
       const parameter = params["parameter"] as string;
       const value = params["value"];
 
-      const transport = getTransport();
+      const transport = await getTransportForRobot(config, robot);
       const response = await transport.callService({
         service: `${node}/set_parameters`,
         type: "rcl_interfaces/srv/SetParameters",

package/runtime/packages/agenticros/src/tools/ros2-publish.ts

@@ -2,7 +2,8 @@ import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "../plugin-api.js";
 import type { AgenticROSConfig } from "@agenticros/core";
 import { toNamespacedTopic, applyCmdVelTwistSignConvention } from "@agenticros/core";
-import { getTransport } from "../service.js";
+import { getTransportForRobot } from "../service.js";
+import { ROBOT_ID_SCHEMA, resolveRobotForTool } from "./_robot-helpers.js";
 
 /**
  * Register the ros2_publish tool with the AI agent.
@@ -14,37 +15,43 @@ export function registerPublishTool(api: OpenClawPluginApi, config: AgenticROSCo
     label: "ROS2 Publish",
     description:
       "Publish a message to a ROS2 topic. Use this to send commands to the robot " +
-      "(e.g., velocity commands to /cmd_vel, navigation goals, etc.).",
+      "(e.g., velocity commands to /cmd_vel, navigation goals, etc.). " +
+      "Pass robot_id (from ros2_list_robots) to target a specific robot; omitted = active robot.",
     parameters: Type.Object({
       topic: Type.String({ description: "The ROS2 topic name (e.g., '/cmd_vel')" }),
       type: Type.String({ description: "The ROS2 message type (e.g., 'geometry_msgs/msg/Twist')" }),
       message: Type.Record(Type.String(), Type.Unknown(), {
         description: "The message payload matching the ROS2 message type schema",
       }),
+      ...ROBOT_ID_SCHEMA,
     }),
 
     async execute(_toolCallId, params) {
+      const resolved = resolveRobotForTool(config, params);
+      if ("error" in resolved) return resolved.error;
+      const { robot } = resolved;
+
       const rawTopic = params["topic"] as string;
-      const topic = toNamespacedTopic(config, rawTopic);
+      const topic = toNamespacedTopic(robot.namespace, rawTopic);
       const type = params["type"] as string;
       let message = params["message"] as Record<string, unknown>;
       message = applyCmdVelTwistSignConvention(topic, type, message);
 
-      const transport = getTransport();
+      const transport = await getTransportForRobot(config, robot);
       transport.publish({ topic, type, msg: message });
 
-      const ns = (config.robot?.namespace ?? "").trim();
+      const ns = (robot.namespace ?? "").trim();
       const namespaceApplied = ns && topic.startsWith(`/${ns}/`);
       let summary = namespaceApplied
-        ? `Published to ${topic} (robot.namespace="${ns}" applied).`
+        ? `Published to ${topic} (robot="${robot.id}", namespace="${ns}" applied).`
         : `Published to ${topic}.`;
       if (!ns && (rawTopic === "/cmd_vel" || rawTopic.trim().replace(/^\/+/, "") === "cmd_vel")) {
         summary += " If the robot did not move, set robot.namespace in plugin config to the robot's cmd_vel prefix (e.g. robot3946b404c33e4aa39a8d16deb1c5c593), then restart the gateway.";
       }
 
-      const result = { success: true, topic, type, summary };
+      const result = { success: true, topic, type, robot_id: robot.id, summary };
       return {
-        content: [{ type: "text", text: summary + "\n" + JSON.stringify({ success: true, topic, type }) }],
+        content: [{ type: "text", text: summary + "\n" + JSON.stringify({ success: true, topic, type, robot_id: robot.id }) }],
         details: result,
       };
     },

package/runtime/packages/agenticros/src/tools/ros2-robots.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool: ros2_list_robots — Phase 1.d of the AgenticROS strategy.
+ *
+ * Returns the list of robots this gateway knows about (id, name, ROS2
+ * namespace, default camera topic) and which one is active. The agent
+ * uses this to discover the fleet and (in a follow-up iteration) target
+ * specific robots via a `robot_id` parameter on other tools.
+ *
+ * Read-only and transport-free: this tool reads the multi-robot section
+ * of the config (with legacy single-robot fallback) so it works even
+ * when the robot is offline. Mirrored across all three adapters
+ * (OpenClaw, Claude Code, Gemini) — see
+ * docs/strategy-ai-agents-plus-ros.md §4 Phase 1.d.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "../plugin-api.js";
+import type { AgenticROSConfig } from "@agenticros/core";
+import { getActiveRobotId, listRobots } from "@agenticros/core";
+
+export function registerRobotsTool(
+  api: OpenClawPluginApi,
+  config: AgenticROSConfig,
+): void {
+  api.registerTool({
+    name: "ros2_list_robots",
+    label: "ROS2 List Robots",
+    description:
+      "List the robots this gateway knows about (id, name, ROS2 namespace, default camera topic) " +
+      "and which one is the active default. Use this FIRST when the user mentions multiple robots, " +
+      "asks 'which robots can you see?', or names a specific robot you haven't heard of. The " +
+      "returned `id` is what later tools (in upcoming iterations) will accept as a `robot_id` " +
+      "parameter — today there's a single active robot, but the field will scope per-tool calls " +
+      "in fleet deployments.",
+    parameters: Type.Object({}),
+
+    async execute(_toolCallId, _params) {
+      const robots = listRobots(config);
+      const active = getActiveRobotId(config);
+      const result = {
+        success: true,
+        total: robots.length,
+        active_robot_id: active,
+        robots,
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        details: result,
+      };
+    },
+  });
+}

package/runtime/packages/agenticros/src/tools/ros2-service.ts

@@ -2,7 +2,8 @@ import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "../plugin-api.js";
 import type { AgenticROSConfig } from "@agenticros/core";
 import { toNamespacedTopic } from "@agenticros/core";
-import { getTransport } from "../service.js";
+import { getTransportForRobot } from "../service.js";
+import { ROBOT_ID_SCHEMA, resolveRobotForTool } from "./_robot-helpers.js";
 
 /**
  * Register the ros2_service_call tool with the AI agent.
@@ -14,22 +15,28 @@ export function registerServiceTool(api: OpenClawPluginApi, config: AgenticROSCo
     label: "ROS2 Service Call",
     description:
       "Call a ROS2 service and return the response. Use this for request/response operations " +
-      "like setting parameters, triggering behaviors, or querying node state.",
+      "like setting parameters, triggering behaviors, or querying node state. " +
+      "Pass robot_id (from ros2_list_robots) to target a specific robot.",
     parameters: Type.Object({
       service: Type.String({ description: "The ROS2 service name (e.g., '/spawn_entity')" }),
       type: Type.Optional(Type.String({ description: "The ROS2 service type (e.g., 'gazebo_msgs/srv/SpawnEntity')" })),
       args: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
         description: "The service request arguments",
       })),
+      ...ROBOT_ID_SCHEMA,
     }),
 
     async execute(_toolCallId, params) {
+      const resolved = resolveRobotForTool(config, params);
+      if ("error" in resolved) return resolved.error;
+      const { robot } = resolved;
+
       const rawService = params["service"] as string;
-      const service = toNamespacedTopic(config, rawService);
+      const service = toNamespacedTopic(robot.namespace, rawService);
       const type = params["type"] as string | undefined;
       const args = params["args"] as Record<string, unknown> | undefined;
 
-      const transport = getTransport();
+      const transport = await getTransportForRobot(config, robot);
       const response = await transport.callService({ service, type, args });
 
       const result = {

package/runtime/packages/agenticros/src/tools/ros2-subscribe.ts

@@ -2,7 +2,8 @@ import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "../plugin-api.js";
 import type { AgenticROSConfig } from "@agenticros/core";
 import { toNamespacedTopic } from "@agenticros/core";
-import { getTransport } from "../service.js";
+import { getTransportForRobot } from "../service.js";
+import { ROBOT_ID_SCHEMA, resolveRobotForTool } from "./_robot-helpers.js";
 
 /**
  * Register the ros2_subscribe_once tool with the AI agent.
@@ -14,16 +15,22 @@ export function registerSubscribeTool(api: OpenClawPluginApi, config: AgenticROS
     label: "ROS2 Subscribe Once",
     description:
       "Subscribe to a ROS2 topic and return the next message. Use this to read sensor data, " +
-      "check robot state, or get the current value of a topic.",
+      "check robot state, or get the current value of a topic. " +
+      "Pass robot_id (from ros2_list_robots) to target a specific robot.",
     parameters: Type.Object({
       topic: Type.String({ description: "The ROS2 topic name (e.g., '/battery_state')" }),
       type: Type.Optional(Type.String({ description: "The ROS2 message type (e.g., 'sensor_msgs/msg/BatteryState')" })),
       timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds (default: 5000)" })),
+      ...ROBOT_ID_SCHEMA,
     }),
 
     async execute(_toolCallId, params) {
+      const resolved = resolveRobotForTool(config, params);
+      if ("error" in resolved) return resolved.error;
+      const { robot } = resolved;
+
       const rawTopic = params["topic"] as string;
-      const topic = toNamespacedTopic(config, rawTopic);
+      const topic = toNamespacedTopic(robot.namespace, rawTopic);
       let msgType = params["type"] as string | undefined;
       const timeout = (params["timeout"] as number | undefined) ?? 5000;
 
@@ -31,7 +38,7 @@ export function registerSubscribeTool(api: OpenClawPluginApi, config: AgenticROS
         msgType = rawTopic.includes("compressed") ? "sensor_msgs/msg/CompressedImage" : "sensor_msgs/msg/Image";
       }
 
-      const transport = getTransport();
+      const transport = await getTransportForRobot(config, robot);
 
       const result = await new Promise<Record<string, unknown>>((resolve, reject) => {
         const subscription = transport.subscribe(

package/runtime/packages/agenticros-claude-code/README.md

@@ -1,6 +1,6 @@
 # AgenticROS Claude Code adapter
 
-MCP (Model Context Protocol) server that exposes AgenticROS ROS2 tools to **Claude Code CLI** and to the **Claude desktop app** on macOS (including **Claude Dispatch** on iPhone when paired to Claude on your Mac). Use natural language to control and query your ROS2 robot (e.g. "what do you see?", "move 1m forward").
+MCP (Model Context Protocol) server that exposes AgenticROS ROS2 tools to **Claude Code CLI** and to the **Claude desktop app** on macOS (including **Claude Dispatch** on iPhone when paired to Claude on your Mac). Use natural language to control and query your ROS2 robot (e.g. *"what do you see?"*, *"find a chair and drive toward it"*, *"list every robot that can follow a person"*).
 
 This adapter does **not** provide the config or teleop web UI; use the [OpenClaw plugin](../../packages/agenticros) for that, or run the gateway for the browser-based teleop page.
 
@@ -94,6 +94,38 @@ claude
 
 Scope options: `--scope user` (default), `--scope project` (shared via `.mcp.json`).
 
+## Codex CLI (OpenAI)
+
+The same MCP server works unmodified with the **OpenAI Codex CLI** — Codex is a vanilla MCP client, and our server speaks the standard `2024-11-05` MCP protocol that every MCP-compatible client uses. Two ways to register it:
+
+**Option A — `codex mcp add` (recommended)**
+
+```bash
+cd /path/to/agenticros
+codex mcp add agenticros \
+  -- node "$(pwd)/packages/agenticros-claude-code/dist/index.js"
+```
+
+**Option B — direct edit of `~/.codex/config.toml`**
+
+```toml
+[mcp_servers.agenticros]
+command = "node"
+args = ["/ABSOLUTE/PATH/TO/agenticros/packages/agenticros-claude-code/dist/index.js"]
+enabled = true
+startup_timeout_sec = 30
+
+[mcp_servers.agenticros.env]
+AGENTICROS_ROBOT_NAMESPACE = "robotYOUR_NAMESPACE_NO_DASHES"
+```
+
+Then start a Codex session and run `/mcp` to verify — you should see `agenticros` connected with **15 tools** (more if you have skills like `agenticros-skill-followme` or `agenticros-skill-find` registered). Same tools, same tool names, same JSON shapes as in Claude Code; everything in the **Tools** section below applies identically.
+
+Two Codex-specific notes:
+
+- **Absolute path required.** Codex's working directory at server-spawn time is not the AgenticROS repo root, so `args = ["packages/agenticros-claude-code/dist/index.js"]` will fail. Use the full absolute path.
+- **Project-scoped config.** Codex also supports a `.codex/config.toml` in a project directory (and a `mcp.json` in cwd on recent builds) — handy for per-repo MCP setups when you don't want `agenticros` enabled globally. See OpenAI's [Codex config reference](https://developers.openai.com/codex/config-reference) for the precedence rules.
+
 ## Claude desktop app + Claude Dispatch (iOS)
 
 The Claude **desktop** app uses a different MCP config file than Claude Code:
@@ -134,18 +166,29 @@ The server exposes the same ROS2 tools as the OpenClaw plugin:
 
 | Tool | Description |
 |------|-------------|
+| **Inspection** | |
 | `ros2_list_topics` | List topics and types |
-| `ros2_publish` | Publish to a topic (e.g. cmd_vel) |
+| `ros2_list_capabilities` | Typed verb manifest (built-in + skill-declared) — the planning surface for agents |
+| **Fleet** | |
+| `ros2_list_robots` | List configured robots — id, name, kind, capabilities, online status |
+| `ros2_discover_robots` | Online discovery: detect `/<ns>/cmd_vel` namespaces + classify reachability |
+| `ros2_find_robots_for` | Ranked filter by capability + kind + online — *"who can `follow_person` right now?"* |
+| **Missions** | |
+| `run_mission` | Execute a multi-step mission **or** compile a natural-language `goal` into one. Chains capabilities via `{{stepId.outputs.field}}` template refs; returns a `mission_id` |
+| `mission_cancel` | Cancel an in-flight mission by `mission_id` at the next step boundary (idempotent, safe on unknown ids) |
+| **Direct ROS** | |
+| `ros2_publish` | Publish to a topic (e.g. cmd_vel) — safety-clamped |
 | `ros2_subscribe_once` | Get next message from a topic |
 | `ros2_service_call` | Call a ROS2 service |
 | `ros2_action_goal` | Send goal to an action server |
 | `ros2_param_get` / `ros2_param_set` | Get/set node parameters |
-| `ros2_camera_snapshot` | "What do you see" — one frame from camera topic |
+| `ros2_camera_snapshot` | *"What do you see"* — one frame from camera topic |
 | `ros2_depth_distance` | Distance in meters from depth camera |
-| `memory_remember` *(when enabled)* | Store a durable fact for the robot — shared with OpenClaw, Claude Desktop, Gemini |
-| `memory_recall` *(when enabled)* | Semantic search across long-term memory |
-| `memory_forget` *(when enabled)* | Delete by id, query, or whole namespace |
-| `memory_status` *(when enabled)* | Health check + record count + embedder info |
+| **Memory** *(only when enabled)* | |
+| `memory_remember` | Store a durable fact for the robot — shared with OpenClaw, Claude Desktop, Gemini |
+| `memory_recall` | Semantic search across long-term memory (also reads `mission:<id>` step transcripts) |
+| `memory_forget` | Delete by id, query, or whole namespace |
+| `memory_status` | Health check + record count + embedder info |
 
 Safety limits (max linear/angular velocity) from config are applied before `ros2_publish`.
 
@@ -255,6 +298,6 @@ If `ros2_publish` runs but the robot doesn’t move:
 
    In the chat you can type `/mcp` to see MCP server status. If the transport isn’t running (e.g. no Zenoh router), tool calls will fail with connection errors until the ROS2 side is up.
 
-## "Follow me" and skills
+## Skills
 
-The OpenClaw plugin can load skills (e.g. **follow me** via `agenticros-skill-followme`). This MCP adapter does not load skills in v1; only the core tools above are available. For "follow me", use the OpenClaw plugin or a future version of this adapter that adds skill loading or a dedicated `follow_robot` tool.
+Skill packages (e.g. `agenticros-skill-followme`, `agenticros-skill-find`) extend the capability registry with new verbs like `follow_person` and `find_object`. The MCP server reads each skill's `package.json` `agenticros` block (`id`, `capabilities[]`) at startup and surfaces those verbs through `ros2_list_capabilities` and `run_mission` — no per-skill MCP tool needed. To register a skill for this adapter, install it with `agenticros skills install <slug>` from the marketplace, or add its path under `skillPaths[]` in `~/.agenticros/config.json` (or use the `agenticros skills add <path>` CLI). See [docs/skills.md](../../docs/skills.md) for the full skill contract.

package/runtime/packages/agenticros-claude-code/dist/__tests__/capabilities-mcp.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=capabilities-mcp.test.d.ts.map

package/runtime/packages/agenticros-claude-code/dist/__tests__/capabilities-mcp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-mcp.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/capabilities-mcp.test.ts"],"names":[],"mappings":""}