agenticros 0.1.18 → 0.2.0

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

@@ -0,0 +1,279 @@
+/**
+ * Unit tests for the Phase 1.g rule-based mission planner.
+ *
+ * These tests pin the contract for `compileGoalToMission`:
+ *
+ *   - Recognised verbs (find / take / measure / follow / drive / list)
+ *     map to the right capability ids and extract structured inputs.
+ *   - Compound "find X and drive toward it" emits a 2-step plan with
+ *     the canonical template ref so the runner steers via the
+ *     detected horizontal_offset.
+ *   - Skill capabilities the runtime doesn't have are NOT fabricated
+ *     — if `find_object` isn't in the registry, "find a chair" fails
+ *     gracefully instead of pretending to run.
+ *   - Failures surface a useful error + suggestions list so the
+ *     agent can self-correct without an extra round-trip.
+ *   - Multi-segment goals ("X and Y") compile each segment
+ *     independently; segments that don't map are recorded as
+ *     `unmatched_verbs` for explainability.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { compileGoalToMission } from "../planner/index.js";
+import type { Capability } from "../capabilities.js";
+
+const BASE_CAPS: Capability[] = [
+  { id: "drive_base", verb: "drive", description: "drive", source: { kind: "builtin" } },
+  { id: "take_snapshot", verb: "see", description: "see", source: { kind: "builtin" } },
+  { id: "measure_depth", verb: "measure", description: "measure", source: { kind: "builtin" } },
+  { id: "list_topics", verb: "introspect", description: "list", source: { kind: "builtin" } },
+  {
+    id: "find_object",
+    verb: "find",
+    description: "find",
+    source: { kind: "skill", skillId: "find", package: "agenticros-skill-find" },
+  },
+  {
+    id: "follow_person",
+    verb: "follow",
+    description: "follow",
+    source: { kind: "skill", skillId: "followme", package: "agenticros-skill-followme" },
+  },
+];
+
+// --- Recognition: single-verb goals ---
+
+test("planner: 'find a chair' compiles to a single find_object step", () => {
+  const res = compileGoalToMission("find a chair", BASE_CAPS);
+  assert.ok(res.mission, `expected mission, got error: ${res.error}`);
+  assert.equal(res.mission!.steps.length, 1);
+  assert.equal(res.mission!.steps[0].capability, "find_object");
+  assert.equal((res.mission!.steps[0].inputs as { target: string }).target, "chair");
+  assert.equal(res.mission!.goal, "find a chair");
+  assert.ok(res.mission!.name?.includes("find a chair"));
+});
+
+test("planner: 'where is the laptop' compiles to find_object with target=laptop", () => {
+  const res = compileGoalToMission("Where is the laptop?", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps[0].capability, "find_object");
+  assert.equal((res.mission!.steps[0].inputs as { target: string }).target, "laptop");
+});
+
+test("planner: 'look for a bottle' uses the 'look for' synonym", () => {
+  const res = compileGoalToMission("Look for a bottle", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal((res.mission!.steps[0].inputs as { target: string }).target, "bottle");
+});
+
+test("planner: 'take a picture' maps to take_snapshot", () => {
+  const res = compileGoalToMission("take a picture", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps.length, 1);
+  assert.equal(res.mission!.steps[0].capability, "take_snapshot");
+});
+
+test("planner: 'what do you see' maps to take_snapshot", () => {
+  const res = compileGoalToMission("What do you see?", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps[0].capability, "take_snapshot");
+});
+
+test("planner: 'measure depth' maps to measure_depth", () => {
+  const res = compileGoalToMission("Measure depth", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps[0].capability, "measure_depth");
+});
+
+test("planner: 'how far away is the wall' maps to measure_depth", () => {
+  const res = compileGoalToMission("How far away is the wall?", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps[0].capability, "measure_depth");
+});
+
+test("planner: 'follow me' maps to follow_person", () => {
+  const res = compileGoalToMission("follow me", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps[0].capability, "follow_person");
+});
+
+test("planner: 'list topics' maps to list_topics", () => {
+  const res = compileGoalToMission("list topics", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps[0].capability, "list_topics");
+});
+
+// --- Drive parsing ---
+
+test("planner: 'drive forward' produces positive linear_x with default speed", () => {
+  const res = compileGoalToMission("drive forward", BASE_CAPS);
+  assert.ok(res.mission);
+  const inputs = res.mission!.steps[0].inputs as { linear_x: number; angular_z: number };
+  assert.ok(inputs.linear_x > 0, `linear_x should be positive, got ${inputs.linear_x}`);
+  assert.equal(inputs.angular_z, 0);
+});
+
+test("planner: 'drive forward at 0.5 m/s' extracts the explicit speed", () => {
+  const res = compileGoalToMission("drive forward at 0.5 m/s", BASE_CAPS);
+  assert.ok(res.mission);
+  const inputs = res.mission!.steps[0].inputs as { linear_x: number };
+  assert.equal(inputs.linear_x, 0.5);
+});
+
+test("planner: 'drive backward' produces NEGATIVE linear_x", () => {
+  const res = compileGoalToMission("drive backward", BASE_CAPS);
+  assert.ok(res.mission);
+  const inputs = res.mission!.steps[0].inputs as { linear_x: number; angular_z: number };
+  assert.ok(inputs.linear_x < 0, `linear_x should be negative, got ${inputs.linear_x}`);
+});
+
+test("planner: 'turn left' produces positive angular_z", () => {
+  const res = compileGoalToMission("turn left", BASE_CAPS);
+  assert.ok(res.mission);
+  const inputs = res.mission!.steps[0].inputs as { linear_x: number; angular_z: number };
+  assert.equal(inputs.linear_x, 0);
+  assert.ok(inputs.angular_z > 0);
+});
+
+test("planner: 'turn right' produces NEGATIVE angular_z", () => {
+  const res = compileGoalToMission("turn right", BASE_CAPS);
+  assert.ok(res.mission);
+  const inputs = res.mission!.steps[0].inputs as { angular_z: number };
+  assert.ok(inputs.angular_z < 0);
+});
+
+test("planner: 'stop' produces a zero-velocity drive_base step", () => {
+  const res = compileGoalToMission("stop", BASE_CAPS);
+  assert.ok(res.mission);
+  const inputs = res.mission!.steps[0].inputs as { linear_x: number; angular_z: number };
+  assert.equal(inputs.linear_x, 0);
+  assert.equal(inputs.angular_z, 0);
+});
+
+test("planner: bare 'drive' (no direction) does NOT compile (avoids no-op steps)", () => {
+  // A drive without direction is ambiguous — the planner must NOT
+  // emit a useless zero-velocity step that's identical to "stop".
+  const res = compileGoalToMission("drive", BASE_CAPS);
+  assert.equal(res.mission, null);
+  assert.ok(res.error);
+});
+
+// --- Compound: find then approach ---
+
+test("planner: 'find a chair and drive toward it' compiles to a 2-step plan with template ref", () => {
+  const res = compileGoalToMission("find a chair and drive toward it", BASE_CAPS);
+  assert.ok(res.mission, `expected mission, got error: ${res.error}`);
+  assert.equal(res.mission!.steps.length, 2);
+  // Step 1: find_object with target=chair
+  assert.equal(res.mission!.steps[0].id, "find");
+  assert.equal(res.mission!.steps[0].capability, "find_object");
+  assert.equal((res.mission!.steps[0].inputs as { target: string }).target, "chair");
+  // Step 2: drive_base with templated angular_z so the runner steers
+  // via the detected horizontal_offset.
+  assert.equal(res.mission!.steps[1].id, "approach");
+  assert.equal(res.mission!.steps[1].capability, "drive_base");
+  const driveInputs = res.mission!.steps[1].inputs as { linear_x: number; angular_z: string };
+  assert.ok(driveInputs.linear_x > 0, "approach should move forward");
+  assert.equal(
+    driveInputs.angular_z,
+    "{{find.outputs.horizontal_offset}}",
+    "angular_z must reference find_object's horizontal_offset output via the runner template",
+  );
+});
+
+test("planner: 'find a bottle and approach it' is the same 2-step pattern (approach synonym)", () => {
+  const res = compileGoalToMission("find a bottle and approach it", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps.length, 2);
+  assert.equal((res.mission!.steps[0].inputs as { target: string }).target, "bottle");
+  assert.equal(res.mission!.steps[1].capability, "drive_base");
+});
+
+// --- Multi-segment compounds (independent steps) ---
+
+test("planner: 'take a picture and then measure depth' compiles to 2 independent steps", () => {
+  const res = compileGoalToMission("take a picture and then measure depth", BASE_CAPS);
+  assert.ok(res.mission, `expected mission, got error: ${res.error}`);
+  assert.equal(res.mission!.steps.length, 2);
+  assert.equal(res.mission!.steps[0].capability, "take_snapshot");
+  assert.equal(res.mission!.steps[1].capability, "measure_depth");
+});
+
+test("planner: 'follow me then take a picture' compiles to 2 sequential steps", () => {
+  const res = compileGoalToMission("follow me then take a picture", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.mission!.steps.length, 2);
+  assert.equal(res.mission!.steps[0].capability, "follow_person");
+  assert.equal(res.mission!.steps[1].capability, "take_snapshot");
+});
+
+// --- Capability availability (no fabrication) ---
+
+test("planner: 'find a chair' fails when find_object isn't in the registry (no fabricated calls)", () => {
+  const noFind = BASE_CAPS.filter((c) => c.id !== "find_object");
+  const res = compileGoalToMission("find a chair", noFind);
+  assert.equal(res.mission, null);
+  assert.ok(res.error);
+  // The planner mentions available capabilities so the agent can pivot.
+  const allSuggestions = res.suggestions.join(" ");
+  assert.ok(allSuggestions.includes("Available capabilities"), `expected suggestions to list capabilities; got: ${allSuggestions}`);
+});
+
+test("planner: 'follow me' fails when follow_person isn't installed", () => {
+  const noFollow = BASE_CAPS.filter((c) => c.id !== "follow_person");
+  const res = compileGoalToMission("follow me", noFollow);
+  assert.equal(res.mission, null);
+});
+
+// --- Failure paths ---
+
+test("planner: empty goal returns a clean error", () => {
+  const res = compileGoalToMission("", BASE_CAPS);
+  assert.equal(res.mission, null);
+  assert.ok(res.error?.toLowerCase().includes("empty"));
+  // Suggestions should still surface so the agent can recover.
+  assert.ok(res.suggestions.length > 0);
+});
+
+test("planner: whitespace-only goal is treated as empty", () => {
+  const res = compileGoalToMission("   \n\t  ", BASE_CAPS);
+  assert.equal(res.mission, null);
+  assert.ok(res.error);
+});
+
+test("planner: 'paint the wall blue' (unrecognised verb) fails gracefully with suggestions", () => {
+  const res = compileGoalToMission("paint the wall blue", BASE_CAPS);
+  assert.equal(res.mission, null);
+  assert.ok(res.error);
+  assert.ok(res.suggestions.length > 0, "must surface suggestions on failure");
+});
+
+// --- Options pass-through ---
+
+test("planner: options.robot_id is propagated onto the compiled mission", () => {
+  const res = compileGoalToMission("take a picture", BASE_CAPS, { robot_id: "robotA" });
+  assert.ok(res.mission);
+  assert.equal(res.mission!.robot_id, "robotA");
+});
+
+test("planner: options.mission_name overrides the default 'Goal: <goal>' label", () => {
+  const res = compileGoalToMission("take a picture", BASE_CAPS, { mission_name: "Snap" });
+  assert.ok(res.mission);
+  assert.equal(res.mission!.name, "Snap");
+});
+
+// --- Candidates surface ---
+
+test("planner: candidates list contains the matched capability ids in declaration order", () => {
+  const res = compileGoalToMission("find a chair and drive toward it", BASE_CAPS);
+  assert.ok(res.mission);
+  assert.equal(res.candidates.length, 2);
+  assert.equal(res.candidates[0].capability_id, "find_object");
+  assert.equal(res.candidates[1].capability_id, "drive_base");
+  for (const c of res.candidates) {
+    assert.ok(c.confidence > 0 && c.confidence <= 1, `confidence should be in (0,1]; got ${c.confidence}`);
+    assert.ok(c.rationale.length > 0);
+  }
+});

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

@@ -0,0 +1,406 @@
+/**
+ * Unit tests for the Phase 1.d multi-robot resolver.
+ *
+ * What these tests pin down (each one corresponds to a real failure mode
+ * the resolver has to defend against in production):
+ *
+ *   - Backwards compat: existing single-robot configs (no `robots`
+ *     array) must yield a synthesized one-entry list so older configs
+ *     don't break and the chat agent doesn't see "no robots configured".
+ *   - Synthesized fallback id derives from namespace when non-empty,
+ *     defaults to "default" otherwise — important because the active id
+ *     is what tool calls will key off in the next iteration.
+ *   - Explicit `robots: []` takes precedence over the legacy single
+ *     robot when non-empty.
+ *   - `default: true` flag wins regardless of position. First-entry wins
+ *     when no default flag.
+ *   - `resolveRobot(robotId)` returns the matching entry, OR a
+ *     descriptive error containing the known ids — the error text shape
+ *     matters because the LLM uses it to self-correct.
+ *   - `resolveRobot()` with no id returns the active robot, matching
+ *     getActiveRobotId().
+ *   - Edge: an explicit override on getActiveRobotId returns it
+ *     verbatim (even if the id doesn't exist — discovery happens at
+ *     resolveRobot time, not here).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { parseConfig } from "../config.js";
+import {
+  listRobots,
+  resolveRobot,
+  getActiveRobotId,
+  getTransportConfigForRobot,
+  hasRobotTransportOverride,
+  type ResolvedRobot,
+} from "../robots.js";
+
+test("robots: empty config yields one synthesized 'default' entry (legacy fallback)", () => {
+  const cfg = parseConfig({});
+  const robots = listRobots(cfg);
+  assert.equal(robots.length, 1);
+  assert.equal(robots[0].id, "default");
+  assert.equal(robots[0].name, "Robot");
+  assert.equal(robots[0].namespace, "");
+  assert.equal(robots[0].source, "legacy");
+});
+
+test("robots: legacy single-robot config synthesizes id from namespace", () => {
+  const cfg = parseConfig({
+    robot: { name: "Spot", namespace: "robot-spot-1", cameraTopic: "/cam" },
+  });
+  const robots = listRobots(cfg);
+  assert.equal(robots.length, 1);
+  assert.equal(robots[0].id, "robot-spot-1");
+  assert.equal(robots[0].name, "Spot");
+  assert.equal(robots[0].namespace, "robot-spot-1");
+  assert.equal(robots[0].cameraTopic, "/cam");
+  assert.equal(robots[0].source, "legacy");
+});
+
+test("robots: explicit robots[] array overrides the legacy single-robot fallback", () => {
+  const cfg = parseConfig({
+    robot: { name: "Ignored", namespace: "ignored-ns" },
+    robots: [
+      { id: "alpha", name: "Alpha", namespace: "ns-alpha" },
+      { id: "beta", name: "Beta", namespace: "ns-beta" },
+    ],
+  });
+  const robots = listRobots(cfg);
+  assert.equal(robots.length, 2);
+  assert.deepEqual(
+    robots.map((r) => r.id),
+    ["alpha", "beta"],
+  );
+  for (const r of robots) assert.equal(r.source, "config");
+});
+
+test("robots: getActiveRobotId returns first entry when no default flag is set", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", name: "Alpha" },
+      { id: "beta", name: "Beta" },
+    ],
+  });
+  assert.equal(getActiveRobotId(cfg), "alpha");
+});
+
+test("robots: getActiveRobotId picks the default-flagged entry regardless of position", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", name: "Alpha" },
+      { id: "beta", name: "Beta", default: true },
+      { id: "gamma", name: "Gamma" },
+    ],
+  });
+  assert.equal(getActiveRobotId(cfg), "beta");
+});
+
+test("robots: getActiveRobotId honours explicit override", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", name: "Alpha" },
+      { id: "beta", name: "Beta", default: true },
+    ],
+  });
+  assert.equal(getActiveRobotId(cfg, "alpha"), "alpha");
+});
+
+test("robots: getActiveRobotId trims whitespace from the override", () => {
+  const cfg = parseConfig({
+    robots: [{ id: "alpha", name: "Alpha" }],
+  });
+  assert.equal(getActiveRobotId(cfg, "  alpha  "), "alpha");
+});
+
+test("robots: getActiveRobotId ignores empty-string overrides (falls through to default rules)", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", name: "Alpha" },
+      { id: "beta", name: "Beta", default: true },
+    ],
+  });
+  assert.equal(getActiveRobotId(cfg, ""), "beta");
+  assert.equal(getActiveRobotId(cfg, "   "), "beta");
+});
+
+test("robots: resolveRobot() with no id returns the active robot", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", name: "Alpha" },
+      { id: "beta", name: "Beta", default: true },
+    ],
+  });
+  const r = resolveRobot(cfg);
+  assert.equal(r.id, "beta");
+  assert.equal(r.name, "Beta");
+});
+
+test("robots: resolveRobot(id) returns the matching entry", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", name: "Alpha", namespace: "ns-a" },
+      { id: "beta", name: "Beta", namespace: "ns-b" },
+    ],
+  });
+  const r: ResolvedRobot = resolveRobot(cfg, "beta");
+  assert.equal(r.id, "beta");
+  assert.equal(r.namespace, "ns-b");
+});
+
+test("robots: resolveRobot(unknown id) throws with known ids listed in the error message", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", name: "Alpha" },
+      { id: "beta", name: "Beta" },
+    ],
+  });
+  assert.throws(
+    () => resolveRobot(cfg, "gamma"),
+    (err: Error) => {
+      assert.ok(
+        err.message.includes("gamma"),
+        `error should mention the unknown id (got: ${err.message})`,
+      );
+      assert.ok(
+        err.message.includes("alpha") && err.message.includes("beta"),
+        `error should list known ids (got: ${err.message})`,
+      );
+      assert.ok(
+        err.message.toLowerCase().includes("ros2_list_robots"),
+        `error should hint at ros2_list_robots for self-correction (got: ${err.message})`,
+      );
+      return true;
+    },
+  );
+});
+
+test("robots: resolveRobot trims whitespace from id arg", () => {
+  const cfg = parseConfig({
+    robots: [{ id: "alpha", name: "Alpha" }],
+  });
+  assert.equal(resolveRobot(cfg, "  alpha  ").id, "alpha");
+});
+
+test("robots: source tag distinguishes config vs legacy entries", () => {
+  const cfgLegacy = parseConfig({ robot: { namespace: "ns" } });
+  const cfgExplicit = parseConfig({ robots: [{ id: "x" }] });
+  assert.equal(listRobots(cfgLegacy)[0].source, "legacy");
+  assert.equal(listRobots(cfgExplicit)[0].source, "config");
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 1.d-resolve: per-robot transport override tests.
+//
+// These pin down a contract that matters for the multi-host fleet story —
+// once adopted by adapters, a single host can simultaneously drive a local
+// sim (mode: "local") AND a remote real robot reached via a router
+// (mode: "zenoh" / "rosbridge"). The resolver alone doesn't materialise
+// transports — it surfaces the right TransportConfig per robot id so an
+// adapter pool can call `createTransport` on it.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("transport-override: schema accepts a per-robot override and round-trips", () => {
+  const cfg = parseConfig({
+    robots: [
+      {
+        id: "sim",
+        namespace: "sim_robot",
+        transport: { mode: "local", local: { domainId: 7 } },
+      },
+    ],
+  });
+  // Parsed shape preserves the override discriminant + sub-section.
+  const raw = cfg.robots[0]?.transport;
+  assert.ok(raw, "override must survive parseConfig");
+  assert.equal(raw!.mode, "local");
+  // Discriminant-narrowed access.
+  if (raw!.mode === "local") {
+    assert.equal(raw!.local?.domainId, 7);
+  }
+});
+
+test("transport-override: schema rejects a sub-section that doesn't match the mode", () => {
+  // A `mode: "zenoh"` override with a `local: {...}` sub-section is a
+  // typo we want to catch at parse time — otherwise the override would
+  // silently fall back to the global zenoh config and the user's
+  // intent would be lost.
+  assert.throws(() =>
+    parseConfig({
+      robots: [
+        {
+          id: "sim",
+          transport: { mode: "zenoh", local: { domainId: 1 } } as unknown as Record<string, unknown>,
+        },
+      ],
+    }),
+  );
+});
+
+test("transport-override: getTransportConfigForRobot returns the override when set", () => {
+  const cfg = parseConfig({
+    transport: { mode: "rosbridge" },
+    rosbridge: { url: "ws://default:9090" },
+    robots: [
+      { id: "real", namespace: "real" },
+      {
+        id: "sim",
+        namespace: "sim_robot",
+        transport: { mode: "local", local: { domainId: 7 } },
+      },
+    ],
+  });
+  const t = getTransportConfigForRobot(cfg, "sim");
+  assert.equal(t.mode, "local");
+  if (t.mode === "local") {
+    assert.equal(t.local?.domainId, 7, "override domainId must win");
+  }
+});
+
+test("transport-override: getTransportConfigForRobot falls back to the global transport when no override", () => {
+  const cfg = parseConfig({
+    transport: { mode: "zenoh" },
+    zenoh: { routerEndpoint: "ws://global:10000" },
+    robots: [{ id: "real", namespace: "real" }],
+  });
+  const t = getTransportConfigForRobot(cfg, "real");
+  assert.equal(t.mode, "zenoh");
+  if (t.mode === "zenoh") {
+    assert.equal(t.zenoh.routerEndpoint, "ws://global:10000");
+  }
+});
+
+test("transport-override: sub-section omitted in override inherits from top-level config", () => {
+  // The user wants `sim` to use zenoh BUT didn't repeat the
+  // routerEndpoint inside the override. The resolver must use the
+  // top-level zenoh config so they don't have to duplicate it.
+  const cfg = parseConfig({
+    transport: { mode: "rosbridge" }, // global mode is different — irrelevant here
+    zenoh: { routerEndpoint: "ws://shared:10000", domainId: 3 },
+    robots: [
+      {
+        id: "sim",
+        namespace: "sim_robot",
+        transport: { mode: "zenoh" }, // no `zenoh: {...}` sub-section
+      },
+    ],
+  });
+  const t = getTransportConfigForRobot(cfg, "sim");
+  assert.equal(t.mode, "zenoh");
+  if (t.mode === "zenoh") {
+    assert.equal(t.zenoh.routerEndpoint, "ws://shared:10000");
+    assert.equal(t.zenoh.domainId, 3);
+  }
+});
+
+test("transport-override: partial sub-section in override merges over top-level (per-field precedence)", () => {
+  // The override only customises routerEndpoint — domainId should
+  // continue to come from the top-level config. This is the most
+  // common real-world shape (override just the endpoint, keep
+  // everything else).
+  const cfg = parseConfig({
+    transport: { mode: "rosbridge" },
+    zenoh: { routerEndpoint: "ws://shared:10000", domainId: 3 },
+    robots: [
+      {
+        id: "field",
+        namespace: "field_robot",
+        transport: {
+          mode: "zenoh",
+          zenoh: { routerEndpoint: "ws://field-router:10000" },
+        },
+      },
+    ],
+  });
+  const t = getTransportConfigForRobot(cfg, "field");
+  assert.equal(t.mode, "zenoh");
+  if (t.mode === "zenoh") {
+    assert.equal(t.zenoh.routerEndpoint, "ws://field-router:10000", "override wins per-field");
+    assert.equal(t.zenoh.domainId, 3, "non-overridden fields inherit from global");
+  }
+});
+
+test("transport-override: legacy single-robot config still returns the global transport", () => {
+  // Backwards compat: when robots[] is empty, there's no override
+  // possible — fast path returns the global transport unmodified.
+  const cfg = parseConfig({
+    transport: { mode: "rosbridge" },
+    rosbridge: { url: "ws://default:9090" },
+    robot: { namespace: "legacy" },
+  });
+  const t = getTransportConfigForRobot(cfg, "legacy");
+  assert.equal(t.mode, "rosbridge");
+  if (t.mode === "rosbridge") {
+    assert.equal(t.rosbridge.url, "ws://default:9090");
+  }
+});
+
+test("transport-override: getTransportConfigForRobot() without id uses the active robot", () => {
+  const cfg = parseConfig({
+    transport: { mode: "local" },
+    robots: [
+      { id: "alpha", namespace: "alpha" },
+      {
+        id: "beta",
+        namespace: "beta",
+        default: true,
+        transport: { mode: "zenoh", zenoh: { routerEndpoint: "ws://beta:10000" } },
+      },
+    ],
+  });
+  const t = getTransportConfigForRobot(cfg); // no id ⇒ active = beta
+  assert.equal(t.mode, "zenoh");
+});
+
+test("transport-override: getTransportConfigForRobot throws on unknown robot_id (same contract as resolveRobot)", () => {
+  const cfg = parseConfig({
+    robots: [{ id: "alpha", namespace: "alpha" }],
+  });
+  assert.throws(
+    () => getTransportConfigForRobot(cfg, "gamma"),
+    /Unknown robot_id "gamma"/,
+  );
+});
+
+test("transport-override: hasRobotTransportOverride() reflects presence", () => {
+  const cfg = parseConfig({
+    robots: [
+      { id: "alpha", namespace: "alpha" },
+      {
+        id: "beta",
+        namespace: "beta",
+        transport: { mode: "local" },
+      },
+    ],
+  });
+  assert.equal(hasRobotTransportOverride(cfg, "alpha"), false);
+  assert.equal(hasRobotTransportOverride(cfg, "beta"), true);
+});
+
+test("transport-override: hasRobotTransportOverride() returns false (not throws) for unknown ids", () => {
+  // Robust against arbitrary tool args — adapters often want a cheap
+  // "should I take the pool path?" check before validating robot ids.
+  const cfg = parseConfig({
+    robots: [{ id: "alpha", namespace: "alpha" }],
+  });
+  assert.equal(hasRobotTransportOverride(cfg, "no-such"), false);
+});
+
+test("transport-override: ResolvedRobot is unchanged by overrides (transport is read via the helper, not the resolved record)", () => {
+  // Intentional design choice — ResolvedRobot stays lean. Tools that
+  // care about transport call getTransportConfigForRobot explicitly.
+  // This test guards that surface from accidental coupling.
+  const cfg = parseConfig({
+    robots: [
+      {
+        id: "sim",
+        namespace: "sim",
+        transport: { mode: "local", local: { domainId: 7 } },
+      },
+    ],
+  });
+  const r = resolveRobot(cfg, "sim");
+  assert.equal(r.id, "sim");
+  assert.equal((r as ResolvedRobot & { transport?: unknown }).transport, undefined);
+});