agenticros 0.3.5 → 0.4.0

package/runtime/packages/agenticros-gemini/src/config.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import type { AgenticROSConfig } from "@agenticros/core";
-import { parseConfig } from "@agenticros/core";
+import { parseConfig, withResolvedSkillRefs, applyCachedSkillRefs } from "@agenticros/core";
 
 /** Same as Claude Code MCP: optional `robot.namespace` override from the environment. */
 function applyMcpEnvOverrides(config: AgenticROSConfig): AgenticROSConfig {
@@ -17,11 +17,6 @@ function applyMcpEnvOverrides(config: AgenticROSConfig): AgenticROSConfig {
   };
 }
 
-/**
- * Resolve path to AgenticROS config file.
- * Prefer AGENTICROS_CONFIG_PATH; else ~/.agenticros/config.json.
- * Optional: fallback to OpenClaw config and read plugins.entries.agenticros.config.
- */
 function getConfigPath(): string {
   const env = process.env.AGENTICROS_CONFIG_PATH;
   if (env && env.trim().length > 0) {
@@ -30,9 +25,6 @@ function getConfigPath(): string {
   return path.join(os.homedir(), ".agenticros", "config.json");
 }
 
-/**
- * Try to read config from OpenClaw file (plugins.entries.agenticros.config).
- */
 function tryOpenClawConfig(): Record<string, unknown> | null {
   const openclawEnv = process.env.OPENCLAW_CONFIG;
   const openclawPath = openclawEnv && openclawEnv.trim().length > 0
@@ -57,12 +49,7 @@ function tryOpenClawConfig(): Record<string, unknown> | null {
   return null;
 }
 
-/**
- * Load and parse AgenticROS config.
- * 1) AGENTICROS_CONFIG_PATH or ~/.agenticros/config.json (full JSON object = config).
- * 2) If that file does not exist, try OpenClaw config and read plugins.entries.agenticros.config.
- */
-export function loadConfig(): AgenticROSConfig {
+function loadConfigSync(): AgenticROSConfig {
   const primaryPath = getConfigPath();
   try {
     const raw = fs.readFileSync(primaryPath, "utf8");
@@ -72,14 +59,14 @@ export function loadConfig(): AgenticROSConfig {
       if (process.stderr && typeof process.stderr.write === "function") {
         process.stderr.write(`[AgenticROS] Config from ${primaryPath}\n`);
       }
-      return applyMcpEnvOverrides(cfg);
+      return applyMcpEnvOverrides(applyCachedSkillRefs(cfg));
     }
   } catch (err) {
     const nodeErr = err as NodeJS.ErrnoException;
     if (nodeErr.code === "ENOENT") {
       const openclawConfig = tryOpenClawConfig();
       if (openclawConfig) {
-        return applyMcpEnvOverrides(parseConfig(openclawConfig));
+        return applyMcpEnvOverrides(applyCachedSkillRefs(parseConfig(openclawConfig)));
       }
       throw new Error(
         `AgenticROS config not found at ${primaryPath}. Create it or set AGENTICROS_CONFIG_PATH. ` +
@@ -88,5 +75,27 @@ export function loadConfig(): AgenticROSConfig {
     }
     throw err;
   }
-  return applyMcpEnvOverrides(parseConfig({}));
+  return applyMcpEnvOverrides(applyCachedSkillRefs(parseConfig({})));
+}
+
+export function loadConfig(): AgenticROSConfig {
+  return loadConfigSync();
+}
+
+export async function loadConfigAsync(): Promise<AgenticROSConfig> {
+  const base = loadConfigSync();
+  if (!(base.skillRefs?.length)) return base;
+  const { config, errors } = await withResolvedSkillRefs(base, {
+    onLog: (msg) => {
+      if (process.stderr && typeof process.stderr.write === "function") {
+        process.stderr.write(`[AgenticROS] ${msg}\n`);
+      }
+    },
+  });
+  for (const e of errors) {
+    if (process.stderr && typeof process.stderr.write === "function") {
+      process.stderr.write(`[AgenticROS] skillRef ${e.ref}: ${e.error}\n`);
+    }
+  }
+  return applyMcpEnvOverrides(config);
 }

package/runtime/packages/agenticros-gemini/src/index.ts

@@ -10,7 +10,7 @@
  * Optional: GEMINI_MODEL (default gemini-2.5-flash) if you hit quota on a specific model.
  */
 
-import { loadConfig } from "./config.js";
+import { loadConfigAsync } from "./config.js";
 import { connect, disconnect } from "./transport.js";
 import { chatWithRobot } from "./chat.js";
 import { renderAgenticROSBanner } from "@agenticros/core";
@@ -32,7 +32,7 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  const config = loadConfig();
+  const config = await loadConfigAsync();
   await connect(config);
 
   try {

package/runtime/packages/agenticros-gemini/src/tools.ts

@@ -14,6 +14,7 @@ import {
   toNamespacedTopic,
   toNamespacedTopicFull,
   listAllCapabilities,
+  listCapabilitiesWithDiscoverable,
   runMission,
   listRobots,
   getActiveRobotId,
@@ -500,15 +501,17 @@ export async function executeTool(
   if (name === "ros2_list_capabilities") {
     const resolved = resolveRobotForTool(config, args);
     if ("error" in resolved) return resolved.error;
-    const caps: Capability[] = listAllCapabilities(config);
+    const caps = await listCapabilitiesWithDiscoverable(config);
     const intrinsic = caps.filter((c) => c.source?.kind === "builtin").length;
-    const skill = caps.filter((c) => c.source?.kind === "skill").length;
+    const skill = caps.filter((c) => c.installed !== false && c.source?.kind === "skill").length;
+    const discoverable = caps.filter((c) => c.discoverable === true).length;
     return {
       output: JSON.stringify({
         success: true,
         total: caps.length,
         intrinsic_count: intrinsic,
         skill_count: skill,
+        discoverable_count: discoverable,
         capabilities: caps,
       }),
     };

package/runtime/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticros/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "AgenticROS core — platform-agnostic ROS2 transport, types, and config (the dep every AgenticROS skill imports).",
   "keywords": [

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/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>;

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/external-capability.ts

@@ -156,12 +156,25 @@ export async function executeExternalCapability(
     }
 
     if (impl.topic) {
-      const topic = resolveName(impl.topic, ns);
+      const topicName =
+        typeof inputs.topic === "string" && inputs.topic.trim()
+          ? inputs.topic.trim()
+          : impl.topic;
+      const topic = resolveName(topicName, ns);
       const msgType = impl.msg_type ?? "";
-      const mode = typeof inputs.mode === "string" ? inputs.mode : "publish";
+      // 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 === "number" ? inputs.timeout : 5000);
+          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(() => {

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

@@ -171,5 +171,35 @@ export type {
   FindRobotsForResult,
 } from "./find-robots-for.js";
 
+export {
+  DEFAULT_SKILLS_API,
+  DEFAULT_SKILLS_CACHE_DIR,
+  ensureSkillRefCached,
+  fetchInstallDescriptor,
+  githubRepoBasename,
+  parseSkillRef,
+  resolveSkillRefs,
+  skillsApiBase,
+  skillsCacheDir,
+  withResolvedSkillRefs,
+  applyCachedSkillRefs,
+} from "./skill-refs.js";
+export type {
+  InstallDescriptor,
+  ParsedSkillRef,
+  ResolveSkillRefsOptions,
+  ResolveSkillRefsResult,
+} from "./skill-refs.js";
+
+export {
+  fetchMarketplaceSkills,
+  listCapabilitiesWithDiscoverable,
+} from "./discoverable-capabilities.js";
+export type {
+  DiscoverableCapability,
+  ListCapabilitiesOptions,
+  ListedCapability,
+} from "./discoverable-capabilities.js";
+
 export { TransportPool, TRANSPORT_POOL_GLOBAL_KEY } from "./transport-pool.js";
 export type { TransportFactory } from "./transport-pool.js";