agenticros 0.3.4 → 0.4.0

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

@@ -0,0 +1,178 @@
+/**
+ * Discoverable marketplace capabilities — list verbs from skills.agenticros.com
+ * that are not yet installed locally, so agents can propose installs.
+ */
+
+import type { AgenticROSConfig } from "./config.js";
+import {
+  listAllCapabilities,
+  type Capability,
+  type CapabilityField,
+  type CapabilitySource,
+} from "./capabilities.js";
+import { skillsApiBase } from "./skill-refs.js";
+
+export interface DiscoverableCapability extends Capability {
+  /** Always true for marketplace-only entries. */
+  discoverable: true;
+  /** False when not present in the local registry. */
+  installed: false;
+  /** Marketplace install ref (owner/skill). */
+  install_ref: string;
+}
+
+export interface ListedCapability extends Capability {
+  discoverable?: boolean;
+  installed?: boolean;
+  install_ref?: string;
+}
+
+export interface ListCapabilitiesOptions {
+  /** Include marketplace browse (network). Default true. */
+  includeDiscoverable?: boolean;
+  apiBase?: string;
+  /** Max marketplace skills to scan. Default 50. */
+  marketplaceLimit?: number;
+  /** Soft-fail: on network error return installed-only. Default true. */
+  softFail?: boolean;
+}
+
+interface MarketplaceSkillDoc {
+  marketplaceRef?: string;
+  ownerLogin?: string;
+  skillSlug?: string;
+  slug?: string;
+  capabilities?: Array<Record<string, unknown>>;
+  visibility?: string;
+}
+
+function installRefOf(s: MarketplaceSkillDoc): string | null {
+  if (s.marketplaceRef && typeof s.marketplaceRef === "string") {
+    return s.marketplaceRef.toLowerCase();
+  }
+  if (s.ownerLogin && s.skillSlug) {
+    return `${s.ownerLogin}/${s.skillSlug}`.toLowerCase();
+  }
+  if (s.slug && s.slug.includes("/")) return s.slug.toLowerCase();
+  return null;
+}
+
+function fieldMap(
+  raw: unknown,
+): Record<string, CapabilityField> | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const out: Record<string, CapabilityField> = {};
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof v === "string") {
+      out[k] = { type: v };
+    } else if (v && typeof v === "object") {
+      const o = v as Record<string, unknown>;
+      out[k] = {
+        type: typeof o.type === "string" ? o.type : "unknown",
+        description: typeof o.description === "string" ? o.description : undefined,
+        optional: o.optional === true,
+      };
+    }
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function normalizeMarketplaceCap(
+  raw: Record<string, unknown>,
+  installRef: string,
+  packageName: string,
+): DiscoverableCapability | null {
+  const id = typeof raw.id === "string" ? raw.id : null;
+  const verb = typeof raw.verb === "string" ? raw.verb : null;
+  const description =
+    typeof raw.description === "string" ? raw.description : id ? `Marketplace capability ${id}` : null;
+  if (!id || !verb || !description) return null;
+  const source: CapabilitySource = {
+    kind: "skill",
+    skillId: installRef.split("/")[1] ?? installRef,
+    package: packageName,
+  };
+  return {
+    id,
+    verb,
+    description,
+    inputs: fieldMap(raw.inputs),
+    outputs: fieldMap(raw.outputs),
+    interruptible: raw.interruptible === true ? true : raw.interruptible === false ? false : undefined,
+    blocks_base: raw.blocks_base === true ? true : undefined,
+    source,
+    discoverable: true,
+    installed: false,
+    install_ref: installRef,
+  };
+}
+
+export async function fetchMarketplaceSkills(
+  opts: { apiBase?: string; limit?: number } = {},
+): Promise<MarketplaceSkillDoc[]> {
+  const base = skillsApiBase(opts.apiBase);
+  const limit = opts.limit ?? 50;
+  const u = new URL(`${base}/skills`);
+  u.searchParams.set("limit", String(limit));
+  u.searchParams.set("sort", "popular");
+  const res = await fetch(u.toString(), { headers: { Accept: "application/json" } });
+  if (!res.ok) {
+    throw new Error(`Marketplace list ${res.status}`);
+  }
+  const body = (await res.json()) as { skills?: MarketplaceSkillDoc[] };
+  return body.skills ?? [];
+}
+
+/**
+ * Merge installed capabilities with discoverable marketplace capabilities
+ * (ids not already present locally). Soft-fails offline.
+ */
+export async function listCapabilitiesWithDiscoverable(
+  config: AgenticROSConfig,
+  opts: ListCapabilitiesOptions = {},
+): Promise<ListedCapability[]> {
+  const installed = listAllCapabilities(config).map((c) => {
+    const listed: ListedCapability = {
+      ...c,
+      installed: true,
+      discoverable: false,
+    };
+    return listed;
+  });
+  if (opts.includeDiscoverable === false) {
+    return installed;
+  }
+
+  const installedIds = new Set(installed.map((c) => c.id));
+  try {
+    const skills = await fetchMarketplaceSkills({
+      apiBase: opts.apiBase,
+      limit: opts.marketplaceLimit ?? 50,
+    });
+    const extra: DiscoverableCapability[] = [];
+    const seenDiscoverable = new Set<string>();
+    for (const s of skills) {
+      if (s.visibility && s.visibility !== "public") continue;
+      const ref = installRefOf(s);
+      if (!ref) continue;
+      const caps = Array.isArray(s.capabilities) ? s.capabilities : [];
+      for (const raw of caps) {
+        if (!raw || typeof raw !== "object") continue;
+        const id = typeof (raw as { id?: unknown }).id === "string" ? (raw as { id: string }).id : null;
+        if (!id || installedIds.has(id) || seenDiscoverable.has(id)) continue;
+        const norm = normalizeMarketplaceCap(
+          raw as Record<string, unknown>,
+          ref,
+          s.slug ?? ref,
+        );
+        if (!norm) continue;
+        seenDiscoverable.add(id);
+        extra.push(norm);
+      }
+    }
+    return [...installed, ...extra];
+  } catch (e) {
+    if (opts.softFail === false) throw e;
+    return installed;
+  }
+}

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

