agenticros 0.1.18 → 0.1.19

package/runtime/packages/agenticros/src/service.ts

@@ -1,6 +1,11 @@
 import type { TransportConfig } from "@agenticros/core";
-import type { RosTransport } from "@agenticros/core";
-import { createTransport, getTransportConfig } from "@agenticros/core";
+import type { RosTransport, ResolvedRobot } from "@agenticros/core";
+import {
+  createTransport,
+  getTransportConfig,
+  getTransportConfigForRobot,
+  hasRobotTransportOverride,
+} from "@agenticros/core";
 import type { OpenClawPluginApi } from "./plugin-api.js";
 import type { PluginLogger } from "./plugin-api.js";
 import type { AgenticROSConfig } from "@agenticros/core";
@@ -238,6 +243,112 @@ async function ensureTransportConnected(
   await next;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 1.d-pool: per-robot transport override pool.
+//
+// The existing `transport` singleton above (with eager-retry / preflight /
+// poll-reconnect) stays the source of truth for every robot WITHOUT a
+// per-robot `transport` override in config. That's the common case and
+// the plugin's hard-won robustness lives in that singleton.
+//
+// For robots that DO declare an override we maintain a smaller, lazier
+// pool here. Override entries don't (yet) get the eager-connect /
+// preflight / polling treatment — they connect on first tool call, fail
+// loudly to the agent on connect timeout, and self-heal on the next
+// acquire. That's intentional: most fleets have one or two override
+// robots and the agent-facing error path is sufficient feedback.
+//
+// Pool key: `robot.id` (validated by `hasRobotTransportOverride`).
+// ─────────────────────────────────────────────────────────────────────────────
+
+const overrideTransports = new Map<string, RosTransport>();
+const overrideInFlight = new Map<string, Promise<RosTransport>>();
+const OVERRIDE_CONNECT_TIMEOUT_MS = 15_000;
+
+/**
+ * Return the right transport for `robot`. Per-robot tools call this
+ * INSTEAD of `getTransport()` so a robot with a custom transport gets
+ * its own connection. Robots without an override fall through to the
+ * service-managed singleton with all its retry / preflight machinery.
+ *
+ * Throws when the singleton is requested but the service hasn't
+ * connected yet — same contract as `getTransport()`.
+ *
+ * Throws (or surfaces as a tool error after the timeout) when an
+ * override entry can't connect — the agent sees a clean failure and
+ * can fall back to a different robot id.
+ */
+export async function getTransportForRobot(
+  config: AgenticROSConfig,
+  robot: ResolvedRobot,
+): Promise<RosTransport> {
+  if (!hasRobotTransportOverride(config, robot.id)) {
+    // Fast path: no override → reuse the service-managed singleton
+    // (with its retries and preflight). Same as the pre-pool behaviour.
+    return getTransport();
+  }
+  return acquireOverrideTransport(config, robot);
+}
+
+async function acquireOverrideTransport(
+  config: AgenticROSConfig,
+  robot: ResolvedRobot,
+): Promise<RosTransport> {
+  const cached = overrideTransports.get(robot.id);
+  if (cached && cached.getStatus() === "connected") return cached;
+
+  // Concurrent first-acquires share one connect promise so two near-
+  // simultaneous tool calls don't double-open the same Zenoh socket.
+  const flight = overrideInFlight.get(robot.id);
+  if (flight) return flight;
+
+  if (cached) {
+    // Stale entry — drop cleanly so a fresh build can proceed.
+    overrideTransports.delete(robot.id);
+    cached.disconnect().catch(() => {});
+  }
+
+  const connectFlight = (async (): Promise<RosTransport> => {
+    const transportCfg = buildTransportConfig(getTransportConfigForRobot(config, robot.id));
+    const t = await createTransport(transportCfg);
+    await connectWithTimeout(t, OVERRIDE_CONNECT_TIMEOUT_MS);
+    overrideTransports.set(robot.id, t);
+    return t;
+  })();
+  overrideInFlight.set(robot.id, connectFlight);
+  try {
+    return await connectFlight;
+  } finally {
+    overrideInFlight.delete(robot.id);
+  }
+}
+
+async function connectWithTimeout(t: RosTransport, timeoutMs: number): Promise<void> {
+  const timeout = new Promise<never>((_, reject) => {
+    setTimeout(
+      () =>
+        reject(
+          new Error(
+            `Per-robot transport connect timed out after ${timeoutMs / 1000}s. ` +
+              "Check the robot's transport override in config (router endpoint, mode).",
+          ),
+        ),
+      timeoutMs,
+    );
+  });
+  await Promise.race([t.connect(), timeout]);
+}
+
+async function drainOverridePool(): Promise<void> {
+  const pending: Promise<unknown>[] = [];
+  for (const t of overrideTransports.values()) {
+    pending.push(t.disconnect().catch(() => {}));
+  }
+  overrideTransports.clear();
+  overrideInFlight.clear();
+  await Promise.all(pending);
+}
+
 const RETRY_INTERVAL_MS = 10000;
 const DISCONNECTED_POLL_MS = 15000;
 
@@ -283,6 +394,13 @@ export function registerService(api: OpenClawPluginApi, config: AgenticROSConfig
         currentMode = null;
         api.logger.info("ROS2 transport disconnected");
       }
+      // Drain any per-robot override connections too — otherwise they'd
+      // leak open Zenoh sockets across plugin reloads.
+      const overrideCount = overrideTransports.size;
+      if (overrideCount > 0) {
+        await drainOverridePool();
+        api.logger.info(`Disconnected ${overrideCount} per-robot override transport(s)`);
+      }
     },
   });
 

