agenticros 0.1.19 → 0.2.1

package/runtime/packages/agenticros/src/skill-loader.ts

@@ -20,8 +20,8 @@
 
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
-import { readFileSync, readdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { OpenClawPluginApi } from "./plugin-api.js";
 import type { AgenticROSConfig } from "@agenticros/core";
 import type { RegisterSkill, SkillContext } from "./skill-api.js";
@@ -41,12 +41,40 @@ export function getLoadedSkillIds(): string[] {
   return [...loadedSkillIds];
 }
 
-function deriveSkillId(packageName: string): string {
-  const lower = packageName.toLowerCase();
-  if (lower.startsWith("agenticros-skill-")) {
-    return lower.slice("agenticros-skill-".length);
+/**
+ * Read the `agenticros` block from a skill's package.json. The block is now
+ * the single source of truth for the skill id, display name, and capability
+ * manifest. The legacy `agenticrosSkill: true | { capabilities }` form is
+ * NOT supported — every skill must declare a fully-formed `agenticros` block.
+ */
+interface AgenticROSBlock {
+  id: string;
+  displayName?: string;
+  description?: string;
+  categories?: string[];
+  screenshots?: string[];
+  demoVideoUrl?: string;
+  capabilities?: unknown[];
+}
+
+interface SkillManifest {
+  name?: string;
+  main?: string;
+  agenticros?: AgenticROSBlock;
+}
+
+function readSkillManifest(pkgJsonPath: string): SkillManifest | null {
+  try {
+    return JSON.parse(readFileSync(pkgJsonPath, "utf-8")) as SkillManifest;
+  } catch {
+    return null;
   }
-  return lower.replace(/^@[^/]+\//, "").replace(/[^a-z0-9]/g, "");
+}
+
+function isValidBlock(block: unknown): block is AgenticROSBlock {
+  if (!block || typeof block !== "object") return false;
+  const b = block as { id?: unknown };
+  return typeof b.id === "string" && /^[a-z0-9][a-z0-9-]*$/.test(b.id);
 }
 
 /**
@@ -56,7 +84,7 @@ function deriveSkillId(packageName: string): string {
  * — including any `api.registerTool(...)` the skill makes — completes before
  * we return, and therefore before the OpenClaw host snapshots `captured.tools`.
  *
- * Returns the derived skill id on success, or `null` (with a logged warning /
+ * Returns the declared skill id on success, or `null` (with a logged warning /
  * error) on any failure mode: missing export, top-level await (which surfaces
  * as `ERR_REQUIRE_ASYNC_MODULE`), or thrown initialization error.
  */
@@ -66,8 +94,8 @@ function loadSkillModuleSync(
   context: SkillContext,
   entryPath: string,
   packageName: string,
+  skillId: string,
 ): string | null {
-  const skillId = deriveSkillId(packageName);
   let mod: unknown;
   try {
     mod = require(entryPath);
@@ -110,44 +138,80 @@ function loadSkillModuleSync(
   }
 }
 
+interface ResolvedSkill {
+  entry: string;
+  packageName: string;
+  skillId: string;
+}
+
 /**
- * Resolve a package name to its main entry path (Node resolution).
+ * Resolve an npm package name to a `ResolvedSkill` (entry + name + skill id).
+ * Reads the package's package.json to extract `pkg.agenticros.id`; refuses
+ * to register the skill if the block is missing or malformed.
  */
-function resolvePackageEntry(packageName: string): string | null {
+function resolveSkillByPackage(
+  api: OpenClawPluginApi,
+  packageName: string,
+): ResolvedSkill | null {
+  let entry: string;
   try {
-    const pkgPath = require.resolve(packageName, { paths: [process.cwd()] });
-    return pkgPath;
+    entry = require.resolve(packageName, { paths: [process.cwd()] });
   } catch {
+    api.logger.warn(`Skill package not found: ${packageName}`);
+    return null;
+  }
+  // Walk up from the resolved entry to find the package.json.
+  const pkgJsonPath = findPackageJsonForEntry(entry);
+  if (!pkgJsonPath) {
+    api.logger.warn(`Skill ${packageName}: cannot locate package.json next to ${entry}`);
     return null;
   }
+  const manifest = readSkillManifest(pkgJsonPath);
+  if (!manifest || !isValidBlock(manifest.agenticros)) {
+    api.logger.warn(
+      `Skill ${packageName}: missing or invalid \`agenticros\` block in package.json. ` +
+        "Declare an `agenticros.id` (kebab-case) to register as a skill.",
+    );
+    return null;
+  }
+  return {
+    entry,
+    packageName: manifest.name ?? packageName,
+    skillId: manifest.agenticros!.id,
+  };
+}
+
+/** Walk up from `entry` (a file inside the package) to find its package.json. */
+function findPackageJsonForEntry(entry: string): string | null {
+  let dir = dirname(entry);
+  for (let i = 0; i < 6; i++) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
 }
 
 /**
- * Scan a directory for package.json with "agenticrosSkill": true and return entry path.
+ * Scan a directory for a package.json with a valid `agenticros` block and
+ * return its entry path + declared id.
  */
-function findSkillInPath(dirPath: string): { entry: string; packageName: string } | null {
+function findSkillInPath(dirPath: string): ResolvedSkill | null {
   if (!existsSync(dirPath)) return null;
   const pkgPath = join(dirPath, "package.json");
   if (!existsSync(pkgPath)) return null;
-  let pkg: {
-    agenticrosSkill?: boolean | Record<string, unknown>;
-    main?: string;
-    name?: string;
-  };
-  try {
-    pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-  } catch {
-    return null;
-  }
-  // Accept either the legacy boolean (`"agenticrosSkill": true`) or the
-  // Phase-1 object form (`"agenticrosSkill": { capabilities: [...] }`).
-  // Anything truthy registers the package as a skill; the capability
-  // schema is read separately by @agenticros/core.
-  if (!pkg.agenticrosSkill) return null;
+  const pkg = readSkillManifest(pkgPath);
+  if (!pkg || !isValidBlock(pkg.agenticros)) return null;
   const main = pkg.main ?? "index.js";
   const entry = join(dirPath, main);
   if (!existsSync(entry)) return null;
-  return { entry, packageName: pkg.name ?? "unknown" };
+  return {
+    entry,
+    packageName: pkg.name ?? "unknown",
+    skillId: pkg.agenticros!.id,
+  };
 }
 
 /**
@@ -174,19 +238,25 @@ export function loadSkills(
   loadedSkillIds.length = 0;
 
   for (const pkgName of packages) {
-    const entryPath = resolvePackageEntry(pkgName);
-    if (!entryPath) {
-      api.logger.warn(`Skill package not found: ${pkgName}`);
-      continue;
-    }
-    const skillId = loadSkillModuleSync(api, config, context, entryPath, pkgName);
+    const resolved = resolveSkillByPackage(api, pkgName);
+    if (!resolved) continue;
+    const skillId = loadSkillModuleSync(
+      api,
+      config,
+      context,
+      resolved.entry,
+      resolved.packageName,
+      resolved.skillId,
+    );
     if (skillId) loadedSkillIds.push(skillId);
   }
 
   for (const dir of paths) {
     const resolved = findSkillInPath(dir);
     if (!resolved) {
-      api.logger.warn(`No agenticros skill in path: ${dir}`);
+      api.logger.warn(
+        `No agenticros skill in path: ${dir} (missing \`agenticros\` block in package.json).`,
+      );
       continue;
     }
     const skillId = loadSkillModuleSync(
@@ -195,6 +265,7 @@ export function loadSkills(
       context,
       resolved.entry,
       resolved.packageName,
+      resolved.skillId,
     );
     if (skillId && !loadedSkillIds.includes(skillId)) loadedSkillIds.push(skillId);
   }

package/runtime/packages/agenticros-claude-code/README.md

@@ -1,6 +1,6 @@
 # AgenticROS Claude Code adapter
 
-MCP (Model Context Protocol) server that exposes AgenticROS ROS2 tools to **Claude Code CLI** and to the **Claude desktop app** on macOS (including **Claude Dispatch** on iPhone when paired to Claude on your Mac). Use natural language to control and query your ROS2 robot (e.g. "what do you see?", "move 1m forward").
+MCP (Model Context Protocol) server that exposes AgenticROS ROS2 tools to **Claude Code CLI** and to the **Claude desktop app** on macOS (including **Claude Dispatch** on iPhone when paired to Claude on your Mac). Use natural language to control and query your ROS2 robot (e.g. *"what do you see?"*, *"find a chair and drive toward it"*, *"list every robot that can follow a person"*).
 
 This adapter does **not** provide the config or teleop web UI; use the [OpenClaw plugin](../../packages/agenticros) for that, or run the gateway for the browser-based teleop page.
 
@@ -94,6 +94,38 @@ claude
 
 Scope options: `--scope user` (default), `--scope project` (shared via `.mcp.json`).
 
+## Codex CLI (OpenAI)
+
+The same MCP server works unmodified with the **OpenAI Codex CLI** — Codex is a vanilla MCP client, and our server speaks the standard `2024-11-05` MCP protocol that every MCP-compatible client uses. Two ways to register it:
+
+**Option A — `codex mcp add` (recommended)**
+
+```bash
+cd /path/to/agenticros
+codex mcp add agenticros \
+  -- node "$(pwd)/packages/agenticros-claude-code/dist/index.js"
+```
+
+**Option B — direct edit of `~/.codex/config.toml`**
+
+```toml
+[mcp_servers.agenticros]
+command = "node"
+args = ["/ABSOLUTE/PATH/TO/agenticros/packages/agenticros-claude-code/dist/index.js"]
+enabled = true
+startup_timeout_sec = 30
+
+[mcp_servers.agenticros.env]
+AGENTICROS_ROBOT_NAMESPACE = "robotYOUR_NAMESPACE_NO_DASHES"
+```
+
+Then start a Codex session and run `/mcp` to verify — you should see `agenticros` connected with **15 tools** (more if you have skills like `agenticros-skill-followme` or `agenticros-skill-find` registered). Same tools, same tool names, same JSON shapes as in Claude Code; everything in the **Tools** section below applies identically.
+
+Two Codex-specific notes:
+
+- **Absolute path required.** Codex's working directory at server-spawn time is not the AgenticROS repo root, so `args = ["packages/agenticros-claude-code/dist/index.js"]` will fail. Use the full absolute path.
+- **Project-scoped config.** Codex also supports a `.codex/config.toml` in a project directory (and a `mcp.json` in cwd on recent builds) — handy for per-repo MCP setups when you don't want `agenticros` enabled globally. See OpenAI's [Codex config reference](https://developers.openai.com/codex/config-reference) for the precedence rules.
+
 ## Claude desktop app + Claude Dispatch (iOS)
 
 The Claude **desktop** app uses a different MCP config file than Claude Code:
@@ -134,18 +166,29 @@ The server exposes the same ROS2 tools as the OpenClaw plugin:
 
 | Tool | Description |
 |------|-------------|
+| **Inspection** | |
 | `ros2_list_topics` | List topics and types |
-| `ros2_publish` | Publish to a topic (e.g. cmd_vel) |
+| `ros2_list_capabilities` | Typed verb manifest (built-in + skill-declared) — the planning surface for agents |
+| **Fleet** | |
+| `ros2_list_robots` | List configured robots — id, name, kind, capabilities, online status |
+| `ros2_discover_robots` | Online discovery: detect `/<ns>/cmd_vel` namespaces + classify reachability |
+| `ros2_find_robots_for` | Ranked filter by capability + kind + online — *"who can `follow_person` right now?"* |
+| **Missions** | |
+| `run_mission` | Execute a multi-step mission **or** compile a natural-language `goal` into one. Chains capabilities via `{{stepId.outputs.field}}` template refs; returns a `mission_id` |
+| `mission_cancel` | Cancel an in-flight mission by `mission_id` at the next step boundary (idempotent, safe on unknown ids) |
+| **Direct ROS** | |
+| `ros2_publish` | Publish to a topic (e.g. cmd_vel) — safety-clamped |
 | `ros2_subscribe_once` | Get next message from a topic |
 | `ros2_service_call` | Call a ROS2 service |
 | `ros2_action_goal` | Send goal to an action server |
 | `ros2_param_get` / `ros2_param_set` | Get/set node parameters |
-| `ros2_camera_snapshot` | "What do you see" — one frame from camera topic |
+| `ros2_camera_snapshot` | *"What do you see"* — one frame from camera topic |
 | `ros2_depth_distance` | Distance in meters from depth camera |
-| `memory_remember` *(when enabled)* | Store a durable fact for the robot — shared with OpenClaw, Claude Desktop, Gemini |
-| `memory_recall` *(when enabled)* | Semantic search across long-term memory |
-| `memory_forget` *(when enabled)* | Delete by id, query, or whole namespace |
-| `memory_status` *(when enabled)* | Health check + record count + embedder info |
+| **Memory** *(only when enabled)* | |
+| `memory_remember` | Store a durable fact for the robot — shared with OpenClaw, Claude Desktop, Gemini |
+| `memory_recall` | Semantic search across long-term memory (also reads `mission:<id>` step transcripts) |
+| `memory_forget` | Delete by id, query, or whole namespace |
+| `memory_status` | Health check + record count + embedder info |
 
 Safety limits (max linear/angular velocity) from config are applied before `ros2_publish`.
 
@@ -255,6 +298,6 @@ If `ros2_publish` runs but the robot doesn’t move:
 
    In the chat you can type `/mcp` to see MCP server status. If the transport isn’t running (e.g. no Zenoh router), tool calls will fail with connection errors until the ROS2 side is up.
 
-## "Follow me" and skills
+## Skills
 
-The OpenClaw plugin can load skills (e.g. **follow me** via `agenticros-skill-followme`). This MCP adapter does not load skills in v1; only the core tools above are available. For "follow me", use the OpenClaw plugin or a future version of this adapter that adds skill loading or a dedicated `follow_robot` tool.
+Skill packages (e.g. `agenticros-skill-followme`, `agenticros-skill-find`) extend the capability registry with new verbs like `follow_person` and `find_object`. The MCP server reads each skill's `package.json` `agenticros` block (`id`, `capabilities[]`) at startup and surfaces those verbs through `ros2_list_capabilities` and `run_mission` — no per-skill MCP tool needed. To register a skill for this adapter, install it with `agenticros skills install <slug>` from the marketplace, or add its path under `skillPaths[]` in `~/.agenticros/config.json` (or use the `agenticros skills add <path>` CLI). See [docs/skills.md](../../docs/skills.md) for the full skill contract.

package/runtime/packages/agenticros-claude-code/dist/__tests__/capabilities-mcp.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=capabilities-mcp.test.d.ts.map

package/runtime/packages/agenticros-claude-code/dist/__tests__/capabilities-mcp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-mcp.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/capabilities-mcp.test.ts"],"names":[],"mappings":""}