@@ -102,9 +102,13 @@ export function effectiveCmdVelNamespace(robotNamespace: string): string {
 /**
  * Find every robot-shaped namespace in a topic list.
  *
- * Detection rule: any `/<seg>/cmd_vel` topic implies a robot with
- * namespace `<seg>`. The unnamespaced `/cmd_vel` topic registers the
- * empty namespace (id=""). Topic count under each namespace is
+ * Detection rules (either is enough):
+ *   1. `/<seg>/cmd_vel` — classic mobile-base signal
+ *   2. `/<seg>/agenticros/robot_info` — Phase 1.d heartbeat (arms/drones
+ *      without cmd_vel still show up)
+ *
+ * The unnamespaced `/cmd_vel` / `/agenticros/robot_info` topics register
+ * the empty namespace (id=""). Topic count under each namespace is
  * accumulated so consumers can rank by liveness.
  *
  * The returned `DetectedRobot.configuredRobotId` is always `null` here —
@@ -124,6 +128,20 @@ export function detectRobotsFromTopics(topics: TopicInfo[]): DetectedRobot[] {
     } else if (t.name === "/cmd_vel" && !byNs.has("")) {
       byNs.set("", { cmdVelTopic: "/cmd_vel", topicCount: 0 });
     }
+
+    // Heartbeat topic — covers robots that don't publish cmd_vel.
+    const hb = t.name.match(/^\/([^/]+)\/agenticros\/robot_info$/);
+    if (hb) {
+      const ns = hb[1]!;
+      if (!byNs.has(ns)) {
+        byNs.set(ns, { cmdVelTopic: `/${ns}/cmd_vel`, topicCount: 0 });
+      }
+    } else if (
+      (t.name === "/agenticros/robot_info" || t.name === "agenticros/robot_info") &&
+      !byNs.has("")
+    ) {
+      byNs.set("", { cmdVelTopic: "/cmd_vel", topicCount: 0 });
+    }
   }
 
   // Count topics under each detected namespace. Empty-namespace robots

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

@@ -0,0 +1,232 @@
+/**
+ * External ROS-node capability executor — Phase 1 completion.
+ *
+ * Dispatches `implementation.kind: "external_ros_node"` capabilities via
+ * the existing RosTransport action / service / topic APIs. The manifest
+ * `launch` field is metadata only (operator-owned bringup) — the gateway
+ * never shells out to `ros2 launch` in v1.
+ */
+
+import type { Capability, CapabilityImplementation } from "./capabilities.js";
+import type { RosTransport } from "./transport/transport.js";
+import { toNamespacedTopic } from "./topic-utils.js";
+
+export interface ExecuteExternalOptions {
+  /** Robot namespace for topic/action/service prefixing. */
+  namespace?: string;
+  /** Optional timeout for subscribe_once (ms). */
+  timeoutMs?: number;
+}
+
+export interface ExecuteExternalResult {
+  text: string;
+  outputs?: Record<string, unknown>;
+  isError?: boolean;
+}
+
+function isExternalImpl(
+  impl: CapabilityImplementation | undefined,
+): impl is Extract<CapabilityImplementation, { kind: "external_ros_node" }> {
+  return impl?.kind === "external_ros_node";
+}
+
+function resolveName(name: string, namespace?: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) return trimmed;
+  if (!namespace?.trim()) return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return toNamespacedTopic(namespace, trimmed);
+}
+
+/**
+ * Map navigate_to-style inputs into a Nav2 NavigateToPose goal when the
+ * action type looks like NavigateToPose and inputs have x/y.
+ */
+export function buildExternalGoal(
+  impl: Extract<CapabilityImplementation, { kind: "external_ros_node" }>,
+  inputs: Record<string, unknown>,
+): Record<string, unknown> {
+  // Explicit goal / request / message wins.
+  if (inputs.goal && typeof inputs.goal === "object") {
+    return inputs.goal as Record<string, unknown>;
+  }
+  if (inputs.request && typeof inputs.request === "object") {
+    return inputs.request as Record<string, unknown>;
+  }
+  if (inputs.message && typeof inputs.message === "object") {
+    return inputs.message as Record<string, unknown>;
+  }
+
+  const msgType = (impl.msg_type ?? "").toLowerCase();
+  if (msgType.includes("navigatetopose") || impl.action?.includes("navigate_to_pose")) {
+    const x = Number(inputs.x ?? 0) || 0;
+    const y = Number(inputs.y ?? 0) || 0;
+    const yaw = Number(inputs.yaw ?? 0) || 0;
+    const qz = Math.sin(yaw / 2);
+    const qw = Math.cos(yaw / 2);
+    const frame = typeof inputs.frame_id === "string" ? inputs.frame_id : "map";
+    return {
+      pose: {
+        header: { frame_id: frame },
+        pose: {
+          position: { x, y, z: 0 },
+          orientation: { x: 0, y: 0, z: qz, w: qw },
+        },
+      },
+    };
+  }
+
+  // Passthrough remaining inputs (minus robot_id).
+  const { robot_id: _rid, ...rest } = inputs;
+  return rest;
+}
+
+/**
+ * Execute an external_ros_node capability against a connected transport.
+ */
+export async function executeExternalCapability(
+  capability: Capability,
+  inputs: Record<string, unknown>,
+  transport: RosTransport,
+  options: ExecuteExternalOptions = {},
+): Promise<ExecuteExternalResult> {
+  const impl = capability.implementation;
+  if (!isExternalImpl(impl)) {
+    return {
+      text: `Capability "${capability.id}" is not an external_ros_node implementation.`,
+      isError: true,
+    };
+  }
+
+  const ns = options.namespace;
+
+  try {
+    if (impl.action) {
+      const action = resolveName(impl.action, ns);
+      const actionType = impl.msg_type ?? "";
+      if (!actionType) {
+        return {
+          text: `Capability "${capability.id}" external action requires implementation.msg_type.`,
+          isError: true,
+        };
+      }
+      const args = buildExternalGoal(impl, inputs);
+      const result = await transport.sendActionGoal({
+        action,
+        actionType,
+        args,
+      });
+      const outputs = {
+        success: result.result,
+        ...(result.values ?? {}),
+        launch_hint: impl.launch ?? null,
+        package_hint: impl.package ?? null,
+      };
+      return {
+        text: JSON.stringify(outputs),
+        outputs,
+        isError: !result.result,
+      };
+    }
+
+    if (impl.service) {
+      const service = resolveName(impl.service, ns);
+      const serviceType = impl.msg_type ?? "";
+      if (!serviceType) {
+        return {
+          text: `Capability "${capability.id}" external service requires implementation.msg_type.`,
+          isError: true,
+        };
+      }
+      const args = buildExternalGoal(impl, inputs);
+      const result = await transport.callService({
+        service,
+        type: serviceType,
+        args,
+      });
+      const outputs = {
+        success: result.result,
+        ...(result.values ?? {}),
+        launch_hint: impl.launch ?? null,
+      };
+      return {
+        text: JSON.stringify(outputs),
+        outputs,
+        isError: !result.result,
+      };
+    }
+
+    if (impl.topic) {
+      const topicName =
+        typeof inputs.topic === "string" && inputs.topic.trim()
+          ? inputs.topic.trim()
+          : impl.topic;
+      const topic = resolveName(topicName, ns);
+      const msgType = impl.msg_type ?? "";
+      // Detection / sensor skills default to subscribe_once; publishers must pass mode: "publish".
+      const mode =
+        typeof inputs.mode === "string"
+          ? inputs.mode
+          : "subscribe";
+      if (mode === "subscribe" || mode === "subscribe_once") {
+        const timeout =
+          options.timeoutMs ??
+          (typeof inputs.timeout_ms === "number"
+            ? inputs.timeout_ms
+            : typeof inputs.timeout === "number"
+              ? inputs.timeout
+              : 5000);
+        const msg = await new Promise<Record<string, unknown>>((resolve, reject) => {
+          let settled = false;
+          const timer = setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            try {
+              sub.unsubscribe();
+            } catch {
+              /* ignore */
+            }
+            reject(new Error(`Timed out waiting for message on ${topic} after ${timeout}ms`));
+          }, timeout);
+          const sub = transport.subscribe(
+            { topic, type: msgType || "std_msgs/msg/String" },
+            (message) => {
+              if (settled) return;
+              settled = true;
+              clearTimeout(timer);
+              try {
+                sub.unsubscribe();
+              } catch {
+                /* ignore */
+              }
+              resolve(message as Record<string, unknown>);
+            },
+          );
+        });
+        const outputs = { message: msg, topic };
+        return { text: JSON.stringify(outputs), outputs };
+      }
+      if (!msgType) {
+        return {
+          text: `Capability "${capability.id}" external topic publish requires implementation.msg_type.`,
+          isError: true,
+        };
+      }
+      const message = buildExternalGoal(impl, inputs);
+      await transport.publish({ topic, type: msgType, msg: message });
+      const outputs = { published: true, topic, launch_hint: impl.launch ?? null };
+      return { text: JSON.stringify(outputs), outputs };
+    }
+
+    return {
+      text:
+        `Capability "${capability.id}" external_ros_node has no action, service, or topic. ` +
+        `Bringup hint: ${impl.launch ?? impl.package ?? "(none)"}.`,
+      isError: true,
+    };
+  } catch (err) {
+    return {
+      text: err instanceof Error ? err.message : String(err),
+      isError: true,
+    };
+  }
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Static fleet file — Phase 1.d hybrid discovery.
+ *
+ * Precedence: `AGENTICROS_FLEET_PATH` → `~/.agenticros/fleet.json` →
+ * `config.robots[]` (via listRobots). When a fleet file exists and
+ * parses as a non-empty robot array (or `{ robots: [...] }`), it wins.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AgenticROSConfig } from "./config.js";
+import { AgenticROSConfigSchema } from "./config.js";
+
+export const DEFAULT_FLEET_FILENAME = "fleet.json";
+
+/** Resolve the fleet file path (env override or default under ~/.agenticros). */
+export function resolveFleetPath(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.AGENTICROS_FLEET_PATH?.trim();
+  if (override) return override;
+  return join(homedir(), ".agenticros", DEFAULT_FLEET_FILENAME);
+}
+
+export interface FleetFileResult {
+  /** Absolute path that was checked. */
+  path: string;
+  /** True when the file exists and was used. */
+  used: boolean;
+  /** Parsed robot entries (empty when unused / invalid). */
+  robots: NonNullable<AgenticROSConfig["robots"]>;
+  /** Human-readable error when the file exists but failed to parse. */
+  error?: string;
+}
+
+/**
+ * Load `fleet.json` if present. Does not throw on missing file.
+ * Invalid JSON / schema → `used: false` with `error` set so callers can warn.
+ */
+export function loadFleetFile(path?: string): FleetFileResult {
+  const fleetPath = path ?? resolveFleetPath();
+  if (!existsSync(fleetPath)) {
+    return { path: fleetPath, used: false, robots: [] };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(fleetPath, "utf8")) as unknown;
+    let robotsRaw: unknown;
+    if (Array.isArray(raw)) {
+      robotsRaw = raw;
+    } else if (raw && typeof raw === "object" && Array.isArray((raw as { robots?: unknown }).robots)) {
+      robotsRaw = (raw as { robots: unknown[] }).robots;
+    } else {
+      return {
+        path: fleetPath,
+        used: false,
+        robots: [],
+        error: "fleet.json must be an array of robots or { robots: [...] }",
+      };
+    }
+    const parsed = AgenticROSConfigSchema.pick({ robots: true }).safeParse({ robots: robotsRaw });
+    if (!parsed.success) {
+      return {
+        path: fleetPath,
+        used: false,
+        robots: [],
+        error: parsed.error.message,
+      };
+    }
+    const robots = parsed.data.robots ?? [];
+    if (robots.length === 0) {
+      return { path: fleetPath, used: false, robots: [] };
+    }
+    return { path: fleetPath, used: true, robots };
+  } catch (err) {
+    return {
+      path: fleetPath,
+      used: false,
+      robots: [],
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Return a config view where `robots` comes from fleet.json when present.
+ * Does not mutate the input config object.
+ */
+export function applyFleetOverride(config: AgenticROSConfig, fleetPath?: string): AgenticROSConfig {
+  const fleet = loadFleetFile(fleetPath);
+  if (!fleet.used) return config;
+  return { ...config, robots: fleet.robots };
+}