package/runtime/packages/agenticros/src/skill-loader.ts

@@ -129,12 +129,20 @@ function findSkillInPath(dirPath: string): { entry: string; packageName: string
   if (!existsSync(dirPath)) return null;
   const pkgPath = join(dirPath, "package.json");
   if (!existsSync(pkgPath)) return null;
-  let pkg: { agenticrosSkill?: boolean; main?: string; name?: string };
+  let pkg: {
+    agenticrosSkill?: boolean | Record<string, unknown>;
+    main?: string;
+    name?: string;
+  };
   try {
     pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
   } catch {
     return null;
   }
+  // Accept either the legacy boolean (`"agenticrosSkill": true`) or the
+  // Phase-1 object form (`"agenticrosSkill": { capabilities: [...] }`).
+  // Anything truthy registers the package as a skill; the capability
+  // schema is read separately by @agenticros/core.
   if (!pkg.agenticrosSkill) return null;
   const main = pkg.main ?? "index.js";
   const entry = join(dirPath, main);

package/runtime/packages/agenticros/src/tools/_robot-helpers.ts

@@ -0,0 +1,68 @@
+/**
+ * Phase 1.d helper — shared by every OpenClaw ROS2 tool that accepts an
+ * optional `robot_id` parameter. Keeping it in one place means the
+ * schema definition and resolution error format stay consistent across
+ * tools and match the claude-code adapter.
+ *
+ * Usage in a tool's parameters:
+ *
+ *     parameters: Type.Object({
+ *       topic: Type.String({ description: "..." }),
+ *       ...ROBOT_ID_SCHEMA,
+ *     })
+ *
+ * Usage in execute():
+ *
+ *     const resolved = resolveRobotForTool(config, params);
+ *     if ("error" in resolved) return resolved.error;
+ *     const ns = resolved.robot.namespace;
+ */
+
+import { Type } from "@sinclair/typebox";
+import { resolveRobotFromArgs, type ResolvedRobot } from "@agenticros/core";
+import type { AgenticROSConfig } from "@agenticros/core";
+
+/**
+ * TypeBox schema fragment — spread into a tool's parameters object to
+ * advertise an optional `robot_id` argument.
+ */
+export const ROBOT_ID_SCHEMA = {
+  robot_id: Type.Optional(
+    Type.String({
+      description:
+        "Optional robot id (from ros2_list_robots) to scope this call. When omitted, the active robot is used.",
+    }),
+  ),
+};
+
+/**
+ * Try to resolve the target robot from the tool's params. On success
+ * returns `{ robot }`. On unknown-id failure returns `{ error }` —
+ * already shaped as an OpenClaw tool response (content + details) so
+ * the caller can `return resolved.error` directly. The error text comes
+ * from `@agenticros/core/resolveRobot` and already lists known ids +
+ * recommends ros2_list_robots, so the agent can self-correct.
+ */
+export function resolveRobotForTool(
+  config: AgenticROSConfig,
+  params: Record<string, unknown>,
+):
+  | { robot: ResolvedRobot }
+  | {
+      error: {
+        content: Array<{ type: "text"; text: string }>;
+        details: { success: false; error: string };
+      };
+    } {
+  try {
+    return { robot: resolveRobotFromArgs(config, params) };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      error: {
+        content: [{ type: "text", text: msg }],
+        details: { success: false, error: msg },
+      },
+    };
+  }
+}

