agenticros 0.3.4 → 0.4.0

package/runtime/packages/core/src/__tests__/heartbeat-fleet.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Heartbeat + fleet-config unit tests.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  detectRobotsFromTopics,
+  discoverRobots,
+} from "../discovery.js";
+import {
+  isHeartbeatFresh,
+  mergeRobotHeartbeats,
+  onlineIdsFromHeartbeats,
+  parseRobotInfoMessage,
+  DEFAULT_HEARTBEAT_STALENESS_MS,
+} from "../heartbeat.js";
+import { applyFleetOverride, loadFleetFile } from "../fleet-config.js";
+import { listRobots } from "../robots.js";
+import { parseConfig } from "../config.js";
+
+test("parseRobotInfoMessage extracts fields", () => {
+  const hb = parseRobotInfoMessage("/bot1/agenticros/robot_info", {
+    id: "kitchen",
+    name: "Kitchen Bot",
+    kind: "amr",
+    robot_namespace: "bot1",
+    capability_ids: ["drive_base", "follow_person"],
+    has_realsense: true,
+    has_lidar: false,
+    has_arm: false,
+    stamp: { sec: 1_700_000_000, nanosec: 0 },
+  });
+  assert.equal(hb.id, "kitchen");
+  assert.equal(hb.sensors.has_realsense, true);
+  assert.equal(hb.stamp_ms, 1_700_000_000_000);
+  assert.deepEqual(hb.capability_ids, ["drive_base", "follow_person"]);
+});
+
+test("isHeartbeatFresh respects 5s window", () => {
+  const now = 1_000_000;
+  const fresh = parseRobotInfoMessage("/n/agenticros/robot_info", {
+    id: "a",
+    robot_namespace: "n",
+    stamp: { sec: Math.floor((now - 2000) / 1000), nanosec: 0 },
+  });
+  // Fix stamp_ms manually for precise control
+  fresh.stamp_ms = now - 2000;
+  assert.equal(isHeartbeatFresh(fresh, { nowMs: now }), true);
+
+  const stale = { ...fresh, stamp_ms: now - DEFAULT_HEARTBEAT_STALENESS_MS - 1 };
+  assert.equal(isHeartbeatFresh(stale, { nowMs: now }), false);
+});
+
+test("onlineIdsFromHeartbeats maps to configured ids", () => {
+  const now = Date.now();
+  const hb = parseRobotInfoMessage("/robotabc/agenticros/robot_info", {
+    id: "wire-id",
+    robot_namespace: "robotabc",
+    stamp: { sec: Math.floor(now / 1000), nanosec: 0 },
+  });
+  hb.stamp_ms = now;
+  const map = new Map([["robotabc", "configured-kitchen"]]);
+  const online = onlineIdsFromHeartbeats([hb], {
+    nowMs: now,
+    configuredIdByNamespace: map,
+  });
+  assert.ok(online.has("configured-kitchen"));
+});
+
+test("mergeRobotHeartbeats keeps freshest per namespace", () => {
+  const now = Date.now();
+  const older = parseRobotInfoMessage("/robotn/agenticros/robot_info", {
+    id: "a",
+    robot_namespace: "robotn",
+    name: "old",
+  });
+  older.stamp_ms = now - 1000;
+  const newer = parseRobotInfoMessage("/robotn/agenticros/robot_info", {
+    id: "a",
+    robot_namespace: "robotn",
+    name: "new",
+  });
+  newer.stamp_ms = now;
+  const merged = mergeRobotHeartbeats([older, newer], { nowMs: now });
+  assert.equal(merged.get("robotn")?.name, "new");
+});
+
+test("detectRobotsFromTopics includes robot_info-only namespaces", () => {
+  const detected = detectRobotsFromTopics([
+    { name: "/arm1/agenticros/robot_info", type: "agenticros_msgs/msg/RobotInfo" },
+  ]);
+  assert.equal(detected.length, 1);
+  assert.equal(detected[0]!.id, "arm1");
+});
+
+test("discoverRobots treats robot_info topic as online signal", () => {
+  // Isolate from a real ~/.agenticros/fleet.json on the developer machine.
+  const prev = process.env.AGENTICROS_FLEET_PATH;
+  process.env.AGENTICROS_FLEET_PATH = join(tmpdir(), "no-fleet-for-discover-test.json");
+  try {
+    // Namespace must already be the on-wire form (or UUID) so
+    // effectiveCmdVelNamespace matches the topic segment.
+    const cfg = parseConfig({
+      robots: [{ id: "arm1", namespace: "robotarm1", kind: "arm" }],
+    });
+    const result = discoverRobots(
+      [{ name: "/robotarm1/agenticros/robot_info", type: "agenticros_msgs/msg/RobotInfo" }],
+      cfg,
+    );
+    assert.equal(result.configured_online.length, 1);
+    assert.equal(result.configured_online[0]!.id, "arm1");
+  } finally {
+    if (prev === undefined) delete process.env.AGENTICROS_FLEET_PATH;
+    else process.env.AGENTICROS_FLEET_PATH = prev;
+  }
+});
+
+test("loadFleetFile + applyFleetOverride wins over config.robots", () => {
+  const dir = mkdtempSync(join(tmpdir(), "agenticros-fleet-"));
+  const path = join(dir, "fleet.json");
+  try {
+    writeFileSync(
+      path,
+      JSON.stringify([{ id: "fleet-bot", namespace: "fleetns", kind: "amr", name: "From Fleet" }]),
+    );
+    const loaded = loadFleetFile(path);
+    assert.equal(loaded.used, true);
+    assert.equal(loaded.robots[0]!.id, "fleet-bot");
+
+    const cfg = parseConfig({
+      robots: [{ id: "config-bot", namespace: "configns" }],
+    });
+    const overridden = applyFleetOverride(cfg, path);
+    const robots = listRobots(overridden);
+    // listRobots also applies fleet from default path — pass overridden
+    // config that already has fleet robots embedded:
+    assert.equal(overridden.robots?.[0]?.id, "fleet-bot");
+    assert.equal(robots[0]!.id, "fleet-bot");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("loadFleetFile missing file is unused", () => {
+  const result = loadFleetFile(join(tmpdir(), "no-such-agenticros-fleet-xyz.json"));
+  assert.equal(result.used, false);
+  assert.equal(result.robots.length, 0);
+});

package/runtime/packages/core/src/__tests__/mission-bindings.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Unit tests for buildMissionBindings — Phase 1 dynamic bindings.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  BUILTIN_MISSION_BINDINGS,
+  buildMissionBindings,
+  defaultToolForCapability,
+  externalToolName,
+  isExternalToolName,
+} from "../mission-bindings.js";
+import type { Capability } from "../capabilities.js";
+
+test("buildMissionBindings includes all builtins", () => {
+  const bindings = buildMissionBindings([]);
+  for (const id of Object.keys(BUILTIN_MISSION_BINDINGS)) {
+    assert.ok(bindings[id], `missing builtin binding ${id}`);
+  }
+});
+
+test("buildMissionBindings derives ros2_<id> for skill capabilities", () => {
+  const caps: Capability[] = [
+    {
+      id: "wave_hand",
+      verb: "wave",
+      description: "Wave",
+      source: { kind: "skill", skillId: "wave", package: "agenticros-skill-wave" },
+    },
+  ];
+  const bindings = buildMissionBindings(caps);
+  assert.equal(bindings.wave_hand.tool, "ros2_wave_hand");
+  assert.deepEqual(bindings.wave_hand.buildArgs({ a: 1 }), { a: 1 });
+});
+
+test("buildMissionBindings uses external: prefix for external_ros_node", () => {
+  const caps: Capability[] = [
+    {
+      id: "navigate_to",
+      verb: "navigate",
+      description: "Nav2",
+      implementation: {
+        kind: "external_ros_node",
+        action: "navigate_to_pose",
+        msg_type: "nav2_msgs/action/NavigateToPose",
+      },
+      source: { kind: "skill", skillId: "navigate", package: "navigate-to" },
+    },
+  ];
+  const bindings = buildMissionBindings(caps);
+  assert.equal(bindings.navigate_to.tool, externalToolName("navigate_to"));
+  assert.ok(isExternalToolName(bindings.navigate_to.tool));
+});
+
+test("buildMissionBindings respects toolNameResolver", () => {
+  const caps: Capability[] = [
+    {
+      id: "custom_cap",
+      verb: "custom",
+      description: "Custom",
+      source: { kind: "skill", skillId: "c", package: "c" },
+    },
+  ];
+  const bindings = buildMissionBindings(caps, {
+    toolNameResolver: (cap) => (cap.id === "custom_cap" ? "my_custom_tool" : undefined),
+  });
+  assert.equal(bindings.custom_cap.tool, "my_custom_tool");
+});
+
+test("defaultToolForCapability prefers explicit tool field", () => {
+  assert.equal(
+    defaultToolForCapability({
+      id: "x",
+      verb: "x",
+      description: "x",
+      tool: "ros2_special",
+    }),
+    "ros2_special",
+  );
+});
+
+test("extra bindings win over derived", () => {
+  const caps: Capability[] = [
+    {
+      id: "wave_hand",
+      verb: "wave",
+      description: "Wave",
+      source: { kind: "skill", skillId: "wave", package: "w" },
+    },
+  ];
+  const bindings = buildMissionBindings(caps, {
+    extra: {
+      wave_hand: {
+        tool: "override_tool",
+        buildArgs: () => ({ overridden: true }),
+      },
+    },
+  });
+  assert.equal(bindings.wave_hand.tool, "override_tool");
+});

package/runtime/packages/core/src/__tests__/mission-pause.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Pause / resume tests for runMission + MissionRegistry.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runMission, type CapabilityToolBindings, type Mission } from "../mission.js";
+import { MissionRegistry } from "../mission-registry.js";
+import type { Capability } from "../capabilities.js";
+
+const CAPS: Capability[] = [
+  { id: "drive_base", verb: "drive", description: "Drive", source: { kind: "builtin" } },
+  { id: "list_topics", verb: "list", description: "List", source: { kind: "builtin" } },
+];
+
+const BINDINGS: CapabilityToolBindings = {
+  drive_base: {
+    tool: "ros2_publish",
+    buildArgs: (inputs) => ({ topic: "cmd_vel", msg: inputs }),
+  },
+  list_topics: {
+    tool: "ros2_list_topics",
+    buildArgs: () => ({}),
+  },
+};
+
+test("pause blocks next step until resume", async () => {
+  const token = { cancelled: false, paused: true, reason: "human in aisle" };
+  const calls: string[] = [];
+  const mission: Mission = {
+    name: "pause-test",
+    steps: [
+      { id: "a", capability: "list_topics" },
+      { id: "b", capability: "drive_base", inputs: { linear_x: 0.1 } },
+    ],
+  };
+
+  const runPromise = runMission(mission, CAPS, BINDINGS, async (tool) => {
+    calls.push(tool);
+    return { text: JSON.stringify({ ok: true }) };
+  }, { cancellation: token, mission_id: "mn_pause" });
+
+  // First step should not run while paused — wait a bit then resume.
+  await new Promise((r) => setTimeout(r, 150));
+  assert.equal(calls.length, 0, "no tools while paused before first step");
+  token.paused = false;
+
+  const result = await runPromise;
+  assert.equal(result.status, "ok");
+  assert.equal(calls.length, 2);
+  assert.deepEqual(calls, ["ros2_list_topics", "ros2_publish"]);
+});
+
+test("cancel while paused aborts remaining steps", async () => {
+  const token = { cancelled: false, paused: true };
+  const mission: Mission = {
+    steps: [
+      { id: "a", capability: "list_topics" },
+      { id: "b", capability: "drive_base" },
+    ],
+  };
+
+  const runPromise = runMission(mission, CAPS, BINDINGS, async () => ({ text: "{}" }), {
+    cancellation: token,
+  });
+
+  await new Promise((r) => setTimeout(r, 80));
+  token.cancelled = true;
+  token.paused = false;
+
+  const result = await runPromise;
+  assert.equal(result.status, "cancelled");
+  assert.ok(result.steps.every((s) => s.status === "cancelled"));
+});
+
+test("MissionRegistry pause/resume/cancel", () => {
+  const reg = new MissionRegistry();
+  const { entry, dispose } = reg.register("mn_1", { name: "t" });
+  assert.equal(entry.cancellation.paused, false);
+
+  const p1 = reg.pause("mn_1", "wait");
+  assert.equal(p1.found, true);
+  assert.equal(p1.alreadyPaused, false);
+  assert.equal(entry.cancellation.paused, true);
+  assert.equal(entry.cancellation.reason, "wait");
+
+  const p2 = reg.pause("mn_1");
+  assert.equal(p2.alreadyPaused, true);
+
+  const r1 = reg.resume("mn_1");
+  assert.equal(r1.found, true);
+  assert.equal(r1.wasPaused, true);
+  assert.equal(entry.cancellation.paused, false);
+
+  assert.equal(reg.pause("missing").found, false);
+  assert.equal(reg.resume("missing").found, false);
+
+  reg.pause("mn_1");
+  reg.cancel("mn_1", "abort");
+  assert.equal(entry.cancellation.cancelled, true);
+  assert.equal(entry.cancellation.paused, false);
+
+  dispose();
+});

package/runtime/packages/core/src/__tests__/skill-refs.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Unit tests for skillRefs parsing and discoverable capability merge.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  parseSkillRef,
+  parseConfig,
+  listCapabilitiesWithDiscoverable,
+  listAllCapabilities,
+} from "../index.js";
+
+test("parseSkillRef: owner/skill and @pin", () => {
+  assert.deepEqual(parseSkillRef("agenticros/navigate-to"), {
+    marketplaceRef: "agenticros/navigate-to",
+    owner: "agenticros",
+    skill: "navigate-to",
+    gitRef: "main",
+  });
+  assert.equal(parseSkillRef("agenticros/start-slam@v0.1.0")?.gitRef, "v0.1.0");
+  assert.equal(parseSkillRef("nope"), null);
+  assert.equal(parseSkillRef(""), null);
+});
+
+test("parseConfig: skillRefs defaults to []", () => {
+  const cfg = parseConfig({});
+  assert.deepEqual(cfg.skillRefs, []);
+  const cfg2 = parseConfig({ skillRefs: ["agenticros/detect-humans"] });
+  assert.deepEqual(cfg2.skillRefs, ["agenticros/detect-humans"]);
+});
+
+test("listCapabilitiesWithDiscoverable: soft-fail offline keeps installed", async () => {
+  const cfg = parseConfig({});
+  const caps = await listCapabilitiesWithDiscoverable(cfg, {
+    apiBase: "http://127.0.0.1:9", // nothing listening
+    softFail: true,
+  });
+  const baseline = listAllCapabilities(cfg);
+  assert.equal(caps.length, baseline.length);
+  assert.ok(caps.every((c) => c.installed !== false || c.discoverable !== true));
+});
+
+test("listCapabilitiesWithDiscoverable: merges marketplace caps when fetch works", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    new Response(
+      JSON.stringify({
+        skills: [
+          {
+            marketplaceRef: "agenticros/detect-humans",
+            visibility: "public",
+            capabilities: [
+              {
+                id: "detect_humans",
+                verb: "detect",
+                description: "Read detections",
+              },
+            ],
+          },
+        ],
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    )) as typeof fetch;
+
+  try {
+    const cfg = parseConfig({});
+    const caps = await listCapabilitiesWithDiscoverable(cfg, { softFail: false });
+    const det = caps.find((c) => c.id === "detect_humans");
+    assert.ok(det);
+    assert.equal(det!.discoverable, true);
+    assert.equal(det!.installed, false);
+    assert.equal(det!.install_ref, "agenticros/detect-humans");
+    assert.ok(caps.some((c) => c.id === "drive_base" && c.installed === true));
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

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

@@ -193,9 +193,30 @@ function normalizeCapability(
   };
 }
 
+function readCapabilitiesJson(
+  packageDir: string,
+): Array<Partial<Capability> & { id: string }> {
+  const capsPath = join(packageDir, "capabilities.json");
+  if (!existsSync(capsPath)) return [];
+  try {
+    const raw = JSON.parse(readFileSync(capsPath, "utf-8")) as unknown;
+    const list = Array.isArray(raw)
+      ? raw
+      : raw && typeof raw === "object" && Array.isArray((raw as { capabilities?: unknown }).capabilities)
+        ? (raw as { capabilities: unknown[] }).capabilities
+        : [];
+    const out: Array<Partial<Capability> & { id: string }> = [];
+    for (const c of list) if (isCapabilityLike(c)) out.push(c);
+    return out;
+  } catch {
+    return [];
+  }
+}
+
 /**
- * Read the `agenticros.capabilities[]` array from a skill's package.json.
- * Returns `null` if the package doesn't declare a valid `agenticros` block.
+ * Read the `agenticros.capabilities[]` array from a skill's package.json,
+ * merging any sibling `capabilities.json`. Returns `null` if the package
+ * doesn't declare a valid `agenticros` block.
  *
  * The legacy `agenticrosSkill: true | { capabilities }` form is NOT supported
  * — every skill must use the single `agenticros` block as its source of truth.
@@ -220,10 +241,24 @@ function readSkillManifestFromDir(
   const packageName = pkg.name ?? "unknown";
   const skillId = pkg.agenticros.id;
   const rawCaps: Array<Partial<Capability> & { id: string }> = [];
+  const seenIds = new Set<string>();
 
   const caps = pkg.agenticros.capabilities;
   if (Array.isArray(caps)) {
-    for (const c of caps) if (isCapabilityLike(c)) rawCaps.push(c);
+    for (const c of caps) {
+      if (isCapabilityLike(c) && !seenIds.has(c.id)) {
+        seenIds.add(c.id);
+        rawCaps.push(c);
+      }
+    }
+  }
+
+  // Sibling capabilities.json merges in (package.json wins on id conflict).
+  for (const c of readCapabilitiesJson(packageDir)) {
+    if (!seenIds.has(c.id)) {
+      seenIds.add(c.id);
+      rawCaps.push(c);
+    }
   }
 
   return { packageName, skillId, rawCaps };

package/runtime/packages/core/src/capability-schema.ts

@@ -0,0 +1,58 @@
+/**
+ * Zod schemas for capability manifests (skill load / CLI publish).
+ */
+
+import { z } from "zod";
+
+export const CapabilityFieldSchema = z.object({
+  type: z.string(),
+  description: z.string().optional(),
+  optional: z.boolean().optional(),
+  default: z.unknown().optional(),
+});
+
+export const CapabilityImplementationSchema = z.union([
+  z.object({ kind: z.literal("in_process") }),
+  z.object({
+    kind: z.literal("external_ros_node"),
+    package: z.string().optional(),
+    launch: z.string().optional(),
+    action: z.string().optional(),
+    service: z.string().optional(),
+    topic: z.string().optional(),
+    msg_type: z.string().optional(),
+  }),
+]);
+
+export const CapabilitySchema = z.object({
+  id: z.string().min(1),
+  verb: z.string().min(1),
+  description: z.string().default(""),
+  inputs: z.record(CapabilityFieldSchema).optional(),
+  outputs: z.record(CapabilityFieldSchema).optional(),
+  preconditions: z.array(z.string()).optional(),
+  interruptible: z.boolean().optional(),
+  blocks_base: z.boolean().optional(),
+  implementation: CapabilityImplementationSchema.optional(),
+  tool: z.string().optional(),
+});
+
+export type ParsedCapability = z.infer<typeof CapabilitySchema>;
+
+/**
+ * Validate a raw capability object. Throws ZodError on failure.
+ */
+export function parseCapability(raw: unknown): ParsedCapability {
+  return CapabilitySchema.parse(raw);
+}
+
+/**
+ * Soft-validate: returns { ok, capability?, error? }.
+ */
+export function safeParseCapability(
+  raw: unknown,
+): { ok: true; capability: ParsedCapability } | { ok: false; error: string } {
+  const result = CapabilitySchema.safeParse(raw);
+  if (result.success) return { ok: true, capability: result.data };
+  return { ok: false, error: result.error.message };
+}

package/runtime/packages/core/src/config.ts

@@ -418,6 +418,14 @@ export const AgenticROSConfigSchema = z.object({
 
   /** Npm (or local) package names to load as skills. Resolved via require.resolve from plugin context. */
   skillPackages: z.array(z.string()).default([]),
+
+  /**
+   * Marketplace skill refs to auto-fetch into `~/.agenticros/skills-cache/`
+   * (e.g. `agenticros/navigate-to` or `owner/skill@main`). Resolved at
+   * adapter startup into effective skillPaths. Never auto-upgrades pins.
+   * Distinct from `skills` (per-skill runtime config object).
+   */
+  skillRefs: z.array(z.string()).default([]),
 });
 
 export type AgenticROSConfig = z.infer<typeof AgenticROSConfigSchema>;
@@ -441,6 +449,26 @@ export function parseConfig(raw: Record<string, unknown>): AgenticROSConfig {
   return AgenticROSConfigSchema.parse(normalized);
 }
 
+/**
+ * Strip Zod defaults that were never present in the raw config before parse.
+ * The config page validates via parseConfig() but should not inject keys the
+ * user never set — e.g. `robots: []` from the schema default breaks OpenClaw's
+ * strict plugin configSchema when that field isn't declared yet.
+ */
+export function prepareConfigForPersistence(
+  parsed: AgenticROSConfig,
+  raw: Record<string, unknown>,
+): Record<string, unknown> {
+  const out = JSON.parse(JSON.stringify(parsed)) as Record<string, unknown>;
+  if (!Object.prototype.hasOwnProperty.call(raw, "robots")) {
+    const robots = out.robots;
+    if (Array.isArray(robots) && robots.length === 0) {
+      delete out.robots;
+    }
+  }
+  return out;
+}
+
 /**
  * Build TransportConfig from full config for createTransport().
  */