agenticros 0.1.18 → 0.1.19

package/runtime/ros2_ws/src/agenticros_discovery/agenticros_discovery/discovery_node.py

@@ -1,20 +1,37 @@
 """
 AgenticROS Discovery Node
 
-Introspects the running ROS2 system and publishes a capability manifest
-describing available topics, services, and actions. This manifest is consumed
-by the AgenticROS plugin to inform the AI agent about what the robot can do.
-
-Published topic:
-  /agenticros/capabilities  (agenticros_msgs/msg/CapabilityManifest)
+Introspects the running ROS2 system and publishes two manifests:
+
+  1. A capability manifest describing the available topics, services, and
+     actions on the ROS2 graph (consumed by the OpenClaw plugin to inform
+     the AI agent about what the robot can do).
+  2. (Phase 1.e) A robot heartbeat (`RobotInfo`) carrying id, name, kind,
+     capabilities, and sensor flags — published on `<namespace>/agenticros/
+     robot_info` at 1 Hz. This is the live counterpart to the TS-side
+     `config.robots[i]` block: the TS agent can subscribe to a fleet's
+     heartbeats and answer `ros2_find_robots_for(capability=…)` against
+     robots it has never been configured for. See docs/strategy-ai-agents-
+     plus-ros.md §4(d).
+
+Published topics:
+  /agenticros/capabilities                  (agenticros_msgs/msg/CapabilityManifest)
+  <namespace>/agenticros/robot_info         (agenticros_msgs/msg/RobotInfo, Phase 1.e)
 
 Service:
   /agenticros/get_capabilities  (agenticros_msgs/srv/GetCapabilities)
 
 Parameters:
-  robot_name       — Name of the robot (default: "Robot")
-  robot_namespace   — Namespace filter; empty = discover all (default: "")
-  publish_interval  — Seconds between manifest publications (default: 5.0)
+  robot_name        — Display name (default: "Robot")
+  robot_namespace   — ROS2 namespace, also used as the heartbeat id fallback (default: "")
+  robot_id          — Stable id for the robot (Phase 1.e). When empty, falls back to robot_namespace.
+  robot_kind        — Robot kind: amr | arm | drone | rover | … (Phase 1.e, default: "amr")
+  capability_ids    — Per-robot capability allowlist for ros2_find_robots_for. Empty = inherit gateway registry. (Phase 1.e)
+  has_realsense     — Sensor tag, surfaces in RobotInfo + ros2_find_robots_for (Phase 1.e)
+  has_lidar         — Sensor tag (Phase 1.e)
+  has_arm           — Sensor tag (Phase 1.e)
+  publish_interval  — Seconds between CapabilityManifest publications (default: 5.0)
+  heartbeat_interval — Seconds between RobotInfo heartbeats (Phase 1.e, default: 1.0)
 """
 
 from __future__ import annotations
@@ -23,7 +40,7 @@ import rclpy
 from rclpy.node import Node
 from rclpy.qos import QoSProfile, DurabilityPolicy
 
-from agenticros_msgs.msg import CapabilityManifest
+from agenticros_msgs.msg import CapabilityManifest, RobotInfo
 from agenticros_msgs.srv import GetCapabilities
 
 
@@ -35,38 +52,92 @@ _INTERNAL_PREFIXES = (
 )
 
 
+def _normalize_namespace_for_topic(ns: str) -> str:
+    """Return `<ns>/agenticros/robot_info` with exactly one leading slash.
+
+    Empty namespace falls back to a single global topic (no per-robot prefix)
+    so single-robot deployments without an explicit namespace still get a
+    heartbeat at `/agenticros/robot_info`.
+    """
+    cleaned = ns.strip().lstrip("/")
+    if not cleaned:
+        return "/agenticros/robot_info"
+    return f"/{cleaned}/agenticros/robot_info"
+
+
 class DiscoveryNode(Node):
     """Periodically discovers ROS2 capabilities and publishes a manifest."""
 
     def __init__(self) -> None:
         super().__init__("agenticros_discovery")
 
-        # Parameters
+        # Parameters — historical first, then Phase 1.e additions.
         self.declare_parameter("robot_name", "Robot")
         self.declare_parameter("robot_namespace", "")
         self.declare_parameter("publish_interval", 5.0)
 
