agenticros 0.3.3 → 0.3.5

package/runtime/packages/core/src/mission-bindings.ts

@@ -0,0 +1,189 @@
+/**
+ * Capability → tool bindings for `run_mission`.
+ *
+ * Builtins live here once; adapters import `buildMissionBindings()` instead
+ * of triplicating MISSION_BINDINGS. Skill-declared capabilities get a
+ * default tool name (`ros2_<id>`, or `capability.tool` when set) and a
+ * passthrough `buildArgs` that forwards resolved inputs.
+ *
+ * External ROS-node capabilities map to the synthetic tool
+ * `external:<capability_id>` so adapters can dispatch via
+ * `executeExternalCapability` before looking up a real tool.
+ */
+
+import type { Capability } from "./capabilities.js";
+import type { CapabilityToolBinding, CapabilityToolBindings } from "./mission.js";
+
+/** Optional explicit tool name on a capability (skill authors may set this). */
+export type CapabilityWithTool = Capability & { tool?: string };
+
+function copyNumber(out: Record<string, unknown>, inputs: Record<string, unknown>, key: string): void {
+  if (typeof inputs[key] === "number") out[key] = inputs[key];
+}
+
+function copyString(out: Record<string, unknown>, inputs: Record<string, unknown>, key: string): void {
+  if (typeof inputs[key] === "string") out[key] = inputs[key];
+}
+
+function copyBoolean(out: Record<string, unknown>, inputs: Record<string, unknown>, key: string): void {
+  if (typeof inputs[key] === "boolean") out[key] = inputs[key];
+}
+
+/** Built-in capability → tool mappings shared by all adapters. */
+export const BUILTIN_MISSION_BINDINGS: CapabilityToolBindings = {
+  drive_base: {
+    tool: "ros2_publish",
+    buildArgs: (inputs) => {
+      const lx = Number(inputs.linear_x ?? 0) || 0;
+      const az = Number(inputs.angular_z ?? 0) || 0;
+      return {
+        topic: "/cmd_vel",
+        type: "geometry_msgs/msg/Twist",
+        message: {
+          linear: { x: lx, y: 0, z: 0 },
+          angular: { x: 0, y: 0, z: az },
+        },
+      };
+    },
+  },
+  take_snapshot: {
+    tool: "ros2_camera_snapshot",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = {};
+      copyString(out, inputs, "topic");
+      copyString(out, inputs, "message_type");
+      copyNumber(out, inputs, "timeout");
+      return out;
+    },
+  },
+  measure_depth: {
+    tool: "ros2_depth_distance",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = {};
+      copyString(out, inputs, "topic");
+      copyNumber(out, inputs, "timeout");
+      return out;
+    },
+  },
+  list_topics: {
+    tool: "ros2_list_topics",
+    buildArgs: () => ({}),
+  },
+  publish_topic: {
+    tool: "ros2_publish",
+    buildArgs: (inputs) => ({
+      topic: String(inputs.topic ?? ""),
+      type: String(inputs.type ?? inputs.msg_type ?? ""),
+      message: inputs.message ?? inputs.msg ?? {},
+    }),
+  },
+  subscribe_once: {
+    tool: "ros2_subscribe_once",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = { topic: String(inputs.topic ?? "") };
+      copyString(out, inputs, "type");
+      copyNumber(out, inputs, "timeout");
+      return out;
+    },
+  },
+  follow_person: {
+    tool: "ros2_follow_me_start",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = {};
+      copyNumber(out, inputs, "target_distance");
+      copyString(out, inputs, "mode");
+      return out;
+    },
+  },
+  find_object: {
+    tool: "ros2_find_object",
+    buildArgs: (inputs) => {
+      const out: Record<string, unknown> = { target: String(inputs.target ?? "") };
+      copyNumber(out, inputs, "angular_speed");
+      copyBoolean(out, inputs, "clockwise");
+      copyNumber(out, inputs, "timeout_seconds");
+      copyNumber(out, inputs, "min_confidence");
+      return out;
+    },
+  },
+};
+
+/** Synthetic tool prefix for external_ros_node capabilities. */
+export const EXTERNAL_TOOL_PREFIX = "external:";
+
+export function externalToolName(capabilityId: string): string {
+  return `${EXTERNAL_TOOL_PREFIX}${capabilityId}`;
+}
+
+export function isExternalToolName(toolName: string): boolean {
+  return toolName.startsWith(EXTERNAL_TOOL_PREFIX);
+}
+
+export function capabilityIdFromExternalTool(toolName: string): string {
+  return toolName.slice(EXTERNAL_TOOL_PREFIX.length);
+}
+
+/**
+ * Default tool name for a skill-declared capability.
+ * Prefer explicit `tool`, then external synthetic name, else `ros2_<id>`.
+ */
+export function defaultToolForCapability(cap: CapabilityWithTool): string {
+  if (typeof cap.tool === "string" && cap.tool.trim().length > 0) {
+    return cap.tool.trim();
+  }
+  if (cap.implementation?.kind === "external_ros_node") {
+    return externalToolName(cap.id);
+  }
+  return `ros2_${cap.id}`;
+}
+
+/** Passthrough: forward resolved inputs as tool args (skill tools). */
+export function passthroughBuildArgs(inputs: Record<string, unknown>): Record<string, unknown> {
+  return { ...inputs };
+}
+
+export interface BuildMissionBindingsOptions {
+  /**
+   * Override tool name resolution for a capability id.
+   * Useful when OpenClaw registers a skill tool under a non-default name.
+   */
+  toolNameResolver?: (cap: Capability) => string | undefined;
+  /**
+   * Extra bindings merged last (win over builtins and auto-derived).
+   */
+  extra?: CapabilityToolBindings;
+}
+
+/**
+ * Build the full capability → tool map for a mission run.
+ *
+ * Order: builtins → auto-derived from non-builtin capabilities → extra.
+ */
+export function buildMissionBindings(
+  capabilities: readonly Capability[],
+  options: BuildMissionBindingsOptions = {},
+): CapabilityToolBindings {
+  const out: CapabilityToolBindings = { ...BUILTIN_MISSION_BINDINGS };
+
+  for (const cap of capabilities) {
+    if (cap.source?.kind === "builtin") continue;
+    // Skip if already covered by builtins (e.g. follow_person from a skill
+    // that duplicates the builtin id — keep the richer builtin binding).
+    if (out[cap.id] && BUILTIN_MISSION_BINDINGS[cap.id]) continue;
+
+    const resolved =
+      options.toolNameResolver?.(cap) ?? defaultToolForCapability(cap as CapabilityWithTool);
+
+    const binding: CapabilityToolBinding = {
+      tool: resolved,
+      buildArgs: passthroughBuildArgs,
+    };
+    out[cap.id] = binding;
+  }
+
+  if (options.extra) {
+    Object.assign(out, options.extra);
+  }
+
+  return out;
+}

