agenticros 0.4.0 → 0.5.0

package/runtime/packages/core/src/__tests__/mission-retry-cancel.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Mission runner v2 — retries / backoff + mid-step cancel for interruptible caps.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  runMission,
+  MissionStepAbortedError,
+  type CapabilityToolBindings,
+  type Mission,
+  type MissionToolDispatcher,
+} from "../mission.js";
+import type { Capability } from "../capabilities.js";
+
+const CAPS: Capability[] = [
+  { id: "drive_base", verb: "drive", description: "drive", source: { kind: "builtin" } },
+  {
+    id: "find_object",
+    verb: "find",
+    description: "find",
+    interruptible: true,
+    source: { kind: "builtin" },
+  },
+  {
+    id: "take_snapshot",
+    verb: "see",
+    description: "see",
+    interruptible: false,
+    source: { kind: "builtin" },
+  },
+];
+
+const BINDINGS: CapabilityToolBindings = {
+  drive_base: {
+    tool: "ros2_publish",
+    buildArgs: (inputs) => ({ topic: "cmd_vel", msg: inputs }),
+  },
+  find_object: {
+    tool: "ros2_find_object",
+    buildArgs: (inputs) => inputs,
+  },
+  take_snapshot: {
+    tool: "ros2_camera_snapshot",
+    buildArgs: () => ({}),
+  },
+};
+
+test("retry: retries failed step then succeeds", async () => {
+  let calls = 0;
+  const dispatch: MissionToolDispatcher = async () => {
+    calls += 1;
+    if (calls < 3) return { text: "transient", isError: true };
+    return { text: "ok", outputs: { done: true } };
+  };
+  const mission: Mission = {
+    name: "retry-drive",
+    steps: [
+      {
+        id: "a",
+        capability: "drive_base",
+        inputs: { linear_x: 0.1 },
+        retry: { max_attempts: 3, backoff_ms: 1 },
+      },
+    ],
+  };
+  const result = await runMission(mission, CAPS, BINDINGS, dispatch);
+  assert.equal(result.status, "ok");
+  assert.equal(calls, 3);
+  assert.equal(result.steps[0]!.attempts, 3);
+  assert.equal(result.steps[0]!.status, "ok");
+});
+
+test("retry: exhausts attempts then on_fail=stop", async () => {
+  let calls = 0;
+  const dispatch: MissionToolDispatcher = async () => {
+    calls += 1;
+    return { text: "always fail", isError: true };
+  };
+  const mission: Mission = {
+    name: "retry-fail",
+    steps: [
+      {
+        id: "a",
+        capability: "drive_base",
+        retry: { max_attempts: 2, backoff_ms: 1 },
+      },
+      { id: "b", capability: "take_snapshot" },
+    ],
+  };
+  const result = await runMission(mission, CAPS, BINDINGS, dispatch);
+  assert.equal(result.status, "error");
+  assert.equal(calls, 2);
+  assert.equal(result.steps[0]!.status, "error");
+  assert.equal(result.steps[0]!.attempts, 2);
+  assert.equal(result.steps[1]!.status, "skipped");
+});
+
+test("mid-step cancel: interruptible step aborts via signal", async () => {
+  const cancellation = { cancelled: false, reason: "stop find" };
+  const dispatch: MissionToolDispatcher = async (_tool, _args, ctx) => {
+    // Flip cancel shortly after start; runner polls and aborts.
+    setTimeout(() => {
+      cancellation.cancelled = true;
+    }, 30);
+    await new Promise<void>((resolve, reject) => {
+      const t = setInterval(() => {
+        if (ctx?.signal?.aborted) {
+          clearInterval(t);
+          reject(new MissionStepAbortedError("find aborted"));
+        }
+      }, 10);
+      setTimeout(() => {
+        clearInterval(t);
+        resolve();
+      }, 5000);
+    });
+    return { text: "should not finish" };
+  };
+  const mission: Mission = {
+    name: "find-cancel",
+    steps: [
+      { id: "find", capability: "find_object", inputs: { target: "chair" } },
+      { id: "snap", capability: "take_snapshot" },
+    ],
+  };
+  const result = await runMission(mission, CAPS, BINDINGS, dispatch, {
+    mission_id: "mn_mid",
+    cancellation,
+  });
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.steps[0]!.status, "cancelled");
+  assert.equal(result.steps[1]!.status, "cancelled");
+});
+
+test("mid-step cancel: non-interruptible finishes current step", async () => {
+  const cancellation = { cancelled: false, reason: "stop later" };
+  let snapStarted = false;
+  const dispatch: MissionToolDispatcher = async (tool) => {
+    if (tool === "ros2_camera_snapshot") {
+      snapStarted = true;
+      setTimeout(() => {
+        cancellation.cancelled = true;
+      }, 20);
+      await new Promise((r) => setTimeout(r, 80));
+      return { text: "snap ok", outputs: { ok: true } };
+    }
+    return { text: "ok" };
+  };
+  const mission: Mission = {
+    name: "snap-then-cancel",
+    steps: [
+      { id: "snap", capability: "take_snapshot" },
+      { id: "drive", capability: "drive_base", inputs: { linear_x: 0.1 } },
+    ],
+  };
+  const result = await runMission(mission, CAPS, BINDINGS, dispatch, {
+    mission_id: "mn_nonint",
+    cancellation,
+  });
+  assert.ok(snapStarted);
+  assert.equal(result.steps[0]!.status, "ok");
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.steps[1]!.status, "cancelled");
+});