+        # Phase 1.e identity + fleet-metadata parameters. Declared with
+        # back-compat defaults so existing single-robot launches keep
+        # working without setting anything new.
+        self.declare_parameter("robot_id", "")
+        self.declare_parameter("robot_kind", "amr")
+        self.declare_parameter("capability_ids", [""])
+        self.declare_parameter("has_realsense", False)
+        self.declare_parameter("has_lidar", False)
+        self.declare_parameter("has_arm", False)
+        self.declare_parameter("heartbeat_interval", 1.0)
+
         self.robot_name: str = self.get_parameter("robot_name").value
         self.robot_namespace: str = self.get_parameter("robot_namespace").value
         self.publish_interval: float = self.get_parameter("publish_interval").value
 
+        # rclpy can't declare an empty string-array default — it falls
+        # back to TYPE_NOT_SET unless we seed with [""]. Strip the
+        # placeholder here so the published heartbeat carries an
+        # accurate count.
+        raw_capability_ids = self.get_parameter("capability_ids").value or []
+        self.capability_ids = [c for c in raw_capability_ids if c]
+
+        # robot_id falls back to robot_namespace, matching the TS-side
+        # listRobots() legacy-fallback contract.
+        configured_id: str = self.get_parameter("robot_id").value
+        self.robot_id: str = configured_id.strip() or (self.robot_namespace.strip() or "default")
+        self.robot_kind: str = self.get_parameter("robot_kind").value
+        self.has_realsense: bool = self.get_parameter("has_realsense").value
+        self.has_lidar: bool = self.get_parameter("has_lidar").value
+        self.has_arm: bool = self.get_parameter("has_arm").value
+        self.heartbeat_interval: float = self.get_parameter("heartbeat_interval").value
+
         # Publisher — transient local so late subscribers get the last manifest
         qos = QoSProfile(depth=1, durability=DurabilityPolicy.TRANSIENT_LOCAL)
         self.manifest_pub = self.create_publisher(
             CapabilityManifest, "/agenticros/capabilities", qos
         )
+        # Phase 1.e heartbeat publisher. Transient-local QoS so a TS
+        # adapter that subscribes mid-flight immediately gets the
+        # latest sample without waiting up to `heartbeat_interval` for
+        # the next tick.
+        self.robot_info_topic = _normalize_namespace_for_topic(self.robot_namespace)
+        self.robot_info_pub = self.create_publisher(RobotInfo, self.robot_info_topic, qos)
 
         # Service — on-demand query
         self.get_caps_srv = self.create_service(
             GetCapabilities, "/agenticros/get_capabilities", self._handle_get_capabilities
         )
 
-        # Timer — periodic discovery
+        # Timers — keep manifest + heartbeat on independent cadences.
+        # The manifest is comparatively heavy (whole topic graph) and
+        # changes rarely, so the existing 5 s default stays. The
+        # heartbeat at 1 Hz matches the strategy memo's
+        # "1 Hz with 5 s staleness window" recommendation.
         self.timer = self.create_timer(self.publish_interval, self._on_timer)
+        self.heartbeat_timer = self.create_timer(self.heartbeat_interval, self._on_heartbeat)
 
         self.get_logger().info(
             f"Discovery node started: robot={self.robot_name}, "
-            f"namespace='{self.robot_namespace}', interval={self.publish_interval}s"
+            f"namespace='{self.robot_namespace}', interval={self.publish_interval}s, "
+            f"id={self.robot_id}, kind={self.robot_kind}, "
+            f"heartbeat={self.heartbeat_interval}s on {self.robot_info_topic}"
         )
 
     def _on_timer(self) -> None:
@@ -79,6 +150,30 @@ class DiscoveryNode(Node):
             f"{len(manifest.action_names)} actions"
         )
 