package/runtime/packages/core/src/mission-registry.ts

@@ -35,7 +35,7 @@ export interface MissionRegistryEntry {
   name?: string;
   /** ms since epoch when the mission was registered. */
   started_at: number;
-  /** The token the mission runner reads each step. */
+  /** The token the mission runner reads each step (cancel + pause). */
   cancellation: MissionCancellationToken;
 }
 
@@ -45,7 +45,7 @@ export interface MissionRegistryEntry {
  * Uses `crypto.randomUUID()` when available (Node 14.17+, Bun, modern
  * browsers); falls back to a Math.random hex string with a `mns_` prefix.
  * Either way the id is opaque to downstream consumers — they just echo
- * it back to `mission_cancel` / `memory_recall`.
+ * it back to `mission_cancel` / `mission_pause` / `memory_recall`.
  */
 export function generateMissionId(): string {
   const g = globalThis as { crypto?: { randomUUID?: () => string } };
@@ -86,7 +86,7 @@ export class MissionRegistry {
       mission_id: missionId,
       name: opts?.name,
       started_at: Date.now(),
-      cancellation: { cancelled: false },
+      cancellation: { cancelled: false, paused: false },
     };
     this.entries.set(missionId, entry);
     return {
@@ -112,10 +112,38 @@ export class MissionRegistry {
     if (!entry) return { found: false, alreadyCancelled: false };
     const alreadyCancelled = entry.cancellation.cancelled === true;
     entry.cancellation.cancelled = true;
+    entry.cancellation.paused = false;
     if (reason !== undefined) entry.cancellation.reason = reason;
     return { found: true, alreadyCancelled };
   }
 
+  /**
+   * Pause the named mission at the next step boundary.
+   * Idempotent — pausing an already-paused mission is a no-op.
+   */
+  pause(missionId: string, reason?: string): { found: boolean; alreadyPaused: boolean } {
+    const entry = this.entries.get(missionId);
+    if (!entry) return { found: false, alreadyPaused: false };
+    if (entry.cancellation.cancelled) {
+      return { found: true, alreadyPaused: entry.cancellation.paused === true };
+    }
+    const alreadyPaused = entry.cancellation.paused === true;
+    entry.cancellation.paused = true;
+    if (reason !== undefined) entry.cancellation.reason = reason;
+    return { found: true, alreadyPaused };
+  }
+
+  /**
+   * Resume a paused mission. Idempotent when not paused.
+   */
+  resume(missionId: string): { found: boolean; wasPaused: boolean } {
+    const entry = this.entries.get(missionId);
+    if (!entry) return { found: false, wasPaused: false };
+    const wasPaused = entry.cancellation.paused === true;
+    entry.cancellation.paused = false;
+    return { found: true, wasPaused };
+  }
+
   /** True when the named mission is currently registered. */
   has(missionId: string): boolean {
     return this.entries.has(missionId);

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

@@ -45,29 +45,40 @@
  *
  * What's still deferred:
  *   - Parallel step execution (today: sequential only).
- *   - Per-tool cancellation (cancel TIES to step boundaries today).
- *   - Natural-language plan compilation (today: declarative only).
+ *   - Per-tool cancellation (cancel TIES to step boundaries today;
+ *     pause/resume also ties to step boundaries).
  *   - Retry / backoff policies.
  *
+ * Shipped since the original Phase 1.f header:
+ *   - Natural-language plan compilation (`compileGoalToMission` + goal arg).
+ *   - Pause / resume via the same control token (`paused` flag).
+ *
  * See: docs/strategy-ai-agents-plus-ros.md §4 (Phase 1.c / 1.f).
  */
 
 import type { Capability } from "./capabilities.js";
 
 /**
- * Cancellation token consumed by `runMission`.
+ * Cancellation / pause token consumed by `runMission`.
  *
  * Plain object (not AbortController) so it's easy to share across
  * processes via a registry without pulling Web platform shims in. The
- * runner only reads `cancelled`; `reason` is surfaced in the result
- * for traceability.
+ * runner reads `cancelled` and `paused` at each step boundary.
  */
 export interface MissionCancellationToken {
   cancelled: boolean;
-  /** Optional free-text reason — bubbled up into the cancelled step results. */
+  /**
+   * When true, the runner waits at the next step boundary until
+   * `paused` is cleared or `cancelled` is set. Phase 1 pause/resume.
+   */
+  paused?: boolean;
+  /** Optional free-text reason — bubbled up into cancelled / paused results. */
   reason?: string;
 }
 
+/** Alias — control token is the same object as the cancellation token. */
+export type MissionControlToken = MissionCancellationToken;
+
 /**
  * Per-step transcript sink. Called immediately after a step finishes
  * (including cancelled / skipped steps) so an external store sees the
@@ -154,8 +165,11 @@ export interface MissionStepResult {
    *   - "error":    tool returned an error or the binding/build threw.
    *   - "skipped":  earlier step failed with on_fail=stop.
    *   - "cancelled": mission was cancelled (Phase 1.f) before this step ran.
+   *   - "paused":   transcript-only marker emitted when the runner entered
+   *                 a pause wait before this step (not a final step outcome
+   *                 in `MissionResult.steps` — those use ok/error/skipped/cancelled).
    */
-  status: "ok" | "error" | "skipped" | "cancelled";
+  status: "ok" | "error" | "skipped" | "cancelled" | "paused";
   /** Resolved inputs (with `{{...}}` templates substituted). */
   inputs: Record<string, unknown>;
   /** Outputs parsed from the tool response (may be `undefined` for fire-and-forget). */
@@ -253,6 +267,31 @@ export type CapabilityToolBindings = Record<string, CapabilityToolBinding>;
 
 const TEMPLATE_RE = /\{\{\s*([a-zA-Z0-9_]+)\.outputs\.([a-zA-Z0-9_]+)\s*\}\}/g;
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+const PAUSE_POLL_MS = 100;
+
+/**
+ * Wait while `token.paused` is true. Returns when resumed or cancelled.
+ * Emits one transcript entry with status "paused" the first time we enter
+ * the wait (so a second agent can see the mission is held).
+ */
+async function waitWhilePaused(
+  token: MissionCancellationToken | undefined,
+  emitPaused: () => void,
+): Promise<"resumed" | "cancelled"> {
+  if (!token?.paused || token.cancelled) {
+    return token?.cancelled ? "cancelled" : "resumed";
+  }
+  emitPaused();
+  while (token.paused && !token.cancelled) {
+    await sleep(PAUSE_POLL_MS);
+  }
+  return token.cancelled ? "cancelled" : "resumed";
+}
+
 /**
  * Substitute `{{stepId.outputs.field}}` references in `value` using the
  * given step output map. Recurses into nested objects/arrays.
@@ -404,6 +443,24 @@ export async function runMission(
       cancelled = true;
     }
 
+    // Pause: wait at the step boundary until resume or cancel.
+    if (!cancelled && options?.cancellation?.paused) {
+      const pauseOutcome = await waitWhilePaused(options.cancellation, () => {
+        const pausedMarker: MissionStepResult = {
+          id: step.id,
+          capability: step.capability,
+          status: "paused",
+          inputs: {},
+          message: `Paused: ${options.cancellation?.reason ?? "paused"}`,
+          duration_ms: 0,
+        };
+        emitTranscript(idx, t0, pausedMarker);
+      });
+      if (pauseOutcome === "cancelled" || options.cancellation?.cancelled) {
+        cancelled = true;
+      }
+    }
+
     if (cancelled) {
       const result: MissionStepResult = {
         id: step.id,

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

@@ -25,6 +25,7 @@
 import type { AgenticROSConfig } from "./config.js";
 import { getTransportConfig } from "./config.js";
 import type { TransportConfig } from "./transport/types.js";
+import { applyFleetOverride } from "./fleet-config.js";
 
 /** Sensor/hardware tags on a robot (Phase 1.e). */
 export interface RobotSensors {
@@ -85,7 +86,10 @@ const DEFAULT_SENSORS: RobotSensors = {
 };
 
 export function listRobots(config: AgenticROSConfig): ResolvedRobot[] {
-  const explicit = Array.isArray(config.robots) ? config.robots : [];
+  // Phase 1.d — ~/.agenticros/fleet.json (or AGENTICROS_FLEET_PATH) wins
+  // over config.robots when present and non-empty.
+  const effective = applyFleetOverride(config);
+  const explicit = Array.isArray(effective.robots) ? effective.robots : [];
   if (explicit.length > 0) {
     return explicit.map((r) => ({
       id: String(r.id),
@@ -107,7 +111,7 @@ export function listRobots(config: AgenticROSConfig): ResolvedRobot[] {
   // ros2_find_robots_for). Users on multi-robot deployments will have
   // promoted into config.robots[] anyway, where the fields are
   // explicit.
-  const legacy = config.robot ?? { name: "Robot", namespace: "", cameraTopic: "" };
+  const legacy = effective.robot ?? { name: "Robot", namespace: "", cameraTopic: "" };
   const id = (legacy.namespace?.trim() || "default");
   return [
     {

package/runtime/packages/core/src/transport/rosbridge/client.ts

@@ -46,6 +46,13 @@ export interface PendingRequest {
  * fresh CONNECT tunnel.
  */
 function buildProxyAgentForUrl(wsUrl: string): HttpAgent | null {
+  // When NODE_USE_ENV_PROXY=1 (Node 22+ / NemoClaw sandbox), the runtime's
+  // built-in EnvHttpProxyAgent handles ws:// tunneling natively and adds the
+  // authentication headers the OpenShell proxy requires. A manual CONNECT
+  // request (our TunnelAgent below) omits those headers and gets 403 from
+  // the proxy. Skip our agent and let Node handle it.
+  if (process.env.NODE_USE_ENV_PROXY === "1") return null;
+
   let parsed: URL;
   try {
     parsed = new URL(wsUrl);

package/runtime/pnpm-lock.yaml

@@ -99,6 +99,12 @@ importers:
       '@google/genai':
         specifier: ^1.0.0
         version: 1.46.0(@modelcontextprotocol/sdk@1.27.1(zod@3.25.76))
+      onnxruntime-node:
+        specifier: ^1.20.0
+        version: 1.26.0
+      sharp:
+        specifier: ^0.33.0
+        version: 0.33.5
       zod:
         specifier: ^3.24.0
         version: 3.25.76

package/templates/skills/camera/package.json

@@ -26,7 +26,7 @@
     ]
   },
   "dependencies": {
-    "@agenticros/core": "^0.5.0",
+    "@agenticros/core": "^0.6.0",
     "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {

package/templates/skills/depth/package.json

@@ -26,7 +26,7 @@
     ]
   },
   "dependencies": {
-    "@agenticros/core": "^0.5.0",
+    "@agenticros/core": "^0.6.0",
     "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {

package/templates/skills/robot/package.json

@@ -28,7 +28,7 @@
     ]
   },
   "dependencies": {
-    "@agenticros/core": "^0.5.0",
+    "@agenticros/core": "^0.6.0",
     "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {