agenticros 0.1.18 → 0.1.19

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

@@ -0,0 +1,128 @@
+/**
+ * Tool: ros2_find_robots_for — Phase 1.e of the AgenticROS strategy.
+ *
+ * Capability-aware fleet filter: given a (capability, kind, online)
+ * query, returns the configured robots that match, ranked best-first.
+ * This is the tool that lets an LLM ask "which robot can find a chair"
+ * or "is there an AMR online that can follow a person" and get a
+ * structured answer it can plan against — without scanning topic lists.
+ *
+ * Config-only by default (no transport touched). When the caller sets
+ * `online: true|false`, we list topics via the global transport and
+ * cross-reference against `<ns>/cmd_vel` patterns to compute the live
+ * set — same heuristic as ros2_discover_robots, sharing
+ * `discoverRobots()` from @agenticros/core. The transport is only
+ * acquired in that branch; offline-mode planning still works.
+ *
+ * Mirrored across all three adapters (Claude Code, OpenClaw, Gemini)
+ * with identical request/response shapes — see
+ * `packages/agenticros-claude-code/src/tools.ts` for the canonical one.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "../plugin-api.js";
+import type { AgenticROSConfig } from "@agenticros/core";
+import { discoverRobots, findRobotsFor } from "@agenticros/core";
+import { getTransport } from "../service.js";
+
+export function registerFindRobotsForTool(
+  api: OpenClawPluginApi,
+  config: AgenticROSConfig,
+): void {
+  api.registerTool({
+    name: "ros2_find_robots_for",
+    label: "ROS2 Find Robots For",
+    description:
+      "Find the robots in the configured fleet that match a capability + kind + online filter, " +
+      "ranked best-first. PREFER this over ros2_list_robots whenever the user names a verb " +
+      "('which robot can find a chair', 'do I have an arm robot that can grasp', 'is there an " +
+      "AMR online that can follow a person'). Capability matches the verbs from " +
+      "ros2_list_capabilities — by default robots inherit the gateway-wide registry; declaring " +
+      "per-robot capabilities in config narrows it. Kind matches robot.kind exactly ('amr' | " +
+      "'arm' | 'drone' | 'rover'). When online=true, only currently-reachable robots are " +
+      "returned (uses the same `<ns>/cmd_vel` heuristic as ros2_discover_robots and requires " +
+      "the transport). The result lists matched robots with id/name/namespace/kind/sensors/" +
+      "online flag, ranked so explicit capability declarations + online robots come first.",
+    parameters: Type.Object({
+      capability: Type.Optional(
+        Type.String({
+          description:
+            "Capability id to match (e.g. 'follow_person', 'find_object', 'drive_base'). " +
+            "Case-sensitive — use ros2_list_capabilities to get the exact list.",
+        }),
+      ),
+      kind: Type.Optional(
+        Type.String({
+          description:
+            "Robot kind filter (case-insensitive exact match). Common values: 'amr', 'arm', " +
+            "'drone', 'rover'.",
+        }),
+      ),
+      online: Type.Optional(
+        Type.Boolean({
+          description:
+            "When true, only return robots currently reachable on the ROS2 graph (requires the " +
+            "transport to be connected). When false, only return robots NOT reachable. When " +
+            "omitted, online status is annotated on every match but doesn't filter the list.",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const p = (params ?? {}) as { capability?: string; kind?: string; online?: boolean };
+      let onlineIds: Set<string> | undefined;
+      if (p.online !== undefined) {
+        const transport = getTransport();
+        if (transport.getStatus() !== "connected") {
+          const fail = {
+            success: false,
+            error:
+              "online filter requires the ROS transport to be connected. Drop the 'online' " +
+              "arg to run config-only, or check that zenohd / rosbridge is up.",
+          };
+          return { content: [{ type: "text", text: JSON.stringify(fail) }], details: fail };
+        }
+        const topics = await transport.listTopics();
+        const disc = discoverRobots(topics, config);
+        onlineIds = new Set(disc.configured_online.map((r) => r.id));
+      }
+      try {
+        const result = findRobotsFor(
+          config,
+          { capability: p.capability, kind: p.kind, online: p.online },
+          onlineIds,
+        );
+        // Flatten the FindRobotsForMatch shape into one object per
+        // robot so the LLM doesn't have to dig through .robot.* —
+        // identical shape to the claude-code adapter's formatter.
+        const payload = {
+          success: true,
+          query: result.query,
+          total: result.total,
+          robots: result.robots.map((m) => ({
+            id: m.robot.id,
+            name: m.robot.name,
+            namespace: m.robot.namespace,
+            kind: m.robot.kind,
+            sensors: m.robot.sensors,
+            capabilities: m.robot.capabilities ?? null,
+            cameraTopic: m.robot.cameraTopic,
+            online: m.online,
+            matched_capability_explicitly: m.matched_capability_explicitly,
+            score: m.score,
+          })),
+        };
+        return {
+          content: [{ type: "text", text: JSON.stringify(payload) }],
+          details: payload,
+        };
+      } catch (e) {
+        const fail = {
+          success: false,
+          error: e instanceof Error ? e.message : String(e),
+        };
+        return { content: [{ type: "text", text: JSON.stringify(fail) }], details: fail };
+      }
+    },
+  });
+}

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

@@ -0,0 +1,311 @@
+/**
+ * Tool: run_mission — Phase 1.c of the AgenticROS strategy.
+ *
+ * Executes a multi-step mission by chaining capabilities. Each step
+ * names a capability (from `ros2_list_capabilities`); the runner maps
+ * the capability to a previously-registered OpenClaw tool, calls that
+ * tool's execute() with the step's resolved inputs, and feeds the
+ * structured output into later steps via `{{stepId.outputs.field}}`
+ * template references.
+ *
+ * The transport-agnostic runner itself lives in @agenticros/core; this
+ * file just provides the OpenClaw-flavoured tool wrapper plus the
+ * capability → tool-name binding map (which mirrors the one in
+ * packages/agenticros-claude-code/src/tools.ts so all adapters agree on
+ * what `drive_base`, `find_object`, etc. actually do).
+ *
+ * Mirrored across all three adapters — see
+ * docs/strategy-ai-agents-plus-ros.md §4 Phase 1.c.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { AgentTool, OpenClawPluginApi } from "../plugin-api.js";
+import type {
+  AgenticROSConfig,
+  CapabilityToolBindings,
+  Mission,
+  MissionToolDispatcher,
+} from "@agenticros/core";
+import {
+  listAllCapabilities,
+  runMission,
+  generateMissionId,
+  createMemoryTranscriptSink,
+  missionTranscriptNamespace,
+  compileGoalToMission,
+} from "@agenticros/core";
+import { resolveRobotForTool } from "./_robot-helpers.js";
+import { getMissionRegistry } from "../mission-registry.js";
+import { getMemory } from "../memory.js";
+
+/**
+ * Snapshot of the registered tools, keyed by tool name. Built in
+ * `tools/index.ts` as each tool is registered, then passed in so this
+ * tool can dispatch sub-tool calls by name.
+ */
+export type ToolRegistry = Map<string, AgentTool>;
+
+const MISSION_BINDINGS: CapabilityToolBindings = {
+  drive_base: {
+    tool: "ros2_publish",
+    buildArgs: (inputs) => {
+      const lx = Number(inputs.linear_x ?? 0) || 0;
+      const az = Number(inputs.angular_z ?? 0) || 0;
+      return {
+        topic: "/cmd_vel",
+        type: "geometry_msgs/msg/Twist",
+        message: {
+          linear: { x: lx, y: 0, z: 0 },
+          angular: { x: 0, y: 0, z: az },
+        },
+      };
+    },
+  },
+  take_snapshot: {
+    tool: "ros2_camera_snapshot",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = {};
+      if (typeof inputs.topic === "string") out.topic = inputs.topic;
+      if (typeof inputs.message_type === "string") out.message_type = inputs.message_type;
+      if (typeof inputs.timeout === "number") out.timeout = inputs.timeout;
+      return out;
+    },
+  },
+  measure_depth: {
+    tool: "ros2_depth_distance",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = {};
+      if (typeof inputs.topic === "string") out.topic = inputs.topic;
+      if (typeof inputs.timeout === "number") out.timeout = inputs.timeout;
+      return out;
+    },
+  },
+  list_topics: {
+    tool: "ros2_list_topics",
+    buildArgs: () => ({}),
+  },
+  publish_topic: {
+    tool: "ros2_publish",
+    buildArgs: (inputs) => ({
+      topic: String(inputs.topic ?? ""),
+      type: String(inputs.type ?? inputs.msg_type ?? ""),
+      message: inputs.message ?? inputs.msg ?? {},
+    }),
+  },
+  subscribe_once: {
+    tool: "ros2_subscribe_once",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = { topic: String(inputs.topic ?? "") };
+      if (typeof inputs.type === "string") out.type = inputs.type;
+      if (typeof inputs.timeout === "number") out.timeout = inputs.timeout;
+      return out;
+    },
+  },
+  follow_person: {
+    tool: "ros2_follow_me_start",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = {};
+      if (typeof inputs.target_distance === "number") out.target_distance = inputs.target_distance;
+      if (typeof inputs.mode === "string") out.mode = inputs.mode;
+      return out;
+    },
+  },
+  find_object: {
+    tool: "ros2_find_object",
+    buildArgs: (inputs) => {
+      const target = String(inputs.target ?? "");
+      const out: Record<string, unknown> = { target };
+      if (typeof inputs.angular_speed === "number") out.angular_speed = inputs.angular_speed;
+      if (typeof inputs.clockwise === "boolean") out.clockwise = inputs.clockwise;
+      if (typeof inputs.timeout_seconds === "number") out.timeout_seconds = inputs.timeout_seconds;
+      if (typeof inputs.min_confidence === "number") out.min_confidence = inputs.min_confidence;
+      return out;
+    },
+  },
+};
+
+export function registerMissionTool(
+  api: OpenClawPluginApi,
+  config: AgenticROSConfig,
+  registry: ToolRegistry,
+): void {
+  api.registerTool({
+    name: "run_mission",
+    label: "ROS2 Run Mission",
+    description:
+      "Execute a multi-step mission by chaining capabilities (the verbs returned by ros2_list_capabilities). " +
+      "PASS EITHER a natural-language `goal` (recommended for simple verbs like 'find a chair', " +
+      "'take a picture', 'follow me', 'find a chair and drive toward it') OR an explicit `mission.steps[]` " +
+      "plan when you need precise control. Steps run sequentially; each step's outputs are available to " +
+      "later steps via {{stepId.outputs.fieldName}} template references. " +
+      "Default on_fail behaviour is 'stop' (abort on first error). Returns a per-step result list, a " +
+      "summary line, a mission_id you can pass to mission_cancel to abort mid-run, and (when a goal was " +
+      "provided) the compiled plan + candidate match list so you can see what the planner did. " +
+      "When memory is enabled, every step is also written to the shared memory under namespace " +
+      "mission:<mission_id> so a second agent can recall the timeline via memory_recall. " +
+      "Today the runner supports: drive_base, take_snapshot, measure_depth, list_topics, " +
+      "publish_topic, subscribe_once, follow_person, find_object. " +
+      "Pass mission.robot_id (or top-level robot_id with goal) to target every step at one robot.",
+    parameters: Type.Object({
+      goal: Type.Optional(
+        Type.String({
+          description:
+            "Natural-language goal — the local planner compiles it into a mission against the capability registry. " +
+            "Examples: 'find a chair', 'find a chair and drive toward it', 'take a picture', 'follow me', " +
+            "'measure depth', 'drive forward at 0.3 m/s', 'turn left', 'stop'. " +
+            "Either goal or mission must be provided; mission wins if both are set.",
+        }),
+      ),
+      robot_id: Type.Optional(
+        Type.String({
+          description:
+            "Optional robot id (from ros2_list_robots) — used when 'goal' is provided to scope every compiled step to one robot.",
+        }),
+      ),
+      mission: Type.Optional(
+        Type.Object({
+          name: Type.Optional(Type.String()),
+          goal: Type.Optional(Type.String()),
+          robot_id: Type.Optional(
+            Type.String({
+              description:
+                "Default robot id (from ros2_list_robots) injected into every step's tool args. Per-step inputs.robot_id overrides this for individual steps.",
+            }),
+          ),
+          steps: Type.Array(
+            Type.Object({
+              id: Type.String(),
+              capability: Type.String(),
+              inputs: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+              on_fail: Type.Optional(Type.Union([Type.Literal("stop"), Type.Literal("continue")])),
+            }),
+          ),
+        }),
+      ),
+    }),
+
+    async execute(toolCallId, params, signal) {
+      const caps = listAllCapabilities(config);
+      const missionRaw = params["mission"];
+      const goalRaw = params["goal"];
+      const topLevelRobotId = typeof params["robot_id"] === "string" ? (params["robot_id"] as string) : undefined;
+
+      // Phase 1.g — accept either an explicit mission OR a
+      // natural-language goal. The planner is deterministic + rule-based,
+      // so an agent can preview the compile via the same call. We surface
+      // candidates/suggestions in details so a failed compile is actionable.
+      let mission: Mission;
+      let plannerInfo:
+        | { compiled_from_goal: string; candidates: unknown[]; unmatched_verbs?: string[] }
+        | undefined;
+      if (missionRaw && typeof missionRaw === "object" && !Array.isArray(missionRaw)) {
+        mission = missionRaw as Mission;
+        if (!Array.isArray(mission.steps)) {
+          const text = "mission.steps must be an array of step objects.";
+          return { content: [{ type: "text", text }], details: { success: false, error: text } };
+        }
+      } else if (typeof goalRaw === "string" && goalRaw.trim().length > 0) {
+        const planned = compileGoalToMission(goalRaw, caps, { robot_id: topLevelRobotId });
+        if (!planned.mission) {
+          const details = {
+            success: false,
+            error: planned.error,
+            goal: goalRaw,
+            suggestions: planned.suggestions,
+            ...(planned.unmatched_verbs ? { unmatched_verbs: planned.unmatched_verbs } : {}),
+          };
+          return { content: [{ type: "text", text: JSON.stringify(details) }], details };
+        }
+        mission = planned.mission;
+        plannerInfo = {
+          compiled_from_goal: goalRaw,
+          candidates: planned.candidates,
+          ...(planned.unmatched_verbs ? { unmatched_verbs: planned.unmatched_verbs } : {}),
+        };
+      } else {
+        const text =
+          'run_mission requires either "mission" (object with steps[]) or "goal" (natural-language string). Pass at least one.';
+        return { content: [{ type: "text", text }], details: { success: false, error: text } };
+      }
+
+      // Validate mission.robot_id up-front so the agent gets a single
+      // clean error (with known ids) instead of one per step.
+      if (typeof mission.robot_id === "string" && mission.robot_id.trim().length > 0) {
+        const resolved = resolveRobotForTool(config, { robot_id: mission.robot_id });
+        if ("error" in resolved) return resolved.error;
+      }
+
+      const dispatcher: MissionToolDispatcher = async (toolName, toolArgs) => {
+        const tool = registry.get(toolName);
+        if (!tool) {
+          return {
+            text: `Tool "${toolName}" is not registered with this OpenClaw plugin instance.`,
+            isError: true,
+          };
+        }
+        const res = await tool.execute(toolCallId, toolArgs, signal);
+        const text = res.content
+          .map((c) => (c.type === "text" ? c.text : `[image: ${c.mimeType}]`))
+          .join("\n");
+        // Tool results don't carry an isError flag in the OpenClaw shape;
+        // surface details if it's an object so the runner can pick it up
+        // as structured outputs.
+        const outputs =
+          res.details && typeof res.details === "object" && !Array.isArray(res.details)
+            ? (res.details as Record<string, unknown>)
+            : undefined;
+        return { text, outputs };
+      };
+
+      // Phase 1.f — generate + register a mission_id, wire transcripts.
+      // mission_cancel uses the registry to find this entry mid-run.
+      // The transcript sink is only attached when memory is enabled
+      // (initMemory() populated getMemory()); otherwise it stays a
+      // no-op so opt-in deployments aren't affected.
+      const missionId = generateMissionId();
+      const missionRegistry = getMissionRegistry();
+      const { entry: regEntry, dispose: disposeRegistry } = missionRegistry.register(
+        missionId,
+        { name: mission.name },
+      );
+      const memory = getMemory();
+      const transcript = memory ? createMemoryTranscriptSink(memory, missionId) : undefined;
+
+      let result;
+      try {
+        result = await runMission(mission, caps, MISSION_BINDINGS, dispatcher, {
+          mission_id: missionId,
+          cancellation: regEntry.cancellation,
+          transcript,
+          adapter: "openclaw",
+        });
+      } finally {
+        disposeRegistry();
+      }
+      const compact = {
+        status: result.status,
+        mission_id: result.mission_id,
+        ...(result.cancellation_reason ? { cancellation_reason: result.cancellation_reason } : {}),
+        ...(transcript ? { transcript_namespace: missionTranscriptNamespace(missionId) } : {}),
+        ...(plannerInfo ? { planner: plannerInfo } : {}),
+        steps_run: result.steps_run,
+        steps_total: result.steps_total,
+        duration_ms: result.duration_ms,
+        summary: result.summary,
+        steps: result.steps.map((s) => ({
+          id: s.id,
+          capability: s.capability,
+          status: s.status,
+          inputs: s.inputs,
+          outputs: s.outputs,
+          ...(s.error ? { error: s.error } : {}),
+          duration_ms: s.duration_ms,
+        })),
+      };
+      return {
+        content: [{ type: "text", text: `${result.summary}\n${JSON.stringify(compact)}` }],
+        details: compact,
+      };
+    },
+  });
+}

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 = {