agenticros 0.1.18 → 0.2.0

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

@@ -0,0 +1,314 @@
+/**
+ * Capability registry — Phase 1.a/1.b of the AgenticROS strategy.
+ *
+ * A capability is a named, declarable verb an LLM can plan against
+ * (`follow_person`, `find_object`, `take_snapshot`, `drive_base`).
+ * It's deliberately shaped to match inter-agent protocol agent cards
+ * (ACP / A2A) so a skill's capability today is readable as an agent
+ * capability when Phase 4 lands — no rewrite required.
+ *
+ * Two kinds of capabilities:
+ *  - **Intrinsic** — built into every AgenticROS deployment (drive_base,
+ *    take_snapshot, measure_depth, list_topics, publish, subscribe). Lives
+ *    in this file as `BUILTIN_CAPABILITIES`.
+ *  - **Skill-declared** — comes from a skill package's `package.json`
+ *    under `agenticrosSkill.capabilities[]` (or a sibling
+ *    `capabilities.json`). Read at adapter startup.
+ *
+ * See: docs/strategy-ai-agents-plus-ros.md §4 (Phase 1).
+ */
+
+import { createRequire } from "node:module";
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import type { AgenticROSConfig } from "./config.js";
+
+/** Where a capability came from. */
+export type CapabilitySource =
+  | { kind: "builtin" }
+  | { kind: "skill"; skillId: string; package: string; path?: string };
+
+/** Implementation hint — in-process Node.js skill vs external ROS node. */
+export type CapabilityImplementation =
+  | { kind: "in_process" }
+  | {
+      kind: "external_ros_node";
+      package?: string;
+      launch?: string;
+      action?: string;
+      service?: string;
+      topic?: string;
+      msg_type?: string;
+    };
+
+/** Typed input/output schema — minimal, JSON-Schema-ish. */
+export interface CapabilityField {
+  type: string;
+  description?: string;
+  optional?: boolean;
+  default?: unknown;
+}
+
+/**
+ * One capability the agent can plan against.
+ *
+ * Required: `id`, `verb`, `description`.
+ * Everything else is optional so a skill can adopt the manifest
+ * incrementally.
+ */
+export interface Capability {
+  /** Unique identifier within a robot (e.g. `follow_person`, `find_object`). */
+  id: string;
+  /** High-level verb (`follow`, `find`, `navigate`, `manipulate`, `map`, `detect`). */
+  verb: string;
+  /** One-line, human-readable description. */
+  description: string;
+  /** Optional structured inputs the agent can fill. */
+  inputs?: Record<string, CapabilityField>;
+  /** Optional structured outputs the skill emits. */
+  outputs?: Record<string, CapabilityField>;
+  /** Free-form preconditions ("depthTopic available", "person detected"). */
+  preconditions?: string[];
+  /** Can be canceled mid-execution? Default true for intrinsic, varies for skills. */
+  interruptible?: boolean;
+  /** Owns the robot base (cmd_vel); other base-owning skills should yield. */
+  blocks_base?: boolean;
+  /** How the capability is implemented. Defaults to `in_process` when unset. */
+  implementation?: CapabilityImplementation;
+  /** Set by the registry, not the skill author. */
+  source?: CapabilitySource;
+}
+
+/**
+ * Built-in robot verbs — wrap the raw MCP tools in agent-meaningful
+ * capability names. The intrinsic set is intentionally small and stable
+ * so the agent's planning surface stays understandable as skill catalogs
+ * grow.
+ */
+export const BUILTIN_CAPABILITIES: readonly Capability[] = [
+  {
+    id: "drive_base",
+    verb: "drive",
+    description:
+      "Drive the robot base by publishing geometry_msgs/Twist to the configured cmd_vel topic. " +
+      "Linear/angular velocities are clamped server-side by safety.maxLinearVelocity / maxAngularVelocity.",
+    inputs: {
+      linear_x: { type: "number", description: "Forward velocity (m/s).", optional: true },
+      angular_z: { type: "number", description: "Yaw velocity (rad/s).", optional: true },
+    },
+    interruptible: true,
+    blocks_base: true,
+    source: { kind: "builtin" },
+  },
+  {
+    id: "take_snapshot",
+    verb: "see",
+    description:
+      "Capture one frame from the configured camera topic. Returns base64-encoded JPEG/PNG.",
+    inputs: {
+      topic: { type: "string", description: "Camera topic (defaults to robot.cameraTopic).", optional: true },
+    },
+    outputs: {
+      format: { type: "string", description: "Image format (jpeg / png)." },
+      width: { type: "number", description: "Image width in pixels." },
+      height: { type: "number", description: "Image height in pixels." },
+    },
+    interruptible: true,
+    source: { kind: "builtin" },
+  },
+  {
+    id: "measure_depth",
+    verb: "measure",
+    description:
+      "Sample the center of a depth image and return a distance in meters. " +
+      "Use to answer 'how far am I from X' style questions.",
+    inputs: {
+      topic: { type: "string", description: "Depth topic.", optional: true },
+    },
+    outputs: {
+      distance_m: { type: "number", description: "Distance in meters at image center." },
+      median_m: { type: "number", description: "Median distance across sampled pixels." },
+    },
+    interruptible: true,
+    source: { kind: "builtin" },
+  },
+  {
+    id: "list_topics",
+    verb: "introspect",
+    description:
+      "List all reachable ROS 2 topics with their message types. Use for discovery when " +
+      "no other capability fits or to confirm what the robot currently publishes.",
+    interruptible: true,
+    source: { kind: "builtin" },
+  },
+  {
+    id: "publish_topic",
+    verb: "publish",
+    description:
+      "Generic ROS 2 publish escape hatch. Prefer a named capability when one exists; " +
+      "publishes are safety-checked but otherwise unmediated.",
+    inputs: {
+      topic: { type: "string", description: "ROS 2 topic name." },
+      type: { type: "string", description: "ROS 2 message type (e.g. geometry_msgs/msg/Twist)." },
+      message: { type: "object", description: "Message payload matching the type schema." },
+    },
+    interruptible: true,
+    source: { kind: "builtin" },
+  },
+  {
+    id: "subscribe_once",
+    verb: "read",
+    description: "Read one message from a ROS 2 topic. Use for one-shot sensor reads or state checks.",
+    inputs: {
+      topic: { type: "string", description: "ROS 2 topic name." },
+      type: { type: "string", description: "ROS 2 message type (optional, often inferred).", optional: true },
+      timeout: { type: "number", description: "Milliseconds to wait (default 5000).", optional: true },
+    },
+    interruptible: true,
+    source: { kind: "builtin" },
+  },
+];
+
+function isCapabilityLike(value: unknown): value is Partial<Capability> & { id: string } {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.id === "string" && v.id.length > 0;
+}
+
+function normalizeCapability(
+  raw: Partial<Capability> & { id: string },
+  source: CapabilitySource,
+): Capability {
+  return {
+    id: raw.id,
+    verb: typeof raw.verb === "string" && raw.verb ? raw.verb : raw.id,
+    description: typeof raw.description === "string" ? raw.description : "",
+    ...(raw.inputs ? { inputs: raw.inputs } : {}),
+    ...(raw.outputs ? { outputs: raw.outputs } : {}),
+    ...(raw.preconditions ? { preconditions: raw.preconditions } : {}),
+    ...(typeof raw.interruptible === "boolean" ? { interruptible: raw.interruptible } : {}),
+    ...(typeof raw.blocks_base === "boolean" ? { blocks_base: raw.blocks_base } : {}),
+    ...(raw.implementation ? { implementation: raw.implementation } : { implementation: { kind: "in_process" } }),
+    source,
+  };
+}
+
+/**
+ * Read the `agenticros.capabilities[]` array from a skill's package.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.
+ */
+function readSkillManifestFromDir(
+  packageDir: string,
+): { packageName: string; skillId: string; rawCaps: Array<Partial<Capability> & { id: string }> } | null {
+  const pkgJsonPath = join(packageDir, "package.json");
+  if (!existsSync(pkgJsonPath)) return null;
+  let pkg: {
+    name?: string;
+    agenticros?: { id?: unknown; capabilities?: unknown };
+  };
+  try {
+    pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+  } catch {
+    return null;
+  }
+  if (!pkg.agenticros || typeof pkg.agenticros !== "object") return null;
+  if (typeof pkg.agenticros.id !== "string") return null;
+
+  const packageName = pkg.name ?? "unknown";
+  const skillId = pkg.agenticros.id;
+  const rawCaps: Array<Partial<Capability> & { id: string }> = [];
+
+  const caps = pkg.agenticros.capabilities;
+  if (Array.isArray(caps)) {
+    for (const c of caps) if (isCapabilityLike(c)) rawCaps.push(c);
+  }
+
+  return { packageName, skillId, rawCaps };
+}
+
+function resolvePackageDir(packageName: string, searchPaths: string[]): string | null {
+  const req = createRequire(import.meta.url);
+  for (const base of [...searchPaths, process.cwd()]) {
+    try {
+      const entry = req.resolve(`${packageName}/package.json`, { paths: [base] });
+      return entry.replace(/\/package\.json$/, "");
+    } catch {
+    }
+  }
+  try {
+    const entry = req.resolve(`${packageName}/package.json`);
+    return entry.replace(/\/package\.json$/, "");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read every capability declared by every skill referenced in `config`.
+ * Sources both `skillPaths` (directories with a package.json) and
+ * `skillPackages` (resolvable npm names).
+ *
+ * Failures are silent — a missing skill is logged elsewhere by the
+ * skill loader; this function focuses on returning the capabilities
+ * it can read.
+ */
+export function readSkillCapabilities(config: AgenticROSConfig): Capability[] {
+  const out: Capability[] = [];
+  const seen = new Set<string>();
+
+  const skillPaths = config.skillPaths ?? [];
+  const skillPackages = config.skillPackages ?? [];
+
+  for (const dir of skillPaths) {
+    const absDir = resolvePath(dir);
+    const manifest = readSkillManifestFromDir(absDir);
+    if (!manifest) continue;
+    for (const raw of manifest.rawCaps) {
+      const key = `${manifest.skillId}:${raw.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(
+        normalizeCapability(raw, {
+          kind: "skill",
+          skillId: manifest.skillId,
+          package: manifest.packageName,
+          path: absDir,
+        }),
+      );
+    }
+  }
+
+  for (const pkgName of skillPackages) {
+    const packageDir = resolvePackageDir(pkgName, skillPaths.map((p) => resolvePath(p)));
+    if (!packageDir) continue;
+    const manifest = readSkillManifestFromDir(packageDir);
+    if (!manifest) continue;
+    for (const raw of manifest.rawCaps) {
+      const key = `${manifest.skillId}:${raw.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(
+        normalizeCapability(raw, {
+          kind: "skill",
+          skillId: manifest.skillId,
+          package: manifest.packageName,
+          path: packageDir,
+        }),
+      );
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Return the full capability list: built-in robot verbs first, then
+ * skill-declared capabilities. This is the shape returned by
+ * `ros2_list_capabilities` across every adapter.
+ */
+export function listAllCapabilities(config: AgenticROSConfig): Capability[] {
+  return [...BUILTIN_CAPABILITIES, ...readSkillCapabilities(config)];
+}

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

@@ -7,6 +7,130 @@ const IceServerSchema = z.object({
   credential: z.string().optional(),
 });
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Transport sub-schemas. Extracted so both the top-level config and the
+// per-robot override in `robots[i].transport` can share them without
+// drifting. The shapes mirror packages/core/src/transport/types.ts.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ZenohSettingsSchema = z.object({
+  /** WebSocket URL for zenoh-ts (zenoh-plugin-remote-api). Not tcp/ — use e.g. ws://localhost:10000 */
+  routerEndpoint: z.string().default("ws://localhost:10000"),
+  domainId: z.number().default(0),
+  /** "ros2dds" = zenoh-bridge-ros2dds key format (slashes kept). "rmw_zenoh" = rmw_zenoh key format (domain + %). */
+  keyFormat: z.enum(["ros2dds", "rmw_zenoh"]).default("ros2dds"),
+  /**
+   * Must match zenoh-bridge-ros2dds `plugins.ros2dds.namespace` when it is not the default "/".
+   * Example: bridge has `namespace: "/bot1"` → set `bridgeNamespace` to "/bot1" or "bot1".
+   * Omit or use "/" when the bridge uses the default (only the ROS topic path is the zenoh key).
+   */
+  bridgeNamespace: z.string().optional(),
+});
+
+const RosbridgeSettingsSchema = z.object({
+  url: z.string().default("ws://localhost:9090"),
+  reconnect: z.boolean().default(true),
+  reconnectInterval: z.number().default(3000),
+});
+
+const LocalSettingsSchema = z.object({
+  domainId: z.number().default(0),
+});
+
+const WebrtcSettingsSchema = z.object({
+  signalingUrl: z.string().default(""),
+  apiUrl: z.string().default(""),
+  robotId: z.string().default(""),
+  robotKey: z.string().default(""),
+  iceServers: z
+    .array(IceServerSchema)
+    .default([{ urls: "stun:stun.l.google.com:19302" }]),
+});
+
+/**
+ * Per-robot transport override sub-schemas (Phase 1.d-resolve).
+ *
+ * These intentionally MIRROR the top-level shapes but drop every
+ * `.default(...)`. Why: when `getTransportConfigForRobot` merges an
+ * override over the global config it does a per-field merge
+ * (`{ ...global, ...override }`). If the override schema applied
+ * defaults (e.g. `domainId: 0`), those defaults would silently clobber
+ * the global values whenever the user omitted them — making the
+ * "merge only the fields I actually wrote" contract impossible.
+ *
+ * Every field is optional here. Validation still rejects wrong types
+ * (e.g. `routerEndpoint: 42`), which is what we want.
+ */
+const ZenohOverrideSettingsSchema = z.object({
+  routerEndpoint: z.string().optional(),
+  domainId: z.number().optional(),
+  keyFormat: z.enum(["ros2dds", "rmw_zenoh"]).optional(),
+  bridgeNamespace: z.string().optional(),
+});
+
+const RosbridgeOverrideSettingsSchema = z.object({
+  url: z.string().optional(),
+  reconnect: z.boolean().optional(),
+  reconnectInterval: z.number().optional(),
+});
+
+const LocalOverrideSettingsSchema = z.object({
+  domainId: z.number().optional(),
+});
+
+const WebrtcOverrideSettingsSchema = z.object({
+  signalingUrl: z.string().optional(),
+  apiUrl: z.string().optional(),
+  robotId: z.string().optional(),
+  robotKey: z.string().optional(),
+  iceServers: z.array(IceServerSchema).optional(),
+});
+
+/**
+ * Per-robot transport override schema (Phase 1.d-resolve).
+ *
+ * Discriminated union on `mode`, each variant `.strict()` so that a
+ * typo like `{ mode: "zenoh", local: {...} }` fails fast at parse time
+ * instead of being silently stripped. Sub-sections are optional —
+ * `{ mode: "zenoh" }` is a valid override that inherits everything
+ * from the top-level `config.zenoh`. A partial sub-section like
+ * `{ mode: "zenoh", zenoh: { routerEndpoint: "ws://field:10000" } }`
+ * is merged per-field over the global config — see the resolver.
+ *
+ * Why a discriminated union (vs the top-level shape of sibling fields):
+ *   - Keeps the override self-contained at one JSON property
+ *   - Matches TransportConfig's runtime discriminated union 1:1
+ *   - Trivially validatable per-robot without leaking across siblings
+ */
+const RobotTransportOverrideSchema = z.discriminatedUnion("mode", [
+  z
+    .object({
+      mode: z.literal("rosbridge"),
+      rosbridge: RosbridgeOverrideSettingsSchema.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("local"),
+      local: LocalOverrideSettingsSchema.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("zenoh"),
+      zenoh: ZenohOverrideSettingsSchema.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("webrtc"),
+      webrtc: WebrtcOverrideSettingsSchema.optional(),
+    })
+    .strict(),
+]);
+
+export type RobotTransportOverride = z.infer<typeof RobotTransportOverrideSchema>;
+
 export const AgenticROSConfigSchema = z.object({
   transport: z
     .object({
@@ -19,47 +143,13 @@ export const AgenticROSConfigSchema = z.object({
     })
     .default({}),
 
-  zenoh: z
-    .object({
-      /** WebSocket URL for zenoh-ts (zenoh-plugin-remote-api). Not tcp/ — use e.g. ws://localhost:10000 */
-      routerEndpoint: z.string().default("ws://localhost:10000"),
-      domainId: z.number().default(0),
-      /** "ros2dds" = zenoh-bridge-ros2dds key format (slashes kept). "rmw_zenoh" = rmw_zenoh key format (domain + %). */
-      keyFormat: z.enum(["ros2dds", "rmw_zenoh"]).default("ros2dds"),
-      /**
-       * Must match zenoh-bridge-ros2dds `plugins.ros2dds.namespace` when it is not the default "/".
-       * Example: bridge has `namespace: "/bot1"` → set `bridgeNamespace` to "/bot1" or "bot1".
-       * Omit or use "/" when the bridge uses the default (only the ROS topic path is the zenoh key).
-       */
-      bridgeNamespace: z.string().optional(),
-    })
-    .default({}),
+  zenoh: ZenohSettingsSchema.default({}),
 
-  rosbridge: z
-    .object({
-      url: z.string().default("ws://localhost:9090"),
-      reconnect: z.boolean().default(true),
-      reconnectInterval: z.number().default(3000),
-    })
-    .default({}),
+  rosbridge: RosbridgeSettingsSchema.default({}),
 
-  local: z
-    .object({
-      domainId: z.number().default(0),
-    })
-    .default({}),
+  local: LocalSettingsSchema.default({}),
 
-  webrtc: z
-    .object({
-      signalingUrl: z.string().default(""),
-      apiUrl: z.string().default(""),
-      robotId: z.string().default(""),
-      robotKey: z.string().default(""),
-      iceServers: z
-        .array(IceServerSchema)
-        .default([{ urls: "stun:stun.l.google.com:19302" }]),
-    })
-    .default({}),
+  webrtc: WebrtcSettingsSchema.default({}),
 
   robot: z
     .object({
@@ -70,6 +160,98 @@ export const AgenticROSConfigSchema = z.object({
     })
     .default({}),
 
+  /**
+   * Phase 1.d multi-robot list. When non-empty, this is the source of
+   * truth for `ros2_list_robots` and (in a follow-up) the per-tool
+   * `robot_id` parameter. When empty, the legacy single-robot
+   * `config.robot` above is synthesised into a one-entry list at
+   * resolution time (see packages/core/src/robots.ts). Existing configs
+   * keep working unchanged; this field is opt-in.
+   *
+   * Mark one entry with `default: true` to make it the active robot
+   * even when it isn't the first in the list. Otherwise the first entry
+   * wins.
+   */
+  robots: z
+    .array(
+      z.object({
+        /** Stable, human-readable identifier referenced by `robot_id` arguments. */
+        id: z.string(),
+        name: z.string().default("Robot"),
+        namespace: z.string().default(""),
+        cameraTopic: z.string().default(""),
+        default: z.boolean().optional(),
+        /**
+         * Phase 1.e robot kind ("amr" | "arm" | "drone" | "rover" | …).
+         *
+         * Free-form string so users can invent their own taxonomy, but the
+         * documented set is `amr` (autonomous mobile robot), `arm`,
+         * `drone`, and `rover`. Consumed by `ros2_find_robots_for(kind=…)`
+         * so an agent can ask "find me an AMR with a depth camera that
+         * can follow_person" and the platform filters the fleet.
+         *
+         * Defaults to "amr" (back-compat: every existing robot today is
+         * an AMR), so the field stays useful even when the user hasn't
+         * tagged their robots explicitly.
+         */
+        kind: z.string().default("amr"),
+        /**
+         * Phase 1.e sensor/hardware tags.
+         *
+         * Lets `ros2_find_robots_for` answer questions like "which
+         * robots have a depth camera" without subscribing to topics or
+         * inspecting the URDF. All flags default to false — set them
+         * explicitly per robot via the CLI (`--sensors=has_realsense`)
+         * or by hand-editing `~/.agenticros/config.json`.
+         *
+         * The list is intentionally short for Phase 1; expand it as we
+         * accumulate seed-catalog skills that depend on a specific
+         * hardware capability (lidar SLAM, arm grasping, etc.).
+         */
+        sensors: z
+          .object({
+            has_realsense: z.boolean().default(false),
+            has_lidar: z.boolean().default(false),
+            has_arm: z.boolean().default(false),
+          })
+          .default({}),
+        /**
+         * Phase 1.e optional per-robot capability allowlist.
+         *
+         * When set, restricts which capabilities `ros2_find_robots_for`
+         * considers this robot capable of. When unset (the common
+         * case), the robot inherits the gateway's global capability
+         * registry (the union of built-in verbs plus every loaded
+         * skill's capabilities). Useful in heterogeneous fleets where
+         * one robot has the arm skill loaded and another doesn't.
+         */
+        capabilities: z.array(z.string()).optional(),
+        /**
+         * Phase 1.d-resolve per-robot transport override.
+         *
+         * When set, this robot uses its own transport instead of the
+         * top-level `config.transport.*`. Useful when one host drives
+         * BOTH a local sim (mode: "local") AND a real robot reached via
+         * an off-robot bridge (mode: "zenoh" / "rosbridge") — each
+         * robot connects through the right path with no global config
+         * juggling.
+         *
+         * Sub-sections (`zenoh`, `rosbridge`, `local`, `webrtc`) are
+         * optional inside the override: omit them to inherit the global
+         * `config.<section>` defaults; set them to override only the
+         * fields you need (e.g. a different router endpoint).
+         *
+         * Consumed by `getTransportConfigForRobot(config, robotId)` in
+         * robots.ts. Adapters opt in to multi-transport pools — when
+         * the override is absent they keep using the single global
+         * transport, so existing single-robot deployments are
+         * unaffected.
+         */
+        transport: RobotTransportOverrideSchema.optional(),
+      }),
+    )
+    .default([]),
+
   /** Phase 3 teleop web app: camera + twist controls. */
   teleop: z
     .object({
@@ -231,7 +413,7 @@ export const AgenticROSConfigSchema = z.object({
   /** Per-skill config. Keys are skill ids (e.g. followme). Each skill validates its own slice. */
   skills: z.record(z.string(), z.unknown()).default({}),
 
-  /** Directories to scan for skill packages (package.json with "agenticrosSkill": true). Resolved at gateway start. */
+  /** Directories to scan for skill packages (package.json with an `agenticros` block). Resolved at gateway start. */
   skillPaths: z.array(z.string()).default([]),
 
   /** Npm (or local) package names to load as skills. Resolved via require.resolve from plugin context. */