agenticros 0.1.18 → 0.2.0

package/runtime/packages/core/src/__tests__/capabilities.test.ts

@@ -0,0 +1,266 @@
+/**
+ * Unit tests for the Phase 1 capability registry.
+ *
+ * The four broken-link failure cascade we hit on 2026-06-10 is exactly the
+ * regression class these tests are here to prevent:
+ *   1. Stale @agenticros/core caches in skill repos hiding new exports.
+ *   2. `sync-skill-tools.mjs` overwriting `contracts.tools` with a stale list.
+ *   3. OpenClaw `tools.alsoAllow` filtering out unallowlisted plugin tools.
+ *   4. The plugin-deploy `dist/` falling behind the workspace.
+ *
+ * The most upstream of those is "the reader produces what we promised";
+ * everything else depends on that contract holding. So this file pins down:
+ *   - BUILTIN_CAPABILITIES has the 6 intrinsic verbs we ship.
+ *   - readSkillCapabilities() picks up the `agenticros` block from package.json.
+ *   - It uses `agenticros.id` (not the package name) as the skill id.
+ *   - It tags every capability with a source so dispatchers can filter.
+ *   - It deduplicates within a skill so a malformed manifest can't blow up.
+ *   - listAllCapabilities() merges intrinsic + skill in that order.
+ *   - It tolerates non-skill packages (no `agenticros` key) silently.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { parseConfig } from "../config.js";
+import {
+  BUILTIN_CAPABILITIES,
+  readSkillCapabilities,
+  listAllCapabilities,
+  type Capability,
+} from "../capabilities.js";
+
+async function writeJson(filePath: string, data: unknown): Promise<void> {
+  await writeFile(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+async function makeSkillDir(
+  root: string,
+  name: string,
+  pkg: Record<string, unknown>,
+): Promise<string> {
+  const dir = path.join(root, name);
+  await mkdir(dir, { recursive: true });
+  await writeJson(path.join(dir, "package.json"), pkg);
+  return dir;
+}
+
+test("BUILTIN_CAPABILITIES exposes the six intrinsic robot verbs", () => {
+  const ids = BUILTIN_CAPABILITIES.map((c) => c.id).sort();
+  assert.deepEqual(ids, [
+    "drive_base",
+    "list_topics",
+    "measure_depth",
+    "publish_topic",
+    "subscribe_once",
+    "take_snapshot",
+  ]);
+  for (const c of BUILTIN_CAPABILITIES) {
+    assert.equal(c.source?.kind, "builtin", `${c.id} should be tagged builtin`);
+    assert.ok(c.verb.length > 0, `${c.id} should have a verb`);
+    assert.ok(c.description.length > 0, `${c.id} should have a description`);
+  }
+});
+
+test("readSkillCapabilities: reads capabilities from the `agenticros` block", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "agenticros-caps-"));
+  try {
+    const skillDir = await makeSkillDir(root, "skill-alpha", {
+      name: "agenticros-skill-alpha",
+      version: "0.0.1",
+      main: "dist/index.js",
+      agenticros: {
+        id: "alpha",
+        displayName: "Alpha",
+        capabilities: [
+          {
+            id: "wave_hello",
+            verb: "greet",
+            description: "Wave the arm.",
+            inputs: { duration_s: { type: "number", optional: true } },
+            interruptible: true,
+          },
+          {
+            id: "patrol_room",
+            verb: "patrol",
+            description: "Patrol until stopped.",
+            blocks_base: true,
+          },
+        ],
+      },
+    });
+    const config = parseConfig({ skillPaths: [skillDir] });
+    const caps = readSkillCapabilities(config);
+
+    assert.equal(caps.length, 2);
+
+    const wave = caps.find((c) => c.id === "wave_hello") as Capability;
+    assert.ok(wave, "wave_hello should be present");
+    assert.equal(wave.verb, "greet");
+    assert.equal(wave.interruptible, true);
+    assert.equal(wave.source?.kind, "skill");
+    if (wave.source?.kind === "skill") {
+      assert.equal(wave.source.skillId, "alpha");
+      assert.equal(wave.source.package, "agenticros-skill-alpha");
+    }
+    assert.equal(wave.implementation?.kind, "in_process", "default implementation should be in_process");
+
+    const patrol = caps.find((c) => c.id === "patrol_room") as Capability;
+    assert.equal(patrol.blocks_base, true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("readSkillCapabilities: uses agenticros.id (not the package name) for the skill id", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "agenticros-caps-"));
+  try {
+    const skillDir = await makeSkillDir(root, "weird-named-repo", {
+      name: "@some-org/totally-different-name",
+      version: "0.0.1",
+      agenticros: {
+        id: "explicit-id",
+        capabilities: [{ id: "do_thing", verb: "do", description: "Do." }],
+      },
+    });
+    const caps = readSkillCapabilities(parseConfig({ skillPaths: [skillDir] }));
+    assert.equal(caps.length, 1);
+    assert.equal(caps[0].source?.kind, "skill");
+    if (caps[0].source?.kind === "skill") {
+      assert.equal(caps[0].source.skillId, "explicit-id");
+      assert.equal(caps[0].source.package, "@some-org/totally-different-name");
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("readSkillCapabilities: silently ignores non-skill packages", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "agenticros-caps-"));
+  try {
+    const dir = await makeSkillDir(root, "not-a-skill", {
+      name: "regular-package",
+      version: "0.0.1",
+    });
+    const caps = readSkillCapabilities(parseConfig({ skillPaths: [dir] }));
+    assert.equal(caps.length, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("readSkillCapabilities: dedupes within a skill when an id appears twice in the array", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "agenticros-caps-"));
+  try {
+    const skillDir = await makeSkillDir(root, "skill-dupe", {
+      name: "agenticros-skill-dupe",
+      version: "0.0.1",
+      agenticros: {
+        id: "dupe",
+        capabilities: [
+          { id: "shared_id", verb: "first", description: "First." },
+          { id: "shared_id", verb: "second", description: "Duplicate (ignored)." },
+          { id: "extra", verb: "demo", description: "Unique." },
+        ],
+      },
+    });
+    const caps = readSkillCapabilities(parseConfig({ skillPaths: [skillDir] }));
+    const ids = caps.map((c) => c.id).sort();
+    assert.deepEqual(ids, ["extra", "shared_id"]);
+    const shared = caps.find((c) => c.id === "shared_id");
+    assert.equal(shared?.verb, "first", "first entry should win on duplicate id");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("readSkillCapabilities: drops entries without a valid id", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "agenticros-caps-"));
+  try {
+    const skillDir = await makeSkillDir(root, "skill-bad", {
+      name: "agenticros-skill-bad",
+      version: "0.0.1",
+      agenticros: {
+        id: "bad",
+        capabilities: [
+          { verb: "noid", description: "Missing id." },
+          { id: "", verb: "empty", description: "Empty id." },
+          { id: "ok", verb: "good", description: "Valid." },
+          "not_an_object",
+          null,
+        ],
+      },
+    });
+    const caps = readSkillCapabilities(parseConfig({ skillPaths: [skillDir] }));
+    assert.equal(caps.length, 1);
+    assert.equal(caps[0].id, "ok");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("readSkillCapabilities: skips packages with an `agenticros` block that lacks an `id`", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "agenticros-caps-"));
+  try {
+    const skillDir = await makeSkillDir(root, "skill-noid", {
+      name: "agenticros-skill-noid",
+      version: "0.0.1",
+      agenticros: {
+        capabilities: [{ id: "do_thing", verb: "do", description: "Do." }],
+      },
+    });
+    const caps = readSkillCapabilities(parseConfig({ skillPaths: [skillDir] }));
+    assert.equal(caps.length, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("listAllCapabilities: built-ins first, then skill caps; counts add up", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "agenticros-caps-"));
+  try {
+    const skillDir = await makeSkillDir(root, "skill-extra", {
+      name: "agenticros-skill-extra",
+      version: "0.0.1",
+      agenticros: {
+        id: "extra",
+        capabilities: [
+          { id: "extra_one", verb: "demo", description: "One." },
+          { id: "extra_two", verb: "demo", description: "Two." },
+        ],
+      },
+    });
+    const config = parseConfig({ skillPaths: [skillDir] });
+    const caps = listAllCapabilities(config);
+
+    assert.equal(caps.length, BUILTIN_CAPABILITIES.length + 2);
+    // Built-ins are first.
+    for (let i = 0; i < BUILTIN_CAPABILITIES.length; i++) {
+      assert.equal(caps[i].id, BUILTIN_CAPABILITIES[i].id);
+      assert.equal(caps[i].source?.kind, "builtin");
+    }
+    // Skill caps follow.
+    const skillSlice = caps.slice(BUILTIN_CAPABILITIES.length);
+    assert.deepEqual(
+      skillSlice.map((c) => c.id).sort(),
+      ["extra_one", "extra_two"],
+    );
+    for (const c of skillSlice) assert.equal(c.source?.kind, "skill");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("listAllCapabilities: empty config returns only built-ins (no crash)", () => {
+  const caps = listAllCapabilities(parseConfig({}));
+  assert.equal(caps.length, BUILTIN_CAPABILITIES.length);
+  assert.ok(caps.every((c) => c.source?.kind === "builtin"));
+});
+
+test("readSkillCapabilities: missing skillPath does not throw", () => {
+  const config = parseConfig({ skillPaths: ["/nonexistent/path/to/nowhere"] });
+  const caps = readSkillCapabilities(config);
+  assert.deepEqual(caps, []);
+});

package/runtime/packages/core/src/__tests__/discovery.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Unit tests for the Phase 1.d multi-robot discovery module.
+ *
+ * What these tests pin down (each one corresponds to a real failure mode
+ * the discovery layer has to defend against in production):
+ *
+ *   - Topic detection picks up `/<ns>/cmd_vel` for every namespace and
+ *     also the unnamespaced `/cmd_vel` (sim default).
+ *   - topicCount aggregates corroborating topics under each namespace —
+ *     this is what consumers use to rank a "live" namespace over a stale
+ *     one with only cmd_vel left over.
+ *   - UUID→robot-no-dashes rewrite: a config entry with a UUID-style
+ *     namespace ("3946b404-...") MUST match a topic
+ *     "/robot3946b404.../cmd_vel" on the wire. This is the rewrite the
+ *     publish path applies, so discovery has to mirror it or
+ *     configured_online will always be empty for UUID deployments.
+ *   - configured_online / configured_offline / unknown_detected
+ *     partition correctly — every configured robot lands in exactly
+ *     one bucket; every detected namespace that doesn't match any
+ *     config lands in unknown_detected.
+ *   - Empty inputs: no topics + legacy config = legacy robot is
+ *     configured_offline (it's configured but the wire is silent).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { parseConfig } from "../config.js";
+import {
+  detectRobotsFromTopics,
+  discoverRobots,
+  effectiveCmdVelNamespace,
+} from "../discovery.js";
+import type { TopicInfo } from "../transport/types.js";
+
+const T = (name: string, type = "geometry_msgs/msg/Twist"): TopicInfo => ({ name, type });
+
+test("discovery: detectRobotsFromTopics finds /<ns>/cmd_vel and the unnamespaced /cmd_vel", () => {
+  const topics: TopicInfo[] = [
+    T("/robotA/cmd_vel"),
+    T("/robotB/cmd_vel"),
+    T("/cmd_vel"),
+    T("/rosout", "rcl_interfaces/msg/Log"),
+  ];
+  const detected = detectRobotsFromTopics(topics);
+  const ids = detected.map((d) => d.id).sort();
+  assert.deepEqual(ids, ["", "robotA", "robotB"]);
+});
+
+test("discovery: detectRobotsFromTopics accumulates topicCount under each namespace", () => {
+  const topics: TopicInfo[] = [
+    T("/robotA/cmd_vel"),
+    T("/robotA/odom", "nav_msgs/msg/Odometry"),
+    T("/robotA/joint_states", "sensor_msgs/msg/JointState"),
+    T("/robotA/camera/color/image_raw", "sensor_msgs/msg/Image"),
+    T("/robotB/cmd_vel"),
+    T("/robotB/odom", "nav_msgs/msg/Odometry"),
+  ];
+  const detected = detectRobotsFromTopics(topics);
+  const A = detected.find((d) => d.id === "robotA")!;
+  const B = detected.find((d) => d.id === "robotB")!;
+  assert.equal(A.topicCount, 4, "robotA has 4 topics under /robotA/");
+  assert.equal(B.topicCount, 2, "robotB has 2 topics under /robotB/");
+});
+
+test("discovery: detectRobotsFromTopics yields empty list for topic graph with no cmd_vel", () => {
+  const topics: TopicInfo[] = [
+    T("/rosout", "rcl_interfaces/msg/Log"),
+    T("/tf", "tf2_msgs/msg/TFMessage"),
+  ];
+  assert.deepEqual(detectRobotsFromTopics(topics), []);
+});
+
+test("discovery: effectiveCmdVelNamespace mirrors the publish-path UUID rewrite", () => {
+  assert.equal(
+    effectiveCmdVelNamespace("3946b404-c33e-4aa3-9a8d-16deb1c5c593"),
+    "robot3946b404c33e4aa39a8d16deb1c5c593",
+    "UUID-shaped namespace must collapse to robot<no-dashes>",
+  );
+  assert.equal(
+    effectiveCmdVelNamespace("robot_alpha"),
+    "robot_alpha",
+    "already-robot-prefixed namespace stays unchanged",
+  );
+  assert.equal(
+    effectiveCmdVelNamespace(""),
+    "",
+    "empty namespace stays empty (default ns)",
+  );
+  assert.equal(
+    effectiveCmdVelNamespace("Robot7"),
+    "Robot7",
+    "case-insensitive 'robot' prefix is preserved as-is",
+  );
+});
+
+test("discovery: discoverRobots classifies a UUID-style configured robot as online via the topic rewrite", () => {
+  // The robot's config namespace is the UUID, but on the wire it
+  // publishes to /robot<no-dashes>/cmd_vel. Without the rewrite, this
+  // would be misclassified as offline.
+  const cfg = parseConfig({
+    robot: { namespace: "3946b404-c33e-4aa3-9a8d-16deb1c5c593" },
+  });
+  const topics: TopicInfo[] = [
+    T("/robot3946b404c33e4aa39a8d16deb1c5c593/cmd_vel"),
+    T("/robot3946b404c33e4aa39a8d16deb1c5c593/odom", "nav_msgs/msg/Odometry"),
+  ];
+  const result = discoverRobots(topics, cfg);
+  assert.equal(result.configured_online.length, 1, "UUID robot must be classified as online");
+  assert.equal(result.configured_online[0]!.id, "3946b404-c33e-4aa3-9a8d-16deb1c5c593");
+  assert.equal(result.configured_offline.length, 0);
+  assert.equal(result.unknown_detected.length, 0);
+  assert.equal(result.detected[0]!.configuredRobotId, "3946b404-c33e-4aa3-9a8d-16deb1c5c593");
+});
+
+test("discovery: discoverRobots reports configured robots as offline when nothing's on the wire", () => {
+  const cfg = parseConfig({
+    robot: { namespace: "robot-alpha" },
+  });
+  const result = discoverRobots([], cfg);
+  assert.equal(result.detected.length, 0);
+  assert.equal(result.configured_online.length, 0);
+  assert.equal(result.configured_offline.length, 1, "single configured robot must be offline");
+  assert.equal(result.configured_offline[0]!.id, "robot-alpha");
+  assert.equal(result.unknown_detected.length, 0);
+});
+
+test("discovery: discoverRobots surfaces an unknown_detected entry for an on-wire robot not in config", () => {
+  const cfg = parseConfig({
+    robot: { namespace: "robot-alpha" },
+  });
+  const topics: TopicInfo[] = [
+    T("/robot-alpha/cmd_vel"),
+    T("/robot-beta/cmd_vel"), // not in config — must show up as unknown
+    T("/robot-beta/odom", "nav_msgs/msg/Odometry"),
+  ];
+  const result = discoverRobots(topics, cfg);
+  assert.equal(result.configured_online.length, 1);
+  assert.equal(result.configured_online[0]!.id, "robot-alpha");
+  assert.equal(result.unknown_detected.length, 1);
+  assert.equal(result.unknown_detected[0]!.id, "robot-beta");
+  assert.equal(
+    result.unknown_detected[0]!.topicCount,
+    2,
+    "topicCount includes cmd_vel itself plus every corroborating topic under /<id>/",
+  );
+  assert.equal(result.unknown_detected[0]!.configuredRobotId, null);
+});
+
+test("discovery: discoverRobots partitions correctly with mixed online + offline + unknown", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", namespace: "robot-alpha", default: true },
+      { id: "beta", namespace: "robot-beta" },
+      { id: "gamma", namespace: "robot-gamma" }, // offline
+    ],
+  });
+  const topics: TopicInfo[] = [
+    T("/robot-alpha/cmd_vel"),
+    T("/robot-beta/cmd_vel"),
+    T("/robot-delta/cmd_vel"), // unknown
+  ];
+  const result = discoverRobots(topics, cfg);
+  assert.equal(result.detected.length, 3, "three /cmd_vel topics → three detections");
+  assert.deepEqual(
+    result.configured_online.map((r) => r.id).sort(),
+    ["alpha", "beta"],
+  );
+  assert.deepEqual(
+    result.configured_offline.map((r) => r.id),
+    ["gamma"],
+    "gamma is configured but not on the wire",
+  );
+  assert.deepEqual(
+    result.unknown_detected.map((d) => d.id),
+    ["robot-delta"],
+  );
+  assert.equal(
+    result.detected.find((d) => d.id === "robot-alpha")!.configuredRobotId,
+    "alpha",
+    "alpha's detected entry is annotated with its config id",
+  );
+  assert.equal(
+    result.detected.find((d) => d.id === "robot-delta")!.configuredRobotId,
+    null,
+    "delta has no config match — configuredRobotId stays null",
+  );
+});
+
+test("discovery: discoverRobots echoes total_topics for diagnostics", () => {
+  const topics: TopicInfo[] = [
+    T("/robot-alpha/cmd_vel"),
+    T("/rosout", "rcl_interfaces/msg/Log"),
+    T("/tf", "tf2_msgs/msg/TFMessage"),
+  ];
+  const cfg = parseConfig({ robot: { namespace: "robot-alpha" } });
+  const result = discoverRobots(topics, cfg);
+  assert.equal(result.total_topics, 3);
+});
+
+test("discovery: the unnamespaced /cmd_vel (sim default) detects as id=''", () => {
+  const topics: TopicInfo[] = [T("/cmd_vel"), T("/odom", "nav_msgs/msg/Odometry")];
+  const detected = detectRobotsFromTopics(topics);
+  assert.equal(detected.length, 1);
+  assert.equal(detected[0]!.id, "", "default-namespace robot uses id=''");
+  assert.equal(detected[0]!.cmdVelTopic, "/cmd_vel");
+});