agenticros 0.0.1 → 0.1.1

package/runtime/packages/agenticros/openclaw.plugin.json

@@ -0,0 +1,451 @@
+{
+  "id": "agenticros",
+  "name": "AgenticROS",
+  "version": "0.0.1",
+  "description": "ROS2 integration for AI agent platforms (OpenClaw adapter)",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": [
+      "ros2_publish",
+      "ros2_subscribe_once",
+      "ros2_service_call",
+      "ros2_action_goal",
+      "ros2_param_get",
+      "ros2_param_set",
+      "ros2_list_topics",
+      "ros2_camera_snapshot",
+      "ros2_depth_distance",
+      "memory_remember",
+      "memory_recall",
+      "memory_forget",
+      "memory_status",
+      "follow_robot",
+      "follow_me_see",
+      "ollama_status"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "transport": {
+        "type": "object",
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": [
+              "rosbridge",
+              "local",
+              "webrtc",
+              "zenoh"
+            ],
+            "description": "Transport mode: local (Mode A, default — gateway co-located with the robot), rosbridge (Mode B, off-robot via WebSocket), webrtc (Mode C, cloud), or zenoh (Mode D)",
+            "default": "local"
+          }
+        }
+      },
+      "rosbridge": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Rosbridge WebSocket URL",
+            "default": "ws://localhost:9090"
+          },
+          "reconnect": {
+            "type": "boolean",
+            "description": "Auto-reconnect on disconnect",
+            "default": true
+          },
+          "reconnectInterval": {
+            "type": "number",
+            "description": "Reconnect interval in milliseconds",
+            "default": 3000
+          }
+        },
+        "required": [
+          "url"
+        ]
+      },
+      "local": {
+        "type": "object",
+        "properties": {
+          "domainId": {
+            "type": "number",
+            "description": "ROS2 domain ID for local DDS communication",
+            "default": 0
+          }
+        }
+      },
+      "zenoh": {
+        "type": "object",
+        "properties": {
+          "routerEndpoint": {
+            "type": "string",
+            "description": "Zenoh router endpoint (e.g. ws://localhost:10000 for zenoh-ts)",
+            "default": "tcp/localhost:7447"
+          },
+          "domainId": {
+            "type": "number",
+            "description": "ROS2 domain ID (matches rmw_zenoh)",
+            "default": 0
+          },
+          "keyFormat": {
+            "type": "string",
+            "enum": [
+              "ros2dds",
+              "rmw_zenoh"
+            ],
+            "description": "Use ros2dds when using zenoh-bridge-ros2dds; use rmw_zenoh when robot uses Zenoh RMW directly",
+            "default": "ros2dds"
+          },
+          "bridgeNamespace": {
+            "type": "string",
+            "description": "Must match zenoh-bridge-ros2dds plugins.ros2dds.namespace when not default \"/\" (e.g. \"/bot1\"). Omit for default bridge namespace."
+          }
+        }
+      },
+      "webrtc": {
+        "type": "object",
+        "properties": {
+          "signalingUrl": {
+            "type": "string",
+            "description": "WebSocket URL of the signaling server (e.g., wss://signal-host)"
+          },
+          "apiUrl": {
+            "type": "string",
+            "description": "REST API URL of the signaling server (e.g., https://signal-host)"
+          },
+          "robotId": {
+            "type": "string",
+            "description": "Target robot's ID on the signaling server"
+          },
+          "robotKey": {
+            "type": "string",
+            "description": "Robot key secret (validated by robot, not server)"
+          },
+          "iceServers": {
+            "type": "array",
+            "description": "STUN/TURN server configuration",
+            "items": {
+              "type": "object",
+              "properties": {
+                "urls": {
+                  "description": "STUN/TURN server URL(s)"
+                },
+                "username": {
+                  "type": "string"
+                },
+                "credential": {
+                  "type": "string"
+                }
+              }
+            },
+            "default": [
+              {
+                "urls": "stun:stun.l.google.com:19302"
+              }
+            ]
+          }
+        }
+      },
+      "robot": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Robot display name",
+            "default": "Robot"
+          },
+          "namespace": {
+            "type": "string",
+            "description": "ROS2 topic namespace so cmd_vel and other root-level topics are published to /<namespace>/<topic> (e.g. robot3946b404c33e4aa39a8d16deb1c5c593 → /robot3946.../cmd_vel). Required if the robot base subscribes to a namespaced cmd_vel.",
+            "default": ""
+          },
+          "cameraTopic": {
+            "type": "string",
+            "description": "Camera topic for what do you see and default for teleop",
+            "default": ""
+          }
+        }
+      },
+      "teleop": {
+        "type": "object",
+        "description": "Teleop web app: camera and twist controls",
+        "properties": {
+          "cameraTopic": {
+            "type": "string",
+            "default": ""
+          },
+          "cameraTopics": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "topic": {
+                  "type": "string"
+                },
+                "label": {
+                  "type": "string"
+                }
+              }
+            },
+            "default": []
+          },
+          "cmdVelTopic": {
+            "type": "string",
+            "default": ""
+          },
+          "speedDefault": {
+            "type": "number",
+            "description": "Default linear speed (m/s) for teleop",
+            "default": 0.3,
+            "minimum": 0,
+            "maximum": 2
+          },
+          "cameraPollMs": {
+            "type": "number",
+            "default": 150,
+            "minimum": 50,
+            "maximum": 2000
+          }
+        }
+      },
+      "safety": {
+        "type": "object",
+        "properties": {
+          "maxLinearVelocity": {
+            "type": "number",
+            "description": "Maximum linear velocity (m/s)",
+            "default": 1
+          },
+          "maxAngularVelocity": {
+            "type": "number",
+            "description": "Maximum angular velocity (rad/s)",
+            "default": 1.5
+          },
+          "workspaceLimits": {
+            "type": "object",
+            "description": "Workspace boundary limits (meters)",
+            "properties": {
+              "xMin": {
+                "type": "number",
+                "default": -10
+              },
+              "xMax": {
+                "type": "number",
+                "default": 10
+              },
+              "yMin": {
+                "type": "number",
+                "default": -10
+              },
+              "yMax": {
+                "type": "number",
+                "default": 10
+              }
+            }
+          }
+        }
+      },
+      "describer": {
+        "type": "object",
+        "description": "Optional in-plugin image describer. When enabled, ros2_camera_snapshot calls an OpenAI-compatible vision endpoint (typically local Ollama with a qwen2.5-VL model) and embeds the description text directly in the tool result. Required when the primary chat model is text-only (e.g. qwen2.5:7b for tool calling on Jetson) because OpenClaw filters image content blocks out of tool results for text-only models, leaving the agent unable to describe what the robot sees.",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Master switch for the describer."
+          },
+          "url": {
+            "type": "string",
+            "default": "http://host.openshell.internal:11435/v1/chat/completions",
+            "description": "OpenAI-compat chat completions endpoint URL (e.g. Ollama)."
+          },
+          "apiKey": {
+            "type": "string",
+            "description": "Optional Bearer token for the endpoint."
+          },
+          "model": {
+            "type": "string",
+            "default": "qwen2.5vl:7b",
+            "description": "Vision model id (must accept OpenAI image_url content blocks)."
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Prompt sent alongside each image. A reasonable default is used when omitted."
+          },
+          "maxTokens": {
+            "type": "number",
+            "default": 400,
+            "minimum": 50,
+            "maximum": 2048,
+            "description": "Max tokens to generate for each description."
+          },
+          "timeoutMs": {
+            "type": "number",
+            "default": 60000,
+            "minimum": 1000,
+            "maximum": 180000,
+            "description": "HTTP request timeout in milliseconds."
+          },
+          "maxImageDimension": {
+            "type": "number",
+            "default": 896,
+            "minimum": 0,
+            "maximum": 4096,
+            "description": "Resize images larger than this max dimension before sending to the VL model. 0 disables resizing."
+          }
+        }
+      },
+      "memory": {
+        "type": "object",
+        "description": "Optional cross-adapter semantic memory. Off by default; see docs/memory.md.",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Master switch. When false, no memory tools are registered."
+          },
+          "backend": {
+            "type": "string",
+            "enum": ["local", "mem0"],
+            "default": "local",
+            "description": "local = JSON-on-disk, no deps; mem0 = semantic search via mem0ai (requires `pnpm add mem0ai`)."
+          },
+          "namespace": {
+            "type": "string",
+            "description": "Override per-record namespace. Defaults to robot.namespace at call time."
+          },
+          "local": {
+            "type": "object",
+            "properties": {
+              "storePath": {
+                "type": "string",
+                "default": "~/.agenticros/memory.json"
+              }
+            }
+          },
+          "mem0": {
+            "type": "object",
+            "properties": {
+              "inferOnWrite": {
+                "type": "boolean",
+                "default": false,
+                "description": "When true, mem0 LLM-extracts facts on add. Default false (raw store)."
+              },
+              "historyDbPath": {
+                "type": "string",
+                "default": "~/.agenticros/memory-history.db"
+              },
+              "embedder": {
+                "type": "object",
+                "description": "Optional. When omitted, factory auto-detects Ollama → OpenAI → error."
+              },
+              "vectorStore": {
+                "type": "object",
+                "description": "Optional. Passed to mem0 verbatim."
+              },
+              "llm": {
+                "type": "object",
+                "description": "Optional. Required only when inferOnWrite is true."
+              }
+            }
+          }
+        }
+      },
+      "skills": {
+        "type": "object",
+        "description": "Per-skill config. Keys are skill ids (e.g. followme). Each skill validates its own slice.",
+        "additionalProperties": true
+      },
+      "skillPaths": {
+        "type": "array",
+        "description": "Directories to scan for skill packages (package.json with agenticrosSkill: true).",
+        "items": {
+          "type": "string"
+        },
+        "default": []
+      },
+      "skillPackages": {
+        "type": "array",
+        "description": "Npm (or local) package names to load as skills (e.g. agenticros-skill-followme).",
+        "items": {
+          "type": "string"
+        },
+        "default": []
+      }
+    }
+  },
+  "uiHints": {
+    "transport.mode": {
+      "label": "Transport Mode",
+      "description": "How the plugin connects to ROS2: rosbridge (WebSocket), local (DDS), webrtc (P2P), or zenoh (Mode D)"
+    },
+    "zenoh.routerEndpoint": {
+      "label": "Zenoh Router Endpoint",
+      "placeholder": "ws://localhost:10000"
+    },
+    "zenoh.domainId": {
+      "label": "Zenoh Domain ID",
+      "advanced": true
+    },
+    "zenoh.bridgeNamespace": {
+      "label": "Zenoh bridge ROS namespace",
+      "description": "Same as ros2dds.namespace on the robot bridge when not \"/\"",
+      "advanced": true
+    },
+    "rosbridge.url": {
+      "label": "Rosbridge URL",
+      "placeholder": "ws://localhost:9090"
+    },
+    "robot.name": {
+      "label": "Robot Name",
+      "placeholder": "Robot"
+    },
+    "robot.namespace": {
+      "label": "ROS2 Robot Namespace",
+      "description": "ROS2 topic namespace; e.g. robot-uuid gives topics like /robot-uuid/cmd_vel",
+      "placeholder": ""
+    },
+    "safety.maxLinearVelocity": {
+      "label": "Max Linear Velocity (m/s)",
+      "advanced": true
+    },
+    "safety.maxAngularVelocity": {
+      "label": "Max Angular Velocity (rad/s)",
+      "advanced": true
+    },
+    "safety.workspaceLimits": {
+      "label": "Workspace Boundary Limits",
+      "advanced": true
+    },
+    "skills.followme.depthTopic": {
+      "label": "Follow Me — depth image topic",
+      "description": "sensor_msgs/Image depth topic for distance (e.g. RealSense depth)"
+    },
+    "skills.followme.rateHz": {
+      "label": "Follow Me — loop rate (Hz)",
+      "advanced": true
+    },
+    "skills.followme.invertLinearX": {
+      "label": "Follow Me — invert cmd_vel linear.x",
+      "description": "Flip forward/back if the base drives the wrong way",
+      "advanced": true
+    },
+    "skills.followme.logTickTiming": {
+      "label": "Follow Me — log tick timing",
+      "description": "Emit latency logs for depth / sectors / Ollama per tick",
+      "advanced": true
+    },
+    "skills.followme.criticalStopDistanceM": {
+      "label": "Follow Me — hard stop distance (m)"
+    },
+    "skills.followme.maxVelocityFraction": {
+      "label": "Follow Me — max speed fraction of Safety limits",
+      "description": "Caps linear/angular vs safety.maxLinearVelocity / maxAngularVelocity (e.g. 0.2 = 20%)"
+    }
+  }
+}

package/runtime/packages/agenticros/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agenticros/openclaw",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "AgenticROS OpenClaw plugin — ROS2 tools, commands, and routes for the OpenClaw gateway",
+  "openclaw": {
+    "id": "agenticros",
+    "activation": {
+      "onStartup": true
+    },
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],    
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2"
+    }
+  },
+  "dependencies": {
+    "@agenticros/core": "workspace:*",
+    "@agenticros/ros-camera": "workspace:*",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "typescript": "^5.7.0"
+  },
+  "author": "PlaiPin",
+  "license": "Apache-2.0"
+}

package/runtime/packages/agenticros/src/camera-snapshot-cache.ts

@@ -0,0 +1,59 @@
+import { randomBytes } from "node:crypto";
+
+type Entry = { body: Buffer; mimeType: string; at: number };
+
+const TTL_MS = 15 * 60 * 1000;
+const MAX_ENTRIES = 64;
+const MAX_BYTES = 12 * 1024 * 1024;
+
+const cache = new Map<string, Entry>();
+
+function prune(): void {
+  const now = Date.now();
+  for (const [k, v] of cache) {
+    if (now - v.at > TTL_MS) {
+      cache.delete(k);
+    }
+  }
+  while (cache.size > MAX_ENTRIES) {
+    let oldestKey: string | undefined;
+    let oldestAt = Infinity;
+    for (const [k, v] of cache) {
+      if (v.at < oldestAt) {
+        oldestAt = v.at;
+        oldestKey = k;
+      }
+    }
+    if (oldestKey) {
+      cache.delete(oldestKey);
+    } else {
+      break;
+    }
+  }
+}
+
+/**
+ * Store one frame for GET /camera/snapshot?id=… (chat UI same as teleop: raw bytes, not data URLs).
+ */
+export function storeCameraSnapshot(body: Buffer, mimeType: string): string {
+  prune();
+  if (body.length > MAX_BYTES) {
+    throw new Error(`Snapshot exceeds ${MAX_BYTES} bytes`);
+  }
+  const id = randomBytes(16).toString("hex");
+  cache.set(id, { body, mimeType: mimeType.trim() || "image/jpeg", at: Date.now() });
+  return id;
+}
+
+export function getCameraSnapshot(id: string): Entry | undefined {
+  prune();
+  const e = cache.get(id);
+  if (!e) {
+    return undefined;
+  }
+  if (Date.now() - e.at > TTL_MS) {
+    cache.delete(id);
+    return undefined;
+  }
+  return e;
+}

package/runtime/packages/agenticros/src/camera-snapshot-routes.ts

@@ -0,0 +1,44 @@
+import type { OpenClawPluginApi, HttpRouteRequest, HttpRouteResponse } from "./plugin-api.js";
+import { getCameraSnapshot } from "./camera-snapshot-cache.js";
+
+/**
+ * Serves cached ros2_camera_snapshot bytes (JPEG/PNG) for chat markdown — avoids huge data: URLs.
+ */
+export function registerCameraSnapshotRoutes(api: OpenClawPluginApi): void {
+  const register = api.registerHttpRoute;
+  if (typeof register !== "function") {
+    return;
+  }
+
+  const handler = (req: HttpRouteRequest, res: HttpRouteResponse) => {
+    const url = req.url ?? "";
+    const u = new URL(url, "http://localhost");
+    const id = u.searchParams.get("id")?.trim() ?? "";
+    if (!id || !/^[a-f0-9]{32}$/i.test(id)) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("Missing or invalid id");
+      return;
+    }
+    const entry = getCameraSnapshot(id);
+    if (!entry) {
+      res.statusCode = 404;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("Snapshot not found or expired");
+      return;
+    }
+    res.setHeader("Content-Type", entry.mimeType);
+    res.setHeader("Cache-Control", "no-store");
+    res.statusCode = 200;
+    res.end(entry.body);
+  };
+
+  const route = (opts: { path: string; method?: string; handler: typeof handler }) =>
+    register({ ...opts, requireAuth: false, auth: "plugin" });
+
+  for (const base of ["/agenticros", "/api/agenticros", "/plugins/agenticros"]) {
+    route({ path: `${base}/camera/snapshot`, method: "GET", handler });
+  }
+
+  api.logger.info("AgenticROS: camera snapshot route registered (GET .../camera/snapshot?id=)");
+}