+    def _on_heartbeat(self) -> None:
+        """Publish a `RobotInfo` heartbeat on `<namespace>/agenticros/robot_info`.
+
+        Carries id, name, kind, capability ids, sensor flags, and a
+        timestamp so subscribers can apply a staleness window without
+        relying on transport-level keepalives.
+        """
+        info = self._build_robot_info()
+        self.robot_info_pub.publish(info)
+
+    def _build_robot_info(self) -> RobotInfo:
+        """Materialise the Phase 1.e heartbeat payload from declared params."""
+        msg = RobotInfo()
+        msg.id = self.robot_id
+        msg.name = self.robot_name
+        msg.kind = self.robot_kind
+        msg.robot_namespace = self.robot_namespace
+        msg.capability_ids = list(self.capability_ids)
+        msg.has_realsense = bool(self.has_realsense)
+        msg.has_lidar = bool(self.has_lidar)
+        msg.has_arm = bool(self.has_arm)
+        msg.stamp = self.get_clock().now().to_msg()
+        return msg
+
     def _handle_get_capabilities(
         self,
         request: GetCapabilities.Request,

package/runtime/ros2_ws/src/agenticros_msgs/CMakeLists.txt

@@ -14,6 +14,7 @@ find_package(geometry_msgs REQUIRED)
 
 rosidl_generate_interfaces(${PROJECT_NAME}
   "msg/CapabilityManifest.msg"
+  "msg/RobotInfo.msg"
   "srv/GetCapabilities.srv"
   "srv/FollowMeStart.srv"
   "srv/FollowMeStop.srv"

package/runtime/ros2_ws/src/agenticros_msgs/msg/RobotInfo.msg

@@ -0,0 +1,44 @@
+# Phase 1.e robot heartbeat — published on `<namespace>/agenticros/robot_info`
+# by agenticros_discovery at 1 Hz. Mirrors the TS-side RobotEntry shape so
+# the discovery service can self-advertise without TS-side static config,
+# and so a future Phase 4 ACP/A2A agent-card payload is a strict superset
+# of these fields. See docs/strategy-ai-agents-plus-ros.md §4(d).
+#
+# Required fields are at the top. Optional fields (sensors, battery, pose)
+# are below — Phase 1.e ships id/name/kind/namespace/capabilities/sensors
+# and leaves the others as forward-compatible placeholders so consumers
+# don't have to handle a schema bump for Phase 3 spatial memory.
+
+# Stable, human-readable identifier — the same `id` the TS side uses as
+# `robot_id` in tool calls (`ros2_publish(robot_id, …)`). Falls back to
+# `robot_namespace` when not set.
+string id
+
+# Display name shown to users / the chat agent (e.g. "Kitchen Bot").
+string name
+
+# Robot kind — "amr" | "arm" | "drone" | "rover" | (free-form). Used by
+# `ros2_find_robots_for(kind=…)` to partition heterogeneous fleets.
+string kind
+
+# ROS2 topic namespace prefix (e.g. "robot3946b404…"). Without leading
+# slash — consumers prepend "/" + this when computing topic paths.
+string robot_namespace
+
+# Capability ids the robot advertises (matches the verbs returned by
+# `ros2_list_capabilities`, e.g. "drive_base", "follow_person",
+# "arm_grasp"). When empty, consumers fall back to the gateway-wide
+# global registry — same precedence as the TS-side per-robot allowlist.
+string[] capability_ids
+
+# Sensor / hardware flags. Three slots match the Phase 1.e schema; add
+# new ones additively (default-false at the consumer when absent) so old
+# subscribers don't break.
+bool has_realsense
+bool has_lidar
+bool has_arm
+
+# Heartbeat timestamp — consumers treat the robot as offline when the
+# last observed stamp is older than ~5 s (per the strategy memo's
+# "1 Hz + 5 s staleness window" recommendation).
+builtin_interfaces/Time stamp

package/runtime/scripts/__tests__/refresh-skill-deps.test.mjs

@@ -0,0 +1,222 @@
+/**
+ * Unit tests for the staleness-detection logic in refresh-skill-deps.mjs.
+ *
+ * The pure-function pieces (file listing + diff) are what we actually care
+ * about pinning down — the spawnSync layer is integration-tested by the
+ * `pnpm refresh:skills` smoke run inside `pnpm deploy:plugin`.
+ *
+ * Why these tests matter: today there's only one staleness-detection
+ * algorithm, and if it accidentally treats "target has more files than
+ * source" as stale (it should NOT), or treats unrelated files in the
+ * skill's @agenticros/core as missing (it should NOT), the refresh will
+ * either thrash (always reinstall) or no-op (never reinstall) — both of
+ * which break the contract.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile, mkdir, symlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  listFilesRecursive,
+  findMissingFiles,
+  checkSkillStaleness,
+  discoverSkillPaths,
+} from "../refresh-skill-deps.mjs";
+
+async function writeText(file, text) {
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, text, "utf8");
+}
+
+test("listFilesRecursive: empty dir returns []", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "refresh-test-"));
+  try {
+    const empty = path.join(root, "empty");
+    await mkdir(empty);
+    assert.deepEqual(listFilesRecursive(empty), []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("listFilesRecursive: missing dir returns [] (no throw)", () => {
+  assert.deepEqual(listFilesRecursive("/no/such/dir/ever-${process.pid}"), []);
+});
+
+test("listFilesRecursive: walks subdirs and returns relative, sorted paths", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "refresh-test-"));
+  try {
+    await writeText(path.join(root, "a.js"), "a");
+    await writeText(path.join(root, "sub", "b.js"), "b");
+    await writeText(path.join(root, "sub", "deep", "c.js"), "c");
+    const files = listFilesRecursive(root);
+    assert.deepEqual(files, ["a.js", path.join("sub", "b.js"), path.join("sub", "deep", "c.js")]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("findMissingFiles: returns source files absent from target", () => {
+  const source = ["a.js", "b.js", "c.js"];
+  const target = ["a.js", "c.js"];
+  assert.deepEqual(findMissingFiles(source, target), ["b.js"]);
+});
+
+test("findMissingFiles: target supersets are NOT treated as missing in source", () => {
+  // Skills sometimes contain extra build artifacts; that's not a cascade.
+  const source = ["a.js", "b.js"];
+  const target = ["a.js", "b.js", "extra.js"];
+  assert.deepEqual(findMissingFiles(source, target), []);
+});
+
+test("findMissingFiles: empty source ⇒ no missing files (degenerate)", () => {
+  assert.deepEqual(findMissingFiles([], ["a.js"]), []);
+});
+
+test("findMissingFiles: empty target ⇒ everything in source is missing", () => {
+  assert.deepEqual(findMissingFiles(["a.js", "b.js"], []), ["a.js", "b.js"]);
+});
+
+test("checkSkillStaleness: hasCoreLink=false when skill has no @agenticros/core dep", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "refresh-test-"));
+  try {
+    const skill = path.join(root, "skill-no-core");
+    await mkdir(skill, { recursive: true });
+    const result = checkSkillStaleness(skill, { sourceCoreDist: path.join(root, "core-src") });
+    assert.equal(result.hasCoreLink, false);
+    assert.deepEqual(result.missingFiles, []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("checkSkillStaleness: detects missing files when target lacks new source files", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "refresh-test-"));
+  try {
+    const coreSrc = path.join(root, "core", "dist");
+    await writeText(path.join(coreSrc, "index.js"), "");
+    await writeText(path.join(coreSrc, "capabilities.js"), "");
+    await writeText(path.join(coreSrc, "mission.js"), "");
+
+    // Skill has a stale link — only index.js, missing capabilities.js and mission.js.
+    const skill = path.join(root, "skill");
+    const staleDist = path.join(skill, "node_modules", "@agenticros", "core", "dist");
+    await writeText(path.join(staleDist, "index.js"), "");
+
+    const result = checkSkillStaleness(skill, { sourceCoreDist: coreSrc });
+    assert.equal(result.hasCoreLink, true);
+    assert.deepEqual(result.missingFiles.sort(), ["capabilities.js", "mission.js"]);
+    assert.equal(result.sourceCount, 3);
+    assert.equal(result.targetCount, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("checkSkillStaleness: returns missingFiles=[] when target is current", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "refresh-test-"));
+  try {
+    const coreSrc = path.join(root, "core", "dist");
+    await writeText(path.join(coreSrc, "index.js"), "");
+    await writeText(path.join(coreSrc, "capabilities.js"), "");
+
+    const skill = path.join(root, "skill");
+    const dist = path.join(skill, "node_modules", "@agenticros", "core", "dist");
+    await writeText(path.join(dist, "index.js"), "");
+    await writeText(path.join(dist, "capabilities.js"), "");
+
+    const result = checkSkillStaleness(skill, { sourceCoreDist: coreSrc });
+    assert.equal(result.hasCoreLink, true);
+    assert.deepEqual(result.missingFiles, []);
+    assert.equal(result.sourceCount, 2);
+    assert.equal(result.targetCount, 2);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("checkSkillStaleness: works when the skill's @agenticros/core is a symlink (real pnpm layout)", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "refresh-test-"));
+  try {
+    const coreSrc = path.join(root, "core", "dist");
+    await writeText(path.join(coreSrc, "index.js"), "");
+    await writeText(path.join(coreSrc, "mission.js"), "");
+
+    // Mimic the pnpm virtual store layout.
+    const pnpmStore = path.join(
+      root,
+      "skill",
+      "node_modules",
+      ".pnpm",
+      "@agenticros+core@file+stub",
+      "node_modules",
+      "@agenticros",
+      "core",
+    );
+    await writeText(path.join(pnpmStore, "dist", "index.js"), "");
+    await writeText(path.join(pnpmStore, "dist", "mission.js"), "");
+
+    const linkParent = path.join(root, "skill", "node_modules", "@agenticros");
+    await mkdir(linkParent, { recursive: true });
+    await symlink(pnpmStore, path.join(linkParent, "core"));
+
+    const result = checkSkillStaleness(path.join(root, "skill"), { sourceCoreDist: coreSrc });
+    assert.equal(result.hasCoreLink, true);
+    assert.deepEqual(result.missingFiles, []);
+    assert.equal(result.targetCount, 2);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("discoverSkillPaths: extraSkillPaths are picked up and absolutised", () => {
+  // Inject only the extraSkillPaths and isolate from env / config files by
+  // clearing the relevant env vars for the duration of the call. The
+  // function also reads ~/.openclaw/openclaw.json + ~/.agenticros/config.json
+  // unconditionally; we accept that those may add more entries, and just
+  // assert our injected path is INCLUDED, not that it's the only one.
+  const original = {
+    AGENTICROS_SKILL_PATHS: process.env.AGENTICROS_SKILL_PATHS,
+    OPENCLAW_CONFIG: process.env.OPENCLAW_CONFIG,
+    AGENTICROS_CONFIG_PATH: process.env.AGENTICROS_CONFIG_PATH,
+  };
+  try {
+    delete process.env.AGENTICROS_SKILL_PATHS;
+    // Point OpenClaw + AgenticROS config readers at nonexistent files so
+    // those branches contribute nothing during the test.
+    process.env.OPENCLAW_CONFIG = "/dev/null/nonexistent.json";
+    process.env.AGENTICROS_CONFIG_PATH = "/dev/null/nonexistent.json";
+
+    const paths = discoverSkillPaths({ extraSkillPaths: ["/tmp/my-skill"] });
+    assert.ok(paths.includes("/tmp/my-skill"), `expected /tmp/my-skill in discovered paths; got ${paths.join(", ")}`);
+  } finally {
+    for (const [k, v] of Object.entries(original)) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  }
+});
+
+test("discoverSkillPaths: AGENTICROS_SKILL_PATHS env var splits on ':'", () => {
+  const original = process.env.AGENTICROS_SKILL_PATHS;
+  const originalOpen = process.env.OPENCLAW_CONFIG;
+  const originalAgenticros = process.env.AGENTICROS_CONFIG_PATH;
+  try {
+    process.env.OPENCLAW_CONFIG = "/dev/null/nonexistent.json";
+    process.env.AGENTICROS_CONFIG_PATH = "/dev/null/nonexistent.json";
+    process.env.AGENTICROS_SKILL_PATHS = "/tmp/skill-a:/tmp/skill-b";
+
+    const paths = discoverSkillPaths();
+    assert.ok(paths.includes("/tmp/skill-a"));
+    assert.ok(paths.includes("/tmp/skill-b"));
+  } finally {
+    if (original === undefined) delete process.env.AGENTICROS_SKILL_PATHS;
+    else process.env.AGENTICROS_SKILL_PATHS = original;
+    if (originalOpen === undefined) delete process.env.OPENCLAW_CONFIG;
+    else process.env.OPENCLAW_CONFIG = originalOpen;
+    if (originalAgenticros === undefined) delete process.env.AGENTICROS_CONFIG_PATH;
+    else process.env.AGENTICROS_CONFIG_PATH = originalAgenticros;
+  }
+});