package/runtime/packages/core/src/__tests__/skill-refs.test.ts

@@ -12,6 +12,7 @@ import {
 
 test("parseSkillRef: owner/skill and @pin", () => {
   assert.deepEqual(parseSkillRef("agenticros/navigate-to"), {
+    kind: "marketplace",
     marketplaceRef: "agenticros/navigate-to",
     owner: "agenticros",
     skill: "navigate-to",
@@ -22,6 +23,19 @@ test("parseSkillRef: owner/skill and @pin", () => {
   assert.equal(parseSkillRef(""), null);
 });
 
+test("parseSkillRef: npm scoped package", () => {
+  assert.deepEqual(parseSkillRef("@agenticros-skills/navigate-to"), {
+    kind: "npm",
+    npmPackage: "@agenticros-skills/navigate-to",
+    npmVersion: undefined,
+  });
+  assert.deepEqual(parseSkillRef("@agenticros-skills/find@^0.2.0"), {
+    kind: "npm",
+    npmPackage: "@agenticros-skills/find",
+    npmVersion: "^0.2.0",
+  });
+});
+
 test("parseConfig: skillRefs defaults to []", () => {
   const cfg = parseConfig({});
   assert.deepEqual(cfg.skillRefs, []);

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

@@ -16,6 +16,11 @@ export interface ExecuteExternalOptions {
   namespace?: string;
   /** Optional timeout for subscribe_once (ms). */
   timeoutMs?: number;
+  /**
+   * When aborted mid-action, call `transport.cancelActionGoal` (best-effort).
+   * Subscribe waits also reject early on abort.
+   */
+  signal?: AbortSignal;
 }
 
 export interface ExecuteExternalResult {
@@ -98,6 +103,7 @@ export async function executeExternalCapability(
   }
 
   const ns = options.namespace;
+  const signal = options.signal;
 
   try {
     if (impl.action) {
@@ -110,22 +116,46 @@ export async function executeExternalCapability(
         };
       }
       const args = buildExternalGoal(impl, inputs);
-      const result = await transport.sendActionGoal({
+      const goalPromise = 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,
-      };
+      let onAbort: (() => void) | undefined;
+      const abortPromise = signal
+        ? new Promise<never>((_, reject) => {
+            const fail = () => {
+              void transport.cancelActionGoal(action).catch(() => {});
+              reject(new Error("Action cancelled"));
+            };
+            if (signal.aborted) {
+              fail();
+              return;
+            }
+            onAbort = fail;
+            signal.addEventListener("abort", fail, { once: true });
+          })
+        : null;
+      try {
+        const result = abortPromise
+          ? await Promise.race([goalPromise, abortPromise])
+          : await goalPromise;
+        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,
+        };
+      } finally {
+        if (signal && onAbort) {
+          signal.removeEventListener("abort", onAbort);
+        }
+      }
     }
 
     if (impl.service) {
@@ -177,28 +207,40 @@ export async function executeExternalCapability(
               : 5000);
         const msg = await new Promise<Record<string, unknown>>((resolve, reject) => {
           let settled = false;
-          const timer = setTimeout(() => {
+          let sub: { unsubscribe: () => void } | undefined;
+          let onAbort: (() => void) | undefined;
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          const finish = (fn: () => void) => {
             if (settled) return;
             settled = true;
+            if (timer) clearTimeout(timer);
+            if (signal && onAbort) signal.removeEventListener("abort", onAbort);
             try {
-              sub.unsubscribe();
+              sub?.unsubscribe();
             } catch {
               /* ignore */
             }
-            reject(new Error(`Timed out waiting for message on ${topic} after ${timeout}ms`));
+            fn();
+          };
+          timer = setTimeout(() => {
+            finish(() =>
+              reject(new Error(`Timed out waiting for message on ${topic} after ${timeout}ms`)),
+            );
           }, timeout);
-          const sub = transport.subscribe(
+          onAbort = () => {
+            finish(() => reject(new Error("Subscribe cancelled")));
+          };
+          if (signal) {
+            if (signal.aborted) {
+              onAbort();
+              return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+          }
+          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>);
+              finish(() => resolve(message as Record<string, unknown>));
             },
           );
         });

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

@@ -84,13 +84,14 @@ export type {
   ExecuteExternalResult,
 } from "./external-capability.js";
 
-export { runMission } from "./mission.js";
+export { runMission, MissionStepAbortedError } from "./mission.js";
 export type {
   Mission,
   MissionStep,
   MissionResult,
   MissionStepResult,
   MissionToolDispatcher,
+  MissionDispatchContext,
   CapabilityToolBinding,
   CapabilityToolBindings,
   MissionCancellationToken,
@@ -175,6 +176,7 @@ export {
   DEFAULT_SKILLS_API,
   DEFAULT_SKILLS_CACHE_DIR,
   ensureSkillRefCached,
+  ensureNpmPackageCached,
   fetchInstallDescriptor,
   githubRepoBasename,
   parseSkillRef,

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

@@ -45,13 +45,13 @@
  *
  * What's still deferred:
  *   - Parallel step execution (today: sequential 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).
+ *   - Step-level retry / backoff (`MissionStep.retry`).
+ *   - Mid-step cancel for interruptible capabilities via AbortSignal
+ *     on the dispatcher (non-interruptible steps still finish naturally).
  *
  * See: docs/strategy-ai-agents-plus-ros.md §4 (Phase 1.c / 1.f).
  */
@@ -131,8 +131,22 @@ export interface MissionStep {
    * Optional behaviour when this step fails. Defaults to "stop".
    *   - "stop":     halt the mission, mark it failed
    *   - "continue": record the failure and run the next step anyway
+   * Applied only after retry attempts (if any) are exhausted.
    */
   on_fail?: "stop" | "continue";
+  /**
+   * Optional retry / backoff when the step errors. Default is a single
+   * attempt (`max_attempts: 1`). Retries re-invoke the same tool with
+   * the same resolved args; `on_fail` applies only after the last attempt.
+   */
+  retry?: {
+    /** Total attempts including the first (minimum 1). */
+    max_attempts: number;
+    /** Delay before the second attempt (ms). Default 0. */
+    backoff_ms?: number;
+    /** Multiply backoff after each failed attempt. Default 1. */
+    backoff_multiplier?: number;
+  };
 }
 
 /** A complete mission plan. */
@@ -180,6 +194,8 @@ export interface MissionStepResult {
   error?: string;
   /** Wall time in ms. */
   duration_ms: number;
+  /** Number of dispatcher attempts used (including the successful one). */
+  attempts?: number;
 }
 
 /** Result of a mission run. */
@@ -222,6 +238,16 @@ export interface MissionResult {
   cancellation_reason?: string;
 }
 
+/** Optional context passed to each dispatcher invocation. */
+export interface MissionDispatchContext {
+  /**
+   * AbortSignal aborted when the mission is cancelled mid-step and the
+   * capability is `interruptible`. Long-running tools should poll
+   * `signal.aborted` (or listen for `abort`) and stop cleanly.
+   */
+  signal?: AbortSignal;
+}
+
 /**
  * A dispatcher invokes a single MCP tool by name and returns:
  *   - `text`: the tool's text response (free-form, for human display)
@@ -230,12 +256,29 @@ export interface MissionResult {
  *                `{{...}}` template resolution by later steps.
  *
  * Adapters wrap their existing tool entry points to satisfy this contract.
+ * The optional third argument carries an AbortSignal for mid-step cancel.
  */
 export type MissionToolDispatcher = (
   toolName: string,
   args: Record<string, unknown>,
+  ctx?: MissionDispatchContext,
 ) => Promise<{ text: string; outputs?: Record<string, unknown>; isError?: boolean }>;
 
+/** Thrown (or returned via isError) when a tool stops due to AbortSignal. */
+export class MissionStepAbortedError extends Error {
+  constructor(message = "Step aborted") {
+    super(message);
+    this.name = "MissionStepAbortedError";
+  }
+}
+
+function isAbortError(err: unknown): boolean {
+  if (err instanceof MissionStepAbortedError) return true;
+  if (err instanceof Error && err.name === "AbortError") return true;
+  if (err instanceof Error && /aborted|cancelled/i.test(err.message)) return true;
+  return false;
+}
+
 /**
  * Capability → MCP tool mapping. Each entry says "to satisfy capability X,
  * call tool Y with these arguments". The transform receives the step's
@@ -397,6 +440,7 @@ export async function runMission(
   options?: RunMissionOptions,
 ): Promise<MissionResult> {
   const capIds = new Set(capabilities.map((c) => c.id));
+  const capById = new Map(capabilities.map((c) => [c.id, c]));
   const stepOutputs: Record<string, Record<string, unknown> | undefined> = {};
   const results: MissionStepResult[] = [];
   const t0Mission = Date.now();
@@ -551,40 +595,153 @@ export async function runMission(
       if (effective) toolArgs.robot_id = effective;
     }
 
-    try {
-      const dispatched = await dispatcher(binding.tool, toolArgs);
-      const outputs =
-        dispatched.outputs ??
-        binding.parseOutputs?.(dispatched.text) ??
-        tryParseJsonOutputs(dispatched.text);
-      stepOutputs[step.id] = outputs;
-      const status: MissionStepResult["status"] = dispatched.isError ? "error" : "ok";
-      const result: MissionStepResult = {
-        id: step.id,
-        capability: step.capability,
-        status,
-        inputs: resolvedInputs,
-        outputs,
-        message: dispatched.text,
-        ...(dispatched.isError ? { error: dispatched.text } : {}),
-        duration_ms: Date.now() - t0,
-      };
-      results.push(result);
-      emitTranscript(idx, t0, result);
-      if (status === "error" && (step.on_fail ?? "stop") === "stop") aborted = true;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      const result: MissionStepResult = {
+    const maxAttempts = Math.max(1, Math.floor(step.retry?.max_attempts ?? 1));
+    let backoffMs = Math.max(0, step.retry?.backoff_ms ?? 0);
+    const backoffMult = step.retry?.backoff_multiplier ?? 1;
+    const interruptible = capById.get(step.capability)?.interruptible === true;
+
+    let attempts = 0;
+    let lastError: string | undefined;
+    let stepCancelledMid = false;
+    let finalResult: MissionStepResult | undefined;
+
+    while (attempts < maxAttempts) {
+      attempts += 1;
+      if (attempts > 1 && backoffMs > 0) {
+        await sleep(backoffMs);
+        backoffMs = Math.max(0, Math.round(backoffMs * backoffMult));
+      }
+
+      // Mid-step cancel: abort in-flight work when interruptible.
+      const controller = new AbortController();
+      let cancelPoll: ReturnType<typeof setInterval> | undefined;
+      if (interruptible && options?.cancellation) {
+        const token = options.cancellation;
+        const maybeAbort = () => {
+          if (token.cancelled && !controller.signal.aborted) {
+            controller.abort();
+          }
+        };
+        maybeAbort();
+        cancelPoll = setInterval(maybeAbort, PAUSE_POLL_MS);
+      }
+
+      try {
+        const dispatched = await dispatcher(binding.tool, toolArgs, {
+          signal: controller.signal,
+        });
+        if (cancelPoll) clearInterval(cancelPoll);
+
+        // Cooperative cancel: tool returned after abort without throwing.
+        if (controller.signal.aborted || options?.cancellation?.cancelled) {
+          if (interruptible) {
+            stepCancelledMid = true;
+            cancelled = true;
+            finalResult = {
+              id: step.id,
+              capability: step.capability,
+              status: "cancelled",
+              inputs: resolvedInputs,
+              message: `Cancelled mid-step: ${options?.cancellation?.reason ?? "cancelled"}`,
+              duration_ms: Date.now() - t0,
+              attempts,
+            };
+            break;
+          }
+        }
+
+        const outputs =
+          dispatched.outputs ??
+          binding.parseOutputs?.(dispatched.text) ??
+          tryParseJsonOutputs(dispatched.text);
+        stepOutputs[step.id] = outputs;
+        const status: MissionStepResult["status"] = dispatched.isError ? "error" : "ok";
+        if (status === "ok") {
+          finalResult = {
+            id: step.id,
+            capability: step.capability,
+            status: "ok",
+            inputs: resolvedInputs,
+            outputs,
+            message: dispatched.text,
+            duration_ms: Date.now() - t0,
+            attempts,
+          };
+          break;
+        }
+        lastError = dispatched.text;
+        if (attempts >= maxAttempts) {
+          finalResult = {
+            id: step.id,
+            capability: step.capability,
+            status: "error",
+            inputs: resolvedInputs,
+            outputs,
+            message: dispatched.text,
+            error: dispatched.text,
+            duration_ms: Date.now() - t0,
+            attempts,
+          };
+        }
+      } catch (err) {
+        if (cancelPoll) clearInterval(cancelPoll);
+        if (isAbortError(err) || controller.signal.aborted) {
+          stepCancelledMid = true;
+          cancelled = true;
+          finalResult = {
+            id: step.id,
+            capability: step.capability,
+            status: "cancelled",
+            inputs: resolvedInputs,
+            message: `Cancelled mid-step: ${options?.cancellation?.reason ?? (err instanceof Error ? err.message : "cancelled")}`,
+            duration_ms: Date.now() - t0,
+            attempts,
+          };
+          break;
+        }
+        lastError = err instanceof Error ? err.message : String(err);
+        if (attempts >= maxAttempts) {
+          finalResult = {
+            id: step.id,
+            capability: step.capability,
+            status: "error",
+            inputs: resolvedInputs,
+            error: lastError,
+            duration_ms: Date.now() - t0,
+            attempts,
+          };
+        }
+      } finally {
+        if (cancelPoll) clearInterval(cancelPoll);
+      }
+
+      // If cancel flipped during a non-interruptible attempt, finish
+      // this step's result then stop subsequent steps at the boundary.
+      if (!interruptible && options?.cancellation?.cancelled && !stepCancelledMid) {
+        cancelled = true;
+      }
+      if (finalResult) break;
+    }
+
+    if (!finalResult) {
+      finalResult = {
         id: step.id,
         capability: step.capability,
         status: "error",
         inputs: resolvedInputs,
-        error: msg,
+        error: lastError ?? "Unknown step failure",
         duration_ms: Date.now() - t0,
+        attempts,
       };
-      results.push(result);
-      emitTranscript(idx, t0, result);
-      if ((step.on_fail ?? "stop") === "stop") aborted = true;
+    }
+
+    results.push(finalResult);
+    emitTranscript(idx, t0, finalResult);
+    if (finalResult.status === "error" && (step.on_fail ?? "stop") === "stop") {
+      aborted = true;
+    }
+    if (options?.cancellation?.cancelled) {
+      cancelled = true;
     }
   }