package/runtime/packages/agenticros/src/commands/estop.ts

@@ -0,0 +1,41 @@
+import type { OpenClawPluginApi } from "../plugin-api.js";
+import type { AgenticROSConfig } from "@agenticros/core";
+import { getTransport } from "../service.js";
+import { getCmdVelTopic } from "../teleop/routes.js";
+
+const TWIST_TYPE = "geometry_msgs/msg/Twist";
+const ZERO_TWIST = {
+  linear: { x: 0, y: 0, z: 0 },
+  angular: { x: 0, y: 0, z: 0 },
+};
+
+/**
+ * Register the /estop command.
+ * This command bypasses the AI agent and immediately sends a zero-velocity
+ * command to stop the robot. Uses the same cmd_vel topic as teleop/skills
+ * (config.teleop.cmdVelTopic or robot namespace).
+ */
+export function registerEstopCommand(api: OpenClawPluginApi, config: AgenticROSConfig): void {
+  api.registerCommand({
+    name: "estop",
+    description: "Emergency stop — immediately halt the robot (bypasses AI)",
+
+    async handler(_ctx) {
+      try {
+        const transport = getTransport();
+        const topic = getCmdVelTopic(config);
+
+        // Send zero repeatedly so the base reliably stops
+        for (let i = 0; i < 5; i++) {
+          transport.publish({ topic, type: TWIST_TYPE, msg: ZERO_TWIST });
+        }
+
+        api.logger.warn("ESTOP: Zero velocity command sent");
+        return { text: "Emergency stop activated. Robot halted." };
+      } catch (error) {
+        api.logger.error(`ESTOP FAILED: ${String(error)}`);
+        return { text: "Emergency stop failed — transport may be disconnected!" };
+      }
+    },
+  });
+}