package/runtime/packages/agenticros/src/tools/index.ts

@@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "../plugin-api.js";
+import type { AgentTool, OpenClawPluginApi } from "../plugin-api.js";
 import type { AgenticROSConfig } from "@agenticros/core";
 import { registerPublishTool } from "./ros2-publish.js";
 import { registerSubscribeTool } from "./ros2-subscribe.js";
@@ -8,6 +8,39 @@ import { registerParamTools } from "./ros2-param.js";
 import { registerIntrospectTool } from "./ros2-introspect.js";
 import { registerCameraTool } from "./ros2-camera.js";
 import { registerDepthDistanceTool } from "./ros2-depth-distance.js";
+import { registerCapabilitiesTool } from "./ros2-capabilities.js";
+import { registerRobotsTool } from "./ros2-robots.js";
+import { registerDiscoverRobotsTool } from "./ros2-discover.js";
+import { registerFindRobotsForTool } from "./ros2-find-robots-for.js";
+import { registerMissionTool, type ToolRegistry } from "./ros2-mission.js";
+import { registerMissionCancelTool } from "./mission-cancel.js";
+
+/**
+ * Wrap the OpenClaw API so every registerTool() call is also recorded in
+ * a local tool registry. The mission runner uses the registry to
+ * dispatch sub-tool calls by name (e.g. capability "drive_base" routes
+ * to the registered "ros2_publish" tool's execute()).
+ *
+ * We keep this internal — skills that register their own tools via
+ * `api.registerTool` won't appear in the registry, which is fine for
+ * v1: today the mission runner only supports the eight intrinsic
+ * capability bindings declared in ros2-mission.ts. Phase 1.d will
+ * extend this to capture skill-declared tools as well.
+ */
+function wrapApiWithToolCapture(api: OpenClawPluginApi): {
+  wrappedApi: OpenClawPluginApi;
+  registry: ToolRegistry;
+} {
+  const registry: ToolRegistry = new Map();
+  const wrappedApi: OpenClawPluginApi = {
+    ...api,
+    registerTool: (tool: AgentTool, opts) => {
+      registry.set(tool.name, tool);
+      api.registerTool(tool, opts);
+    },
+  };
+  return { wrappedApi, registry };
+}
 
 /**
  * Register core ROS2 tools with the OpenClaw AI agent.
@@ -15,12 +48,19 @@ import { registerDepthDistanceTool } from "./ros2-depth-distance.js";
  * Memory tools register asynchronously from index.ts after initMemory resolves.
  */
 export function registerTools(api: OpenClawPluginApi, config: AgenticROSConfig): void {
-  registerPublishTool(api, config);
-  registerSubscribeTool(api, config);
-  registerServiceTool(api, config);
-  registerActionTool(api, config);
-  registerParamTools(api, config);
-  registerIntrospectTool(api);
-  registerCameraTool(api, config);
-  registerDepthDistanceTool(api, config);
+  const { wrappedApi, registry } = wrapApiWithToolCapture(api);
+  registerPublishTool(wrappedApi, config);
+  registerSubscribeTool(wrappedApi, config);
+  registerServiceTool(wrappedApi, config);
+  registerActionTool(wrappedApi, config);
+  registerParamTools(wrappedApi, config);
+  registerIntrospectTool(wrappedApi);
+  registerCameraTool(wrappedApi, config);
+  registerDepthDistanceTool(wrappedApi, config);
+  registerCapabilitiesTool(wrappedApi, config);
+  registerRobotsTool(wrappedApi, config);
+  registerDiscoverRobotsTool(wrappedApi, config);
+  registerFindRobotsForTool(wrappedApi, config);
+  registerMissionTool(wrappedApi, config, registry);
+  registerMissionCancelTool(wrappedApi);
 }

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

@@ -0,0 +1,70 @@
+/**
+ * Tool: mission_cancel — Phase 1.f of the AgenticROS strategy.
+ *
+ * Cancel a mission that's currently running in this OpenClaw plugin
+ * process. Pass the `mission_id` returned by `run_mission`. The mission
+ * runner stops at the next step boundary (the in-flight step finishes
+ * naturally — per-tool preemption is out of scope for Phase 1.f),
+ * marks remaining steps as "cancelled", and returns a result with
+ * `status: "cancelled"`.
+ *
+ * Idempotent / safe-by-default:
+ *  - Unknown mission_id → `found: false`, never an error
+ *  - Calling twice on the same id → second call returns
+ *    `already_cancelled: true` and is otherwise a no-op
+ *  - No transport required — this only mutates an in-process
+ *    `MissionRegistry`
+ *
+ * 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 { getMissionRegistry } from "../mission-registry.js";
+
+export function registerMissionCancelTool(api: OpenClawPluginApi): void {
+  api.registerTool({
+    name: "mission_cancel",
+    label: "Cancel Mission",
+    description:
+      "Cancel a mission that's currently running in this OpenClaw plugin process. " +
+      "Pass the mission_id returned by run_mission. The mission runner stops at the next " +
+      "step boundary (the in-flight step finishes naturally), marks remaining steps as " +
+      "'cancelled', and returns. If the mission has already finished (or the id is unknown), " +
+      "this is a no-op that returns found=false. Optional 'reason' is recorded in the " +
+      "cancelled step results for traceability.",
+    parameters: Type.Object({
+      mission_id: Type.String({
+        description: "The mission_id echoed by run_mission. Required.",
+      }),
+      reason: Type.Optional(
+        Type.String({
+          description: "Optional free-text reason — surfaced in the cancelled mission result.",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const missionId = typeof params["mission_id"] === "string" ? (params["mission_id"] as string).trim() : "";
+      if (!missionId) {
+        const text = "mission_cancel requires 'mission_id' (a non-empty string returned by run_mission).";
+        return { content: [{ type: "text", text }], details: { success: false, error: text } };
+      }
+      const reason = typeof params["reason"] === "string" ? (params["reason"] as string) : undefined;
+      const outcome = getMissionRegistry().cancel(missionId, reason);
+      const details = {
+        success: true,
+        mission_id: missionId,
+        found: outcome.found,
+        already_cancelled: outcome.alreadyCancelled,
+        reason: reason ?? null,
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(details) }],
+        details,
+      };
+    },
+  });
+}

package/runtime/packages/agenticros/src/tools/ros2-action.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_action_goal tool with the AI agent.
@@ -14,22 +15,28 @@ export function registerActionTool(api: OpenClawPluginApi, config: AgenticROSCon
     label: "ROS2 Action Goal",
     description:
       "Send a goal to a ROS2 action server and stream feedback. " +
-      "Use this for long-running operations like navigation or arm movements.",
+      "Use this for long-running operations like navigation or arm movements. " +
+      "Pass robot_id (from ros2_list_robots) to target a specific robot.",
     parameters: Type.Object({
       action: Type.String({ description: "The ROS2 action server name (e.g., '/navigate_to_pose')" }),
       actionType: Type.String({ description: "The ROS2 action type (e.g., 'nav2_msgs/action/NavigateToPose')" }),
       goal: Type.Record(Type.String(), Type.Unknown(), {
         description: "The action goal parameters",
       }),
+      ...ROBOT_ID_SCHEMA,
     }),
 
     async execute(_toolCallId, params) {
+      const resolved = resolveRobotForTool(config, params);
+      if ("error" in resolved) return resolved.error;
+      const { robot } = resolved;
+
       const rawAction = params["action"] as string;
-      const action = toNamespacedTopic(config, rawAction);
+      const action = toNamespacedTopic(robot.namespace, rawAction);
       const actionType = params["actionType"] as string;
       const goal = params["goal"] as Record<string, unknown>;
 
-      const transport = getTransport();
+      const transport = await getTransportForRobot(config, robot);
       const actionResult = await transport.sendActionGoal({
         action,
         actionType,

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

@@ -9,11 +9,12 @@ import {
   mimeTypeForSnapshotBase64,
   rosNumericField,
 } from "@agenticros/ros-camera";
-import { getTransport } from "../service.js";
+import { getTransportForRobot } from "../service.js";
 import { normalizePluginToolImageBase64 } from "../plugin-image-base64.js";
 import { trimJpegToLastEoi } from "../image-binary-trim.js";
 import { storeCameraSnapshot } from "../camera-snapshot-cache.js";
 import { describeImageBestEffort } from "../describer.js";
+import { ROBOT_ID_SCHEMA, resolveRobotForTool } from "./_robot-helpers.js";
 
 /** Known camera topic patterns for common setups (e.g. RealSense). */
 export const REALSENSE_CAMERA_TOPICS = {
@@ -64,20 +65,25 @@ export function registerCameraTool(api: OpenClawPluginApi, config: AgenticROSCon
         ),
       ),
       timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds (default: 10000)" })),
+      ...ROBOT_ID_SCHEMA,
     }),
 
     async execute(_toolCallId, params) {
+      const resolved = resolveRobotForTool(config, params);
+      if ("error" in resolved) return resolved.error;
+      const { robot } = resolved;
+
       const defaultTopic =
-        (config.robot?.cameraTopic ?? "").trim() || "/camera/camera/color/image_raw/compressed";
+        (robot.cameraTopic ?? "").trim() || "/camera/camera/color/image_raw/compressed";
       const rawTopic = (params["topic"] as string | undefined) ?? defaultTopic;
-      const topic = resolveCameraSubscribeTopic(config, rawTopic);
+      const topic = resolveCameraSubscribeTopic(robot.namespace, rawTopic);
       const rawMsgType = params["message_type"] as string | undefined;
       const messageType: "CompressedImage" | "Image" =
         rawMsgType === "Image" ? "Image" : "CompressedImage";
       const timeout = (params["timeout"] as number | undefined) ?? 10000;
 
       try {
-        const transport = getTransport();
+        const transport = await getTransportForRobot(config, robot);
         const typeSel = messageType === "Image" ? ROS_MSG_IMAGE : ROS_MSG_COMPRESSED_IMAGE;
 
         const result = await new Promise<{

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

@@ -0,0 +1,63 @@
+/**
+ * Tool: ros2_list_capabilities — Phase 1.b of the AgenticROS strategy.
+ *
+ * Returns the merged list of intrinsic robot verbs + every capability
+ * declared by installed AgenticROS skills, as read by
+ * @agenticros/core. Prefer this over `ros2_list_topics` for high-level
+ * planning: capabilities are agent-meaningful verbs with typed
+ * inputs/outputs, not raw topic names.
+ *
+ * Read-only and transport-free: this tool reads skill manifests from
+ * local config + filesystem, 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.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "../plugin-api.js";
+import type { AgenticROSConfig, Capability } from "@agenticros/core";
+import { listAllCapabilities } from "@agenticros/core";
+import { ROBOT_ID_SCHEMA, resolveRobotForTool } from "./_robot-helpers.js";
+
+export function registerCapabilitiesTool(
+  api: OpenClawPluginApi,
+  config: AgenticROSConfig,
+): void {
+  api.registerTool({
+    name: "ros2_list_capabilities",
+    label: "ROS2 List Capabilities",
+    description:
+      "List the high-level capabilities (named verbs) this robot can perform — built-in verbs like " +
+      "drive_base / take_snapshot / measure_depth plus every capability declared by installed " +
+      "AgenticROS skills (e.g. follow_person, find_object). PREFER this over ros2_list_topics for " +
+      "high-level planning: capabilities are agent-meaningful verbs with typed inputs/outputs, " +
+      "not raw topic names. Returns one structured response listing every capability the robot " +
+      "supports right now. Pass robot_id (from ros2_list_robots) to scope to a specific robot; " +
+      "today every robot exposes the same capabilities, but the API is in place for per-robot " +
+      "capability declarations.",
+    parameters: Type.Object({ ...ROBOT_ID_SCHEMA }),
+
+    async execute(_toolCallId, params) {
+      // robot_id is validated even though the response doesn't depend on
+      // it yet — unknown ids surface as a tool error, matching every
+      // other tool in the suite.
+      const resolved = resolveRobotForTool(config, params);
+      if ("error" in resolved) return resolved.error;
+
+      const caps: Capability[] = listAllCapabilities(config);
+      const intrinsic = caps.filter((c) => c.source?.kind === "builtin").length;
+      const skill = caps.filter((c) => c.source?.kind === "skill").length;
+      const result = {
+        success: true,
+        total: caps.length,
+        intrinsic_count: intrinsic,
+        skill_count: skill,
+        capabilities: caps,
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        details: result,
+      };
+    },
+  });
+}

package/runtime/packages/agenticros/src/tools/ros2-depth-distance.ts

@@ -7,9 +7,10 @@ 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 { getDepthDistance } from "../depth.js";
 import { REALSENSE_CAMERA_TOPICS } from "./ros2-camera.js";
+import { ROBOT_ID_SCHEMA, resolveRobotForTool } from "./_robot-helpers.js";
 
 const DEFAULT_DEPTH_TOPIC = REALSENSE_CAMERA_TOPICS.depth_raw;
 
@@ -20,7 +21,8 @@ export function registerDepthDistanceTool(api: OpenClawPluginApi, config: Agenti
     description:
       "Get distance in meters from the robot's depth camera (e.g. RealSense). " +
       "Samples the center of the depth image and returns distance biased toward nearer pixels (~12th percentile), not median (median often tracks walls when the person only covers part of the patch). " +
-      "Use when the user asks how far they are from the robot, or distance to/from the robot.",
+      "Use when the user asks how far they are from the robot, or distance to/from the robot. " +
+      "Pass robot_id (from ros2_list_robots) to sample a specific robot's depth camera.",
 
     parameters: Type.Object({
       topic: Type.Optional(
@@ -29,15 +31,20 @@ export function registerDepthDistanceTool(api: OpenClawPluginApi, config: Agenti
         }),
       ),
       timeout: Type.Optional(Type.Number({ description: "Timeout in ms (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 | undefined)?.trim() || DEFAULT_DEPTH_TOPIC;
-      const topic = toNamespacedTopic(config, rawTopic);
+      const topic = toNamespacedTopic(robot.namespace, rawTopic);
       const timeout = (params["timeout"] as number | undefined) ?? 5000;
 
       try {
-        const transport = getTransport();
+        const transport = await getTransportForRobot(config, robot);
         const result = await getDepthDistance(transport, topic, timeout);
         const text = result.valid
           ? `Distance at center (~12th percentile, nearer surfaces): **${result.distance_m} m** (median in same patch: ${result.median_m} m; range ${result.min_m}–${result.max_m} m; ${result.sample_count} pixels). Topic: ${result.topic}.`

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

@@ -0,0 +1,65 @@
+/**
+ * Tool: ros2_discover_robots — Phase 1.d "fleet awareness on the wire".
+ *
+ * Scans the ROS2 topic graph via `transport.listTopics()`, infers robot
+ * namespaces from `<ns>/cmd_vel` patterns, and cross-references them
+ * against the gateway's configured robot list. Returns four buckets so
+ * the agent can answer "which robots are online right now?" without
+ * forcing the user to hand-edit config:
+ *
+ *   - detected            — every robot inferred from the topic graph
+ *   - configured_online   — configured AND on the wire
+ *   - configured_offline  — configured but the wire is silent
+ *   - unknown_detected    — on the wire but NOT in config (candidates)
+ *
+ * Read-only — nothing is written to config from this tool. Persistence
+ * is a separate UX decision handled by the CLI / OpenClaw config UI.
+ *
+ * Pure-function detection + classification lives in @agenticros/core
+ * (`discoverRobots()`) so all three adapters share the same semantics.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "../plugin-api.js";
+import type { AgenticROSConfig } from "@agenticros/core";
+import { discoverRobots } from "@agenticros/core";
+import { getTransport } from "../service.js";
+
+export function registerDiscoverRobotsTool(
+  api: OpenClawPluginApi,
+  config: AgenticROSConfig,
+): void {
+  api.registerTool({
+    name: "ros2_discover_robots",
+    label: "ROS2 Discover Robots",
+    description:
+      "Scan the ROS2 topic graph and report which robots are actually on the wire right now, " +
+      "classified against the gateway's configured robot list. Returns: (1) every namespace " +
+      "inferred from `<ns>/cmd_vel` topics, with a topicCount that says how many corroborating " +
+      "topics live under that namespace, (2) configured_online — configured robots currently " +
+      "publishing, (3) configured_offline — configured robots that are silent, (4) " +
+      "unknown_detected — robots on the wire that aren't in config yet (candidates to add via " +
+      "the CLI / config UI). Use this when the user asks 'which robots are online right now', " +
+      "'is my robot connected', or wants to find a robot that isn't in ros2_list_robots. " +
+      "Requires the ROS transport to be connected.",
+    parameters: Type.Object({}),
+
+    async execute(_toolCallId, _params) {
+      const transport = getTransport();
+      const topics = await transport.listTopics();
+      const result = discoverRobots(topics, config);
+      const payload = {
+        success: true,
+        total_topics: result.total_topics,
+        detected: result.detected,
+        configured_online: result.configured_online,
+        configured_offline: result.configured_offline,
+        unknown_detected: result.unknown_detected,
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        details: payload,
+      };
+    },
+  });
+}