agenticros 0.1.17 → 0.1.19

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

@@ -0,0 +1,193 @@
+/**
+ * Multi-robot discovery — Phase 1.d "fleet awareness on the wire".
+ *
+ * Configuration tells the gateway what robots the user wants to talk to.
+ * The transport tells the gateway what's actually on the wire right now.
+ * Discovery is the bridge: scan published ROS2 topics, infer robot
+ * namespaces from `<ns>/cmd_vel` patterns, cross-reference against the
+ * configured robot list, and surface three categories:
+ *
+ *   1. configured_online   — in config AND seen on the wire
+ *   2. configured_offline  — in config but NOT seen on the wire
+ *   3. unknown_detected    — on the wire but NOT in config
+ *
+ * The agent uses this to answer questions like "which robots can I talk
+ * to right now?" without forcing the user to hand-edit
+ * `~/.agenticros/config.json` every time a robot joins the network.
+ *
+ * Persistence is intentionally OUT of scope here: discovery is read-only.
+ * Writing newly-detected robots into the user's config is a separate
+ * UX decision handled by the CLI / OpenClaw config UI on top of this
+ * function.
+ *
+ * ## Detection signal
+ *
+ * `<ns>/cmd_vel` (the velocity command topic) is the canonical signal —
+ * a robot that can be driven publishes/subscribes there. Other topics
+ * like `<ns>/odom`, `<ns>/joint_states`, and `<ns>/camera/...` corroborate
+ * the same `<ns>`; we surface them as `topicCount` so consumers can
+ * gauge how "alive" the namespace looks.
+ *
+ * The unnamespaced `/cmd_vel` topic (default namespace, common in
+ * simulation) is detected as id="" — consumers can render it as
+ * "default robot" or similar.
+ *
+ * ## Namespace rewrite
+ *
+ * `ros2_publish` rewrites a UUID-shaped namespace like
+ * `3946b404-c33e-...` into `robot3946b404c33e...` (strip dashes,
+ * prefix with "robot") because most robot firmware expects the
+ * dashless form. Discovery applies the same rewrite when matching
+ * configured robots against detected namespaces, so a UUID-style
+ * config entry still matches the `/robot<no-dashes>/cmd_vel` topic
+ * the robot is actually publishing on.
+ */
+
+import type { AgenticROSConfig } from "./config.js";
+import type { ResolvedRobot } from "./robots.js";
+import { listRobots } from "./robots.js";
+import type { TopicInfo } from "./transport/types.js";
+
+/** One robot inferred from the topic graph. */
+export interface DetectedRobot {
+  /** The namespace segment, e.g. "robot3946b...". Empty string = default namespace. */
+  id: string;
+  /** The full cmd_vel topic name we saw — e.g. "/robot3946b.../cmd_vel". */
+  cmdVelTopic: string;
+  /**
+   * Total topics under `/<id>/`, INCLUDING the cmd_vel topic itself.
+   * A topicCount of 1 means the robot is "barely there" (just cmd_vel,
+   * no odom / joint_states / camera etc.); higher counts corroborate
+   * that the namespace is actually a live robot, not a stale advert.
+   * Always 0 for the unnamespaced default robot (id="").
+   */
+  topicCount: number;
+  /**
+   * The matching `robot.id` from `config.robots` (or the legacy fallback)
+   * when this detected namespace maps to a configured robot, otherwise
+   * `null`. Matching uses the same UUID→robot-no-dashes rewrite as the
+   * publish path.
+   */
+  configuredRobotId: string | null;
+}
+
+/** Result of a discovery pass. */
+export interface RobotDiscoveryResult {
+  /** Every robot inferred from the topic graph, with config match annotations. */
+  detected: DetectedRobot[];
+  /** Configured robots that ARE present on the wire right now. */
+  configured_online: ResolvedRobot[];
+  /** Configured robots that are NOT present on the wire right now. */
+  configured_offline: ResolvedRobot[];
+  /** Detected robots that have no matching config entry — candidates to add. */
+  unknown_detected: DetectedRobot[];
+  /** Total topics scanned (echoed for diagnostics). */
+  total_topics: number;
+}
+
+/**
+ * Apply the same UUID→robot-no-dashes rewrite as `ros2_publish` uses
+ * when normalising a `/<ns>/cmd_vel` target.
+ *
+ * `""` stays `""` (default namespace). Namespaces that already start
+ * with "robot" are returned unchanged.
+ */
+export function effectiveCmdVelNamespace(robotNamespace: string): string {
+  const ns = robotNamespace.trim();
+  if (ns === "") return "";
+  if (ns.toLowerCase().startsWith("robot")) return ns;
+  return `robot${ns.replace(/-/g, "")}`;
+}
+
+/**
+ * Find every robot-shaped namespace in a topic list.
+ *
+ * Detection rule: any `/<seg>/cmd_vel` topic implies a robot with
+ * namespace `<seg>`. The unnamespaced `/cmd_vel` topic registers the
+ * empty namespace (id=""). Topic count under each namespace is
+ * accumulated so consumers can rank by liveness.
+ *
+ * The returned `DetectedRobot.configuredRobotId` is always `null` here —
+ * call `discoverRobots()` (which wraps this function) to annotate with
+ * config matches.
+ */
+export function detectRobotsFromTopics(topics: TopicInfo[]): DetectedRobot[] {
+  const byNs = new Map<string, { cmdVelTopic: string; topicCount: number }>();
+
+  for (const t of topics) {
+    // Match /<seg>/cmd_vel exactly — sub-namespaces would imply a more
+    // complex robot graph than this v1 wants to handle.
+    const m = t.name.match(/^\/([^/]+)\/cmd_vel$/);
+    if (m) {
+      const ns = m[1]!;
+      if (!byNs.has(ns)) byNs.set(ns, { cmdVelTopic: t.name, topicCount: 0 });
+    } else if (t.name === "/cmd_vel" && !byNs.has("")) {
+      byNs.set("", { cmdVelTopic: "/cmd_vel", topicCount: 0 });
+    }
+  }
+
+  // Count topics under each detected namespace. Empty-namespace robots
+  // (default) intentionally don't accumulate counts — every topic in
+  // the system would otherwise "belong" to them, which is misleading.
+  for (const t of topics) {
+    for (const [ns, info] of byNs) {
+      if (ns === "") continue;
+      if (t.name.startsWith(`/${ns}/`)) {
+        info.topicCount += 1;
+      }
+    }
+  }
+
+  return Array.from(byNs.entries()).map(([id, info]) => ({
+    id,
+    cmdVelTopic: info.cmdVelTopic,
+    topicCount: info.topicCount,
+    configuredRobotId: null,
+  }));
+}
+
+/**
+ * Top-level discovery: detect robots on the wire, match against the
+ * configured robot list, and classify into online / offline / unknown.
+ *
+ * Pure function — feed it the topic list and the config, get a result
+ * back. No transport access here; adapters wrap this with a call to
+ * `transport.listTopics()`.
+ */
+export function discoverRobots(
+  topics: TopicInfo[],
+  config: AgenticROSConfig,
+): RobotDiscoveryResult {
+  const detected = detectRobotsFromTopics(topics);
+  const configured = listRobots(config);
+
+  // Map effective-namespace → configured robot for O(1) lookup.
+  const effToCfg = new Map<string, ResolvedRobot>();
+  for (const r of configured) {
+    effToCfg.set(effectiveCmdVelNamespace(r.namespace), r);
+  }
+
+  const annotated = detected.map((d) => {
+    const cfg = effToCfg.get(d.id);
+    return cfg
+      ? { ...d, configuredRobotId: cfg.id }
+      : { ...d, configuredRobotId: null };
+  });
+
+  const detectedIds = new Set(annotated.map((d) => d.id));
+  const configured_online = configured.filter((r) =>
+    detectedIds.has(effectiveCmdVelNamespace(r.namespace)),
+  );
+  const configured_offline = configured.filter(
+    (r) => !detectedIds.has(effectiveCmdVelNamespace(r.namespace)),
+  );
+  const unknown_detected = annotated.filter((d) => d.configuredRobotId === null);
+
+  return {
+    detected: annotated,
+    configured_online,
+    configured_offline,
+    unknown_detected,
+    total_topics: topics.length,
+  };
+}

package/runtime/packages/core/src/find-robots-for.ts

@@ -0,0 +1,164 @@
+/**
+ * `findRobotsFor` — Phase 1.e capability-aware robot filter.
+ *
+ * Given a (capability?, kind?, online?) query, returns the configured
+ * robots that match, ranked best-first. This is the resolver behind the
+ * `ros2_find_robots_for` MCP tool — adapters call it from `tools.ts`
+ * with the live online-set computed from a topic scan (or `undefined`
+ * when `online` isn't being filtered, so we don't pay for the scan).
+ *
+ * Filter semantics:
+ *  - `capability` — keep robots whose per-robot allowlist
+ *    (`config.robots[i].capabilities`) includes the verb, OR (when no
+ *    allowlist is set) whose gateway's global capability registry
+ *    includes it. The global path is the common case — every robot
+ *    today exposes the same builtin + skill-declared capabilities. The
+ *    per-robot allowlist exists for heterogeneous fleets where (e.g.)
+ *    only one robot has the `arm_skill` loaded.
+ *  - `kind` — exact match on `robot.kind` (case-insensitive). Use
+ *    "amr" / "arm" / "drone" / "rover" by convention but any string is
+ *    accepted by the schema.
+ *  - `online` — `true` keeps only robots whose id is in `onlineIds`;
+ *    `false` keeps only robots NOT in `onlineIds`; `undefined` skips
+ *    this filter entirely. The adapter is responsible for populating
+ *    `onlineIds` from the live topic graph (typically via
+ *    `discoverRobots()`) before calling this — core doesn't touch the
+ *    transport.
+ *
+ * Ranking (highest score first):
+ *   +2  online (when query.online is true)
+ *   +1  per-robot capabilities allowlist included the requested verb
+ *       (an explicit "I support this" beats a global-registry inference)
+ *   +0  default tier
+ *
+ * Ties broken by config declaration order (stable).
+ *
+ * Why not a full LLM-style scoring function? Phase 1.e's goal is
+ * deterministic and explainable — an agent calling `find_robots_for`
+ * wants a list it can plan against, not a relevance heuristic. The
+ * +1/+2 deltas are enough to surface a perfect match above an
+ * inherited one without inventing fuzzy matching.
+ */
+
+import type { AgenticROSConfig } from "./config.js";
+import { listAllCapabilities, type Capability } from "./capabilities.js";
+import { listRobots, type ResolvedRobot } from "./robots.js";
+
+/** Query input to `findRobotsFor`. All fields optional → returns every robot. */
+export interface FindRobotsForQuery {
+  /** Capability id (e.g. `follow_person`, `find_object`). Case-sensitive — match the registry. */
+  capability?: string;
+  /** Robot kind (e.g. `amr`, `arm`, `drone`). Case-insensitive. */
+  kind?: string;
+  /** When set, restrict to online (true) or offline (false) robots. */
+  online?: boolean;
+}
+
+/** One entry in the find-robots-for result. */
+export interface FindRobotsForMatch {
+  robot: ResolvedRobot;
+  /** True when the capability filter was satisfied by an explicit per-robot allowlist. */
+  matched_capability_explicitly: boolean;
+  /**
+   * True when this robot is in the caller-supplied online set, false when
+   * not, and `null` when the caller didn't provide an online set at all
+   * (so we can't say either way).
+   */
+  online: boolean | null;
+  /** Sort key — higher = better match. See module header for the formula. */
+  score: number;
+}
+
+/** Result envelope. */
+export interface FindRobotsForResult {
+  query: FindRobotsForQuery;
+  total: number;
+  /** Best-matching robots first. */
+  robots: FindRobotsForMatch[];
+}
+
+/**
+ * Run the filter+rank against the configured fleet.
+ *
+ * `onlineIds` is optional. When omitted AND `query.online` is set, this
+ * throws — the adapter MUST resolve the live set before calling this so
+ * the core stays transport-agnostic.
+ *
+ * The match list is stable across calls with the same input (no
+ * non-determinism, no time-of-day effects).
+ */
+export function findRobotsFor(
+  config: AgenticROSConfig,
+  query: FindRobotsForQuery,
+  onlineIds?: ReadonlySet<string>,
+): FindRobotsForResult {
+  if (query.online !== undefined && onlineIds === undefined) {
+    throw new Error(
+      "findRobotsFor: query.online was set but onlineIds was not provided. " +
+        "Call discoverRobots() first and pass configured_online ids.",
+    );
+  }
+
+  // Resolve the global capability registry once — used as the fallback
+  // when a robot doesn't declare its own per-robot allowlist.
+  const globalCapIds: ReadonlySet<string> = new Set(
+    listAllCapabilities(config).map((c: Capability) => c.id),
+  );
+
+  const wantedKind = query.kind?.trim().toLowerCase();
+  const wantedCap = query.capability?.trim();
+
+  const fleet = listRobots(config);
+  const matches: FindRobotsForMatch[] = [];
+
+  for (const robot of fleet) {
+    // kind filter
+    if (wantedKind && robot.kind.toLowerCase() !== wantedKind) continue;
+
+    // capability filter
+    let matchedExplicitly = false;
+    if (wantedCap) {
+      const allowlist = robot.capabilities;
+      if (allowlist) {
+        if (!allowlist.includes(wantedCap)) continue;
+        matchedExplicitly = true;
+      } else {
+        // No per-robot allowlist → fall back to the gateway-wide
+        // registry. This is the common case today.
+        if (!globalCapIds.has(wantedCap)) continue;
+      }
+    }
+
+    // online filter
+    let isOnline: boolean | null = null;
+    if (onlineIds) {
+      isOnline = onlineIds.has(robot.id);
+      if (query.online === true && !isOnline) continue;
+      if (query.online === false && isOnline) continue;
+    }
+
+    let score = 0;
+    if (matchedExplicitly) score += 1;
+    if (query.online === true && isOnline) score += 2;
+    // Reward online robots even when the user didn't filter for it —
+    // an agent picking a robot for an action almost always wants the
+    // one currently reachable.
+    if (query.online === undefined && isOnline === true) score += 1;
+
+    matches.push({ robot, matched_capability_explicitly: matchedExplicitly, online: isOnline, score });
+  }
+
+  // Stable sort: higher score first, tie-broken by original config
+  // order (which is what listRobots() returned).
+  matches.sort((a, b) => b.score - a.score);
+
+  return {
+    query: {
+      ...(wantedCap ? { capability: wantedCap } : {}),
+      ...(wantedKind ? { kind: wantedKind } : {}),
+      ...(query.online !== undefined ? { online: query.online } : {}),
+    },
+    total: matches.length,
+    robots: matches,
+  };
+}

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

@@ -2,7 +2,7 @@
  * @agenticros/core — Platform-agnostic ROS2 transport, config, and utilities.
  */
 
-export type { AgenticROSConfig } from "./config.js";
+export type { AgenticROSConfig, RobotTransportOverride } from "./config.js";
 export {
   AgenticROSConfigSchema,
   parseConfig,
@@ -52,3 +52,69 @@ export type {
   RecallInput,
   ForgetInput,
 } from "./memory/index.js";
+
+export {
+  BUILTIN_CAPABILITIES,
+  readSkillCapabilities,
+  listAllCapabilities,
+} from "./capabilities.js";
+export type {
+  Capability,
+  CapabilityField,
+  CapabilityImplementation,
+  CapabilitySource,
+} from "./capabilities.js";
+
+export { runMission } from "./mission.js";
+export type {
+  Mission,
+  MissionStep,
+  MissionResult,
+  MissionStepResult,
+  MissionToolDispatcher,
+  CapabilityToolBinding,
+  CapabilityToolBindings,
+  MissionCancellationToken,
+  MissionTranscriptEntry,
+  MissionTranscriptSink,
+  RunMissionOptions,
+} from "./mission.js";
+
+export {
+  MissionRegistry,
+  generateMissionId,
+  missionTranscriptNamespace,
+} from "./mission-registry.js";
+export type { MissionRegistryEntry } from "./mission-registry.js";
+
+export { createMemoryTranscriptSink } from "./mission-transcript-sink.js";
+
+export { compileGoalToMission } from "./planner/index.js";
+export type { PlannerResult, PlannerCandidate } from "./planner/index.js";
+
+export {
+  listRobots,
+  resolveRobot,
+  resolveRobotFromArgs,
+  getActiveRobotId,
+  getTransportConfigForRobot,
+  hasRobotTransportOverride,
+} from "./robots.js";
+export type { ResolvedRobot, RobotSensors } from "./robots.js";
+
+export {
+  detectRobotsFromTopics,
+  discoverRobots,
+  effectiveCmdVelNamespace,
+} from "./discovery.js";
+export type { DetectedRobot, RobotDiscoveryResult } from "./discovery.js";
+
+export { findRobotsFor } from "./find-robots-for.js";
+export type {
+  FindRobotsForQuery,
+  FindRobotsForMatch,
+  FindRobotsForResult,
+} from "./find-robots-for.js";
+
+export { TransportPool, TRANSPORT_POOL_GLOBAL_KEY } from "./transport-pool.js";
+export type { TransportFactory } from "./transport-pool.js";

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

@@ -0,0 +1,142 @@
+/**
+ * MissionRegistry — Phase 1.f in-process tracker for active missions.
+ *
+ * Each adapter (Claude Code MCP server, OpenClaw plugin, Gemini CLI)
+ * keeps a module-level registry. When `run_mission` starts, the adapter
+ * registers a fresh cancellation token under a unique `mission_id` and
+ * returns the id in the tool response. A sibling `mission_cancel` tool
+ * call then looks up the token by id and flips `cancelled = true` — the
+ * mission runner picks that up at the next step boundary and stops
+ * gracefully.
+ *
+ * Lifetime semantics:
+ *  - `register()` returns the cancellation token AND a `dispose()`
+ *    callback the caller is expected to invoke in a `finally` block
+ *    once the mission ends (regardless of outcome). Disposal removes
+ *    the entry so a subsequent cancel doesn't silently target a
+ *    completed mission and the in-memory map stays small.
+ *  - `cancel()` is idempotent — calling it on a missing id returns
+ *    `{ found: false }`; calling it twice on the same id is a no-op
+ *    after the first.
+ *
+ * Why in-process (not cross-process)? Cancellation is fundamentally
+ * "stop the dispatcher I'm running"; that dispatcher is local to the
+ * adapter process. Cross-agent coordination is Phase 4. The transcript
+ * subsystem (memory) handles the "different agent reads what I did"
+ * story orthogonally.
+ */
+
+import type { MissionCancellationToken } from "./mission.js";
+
+/** One registered mission. */
+export interface MissionRegistryEntry {
+  mission_id: string;
+  /** Adapter-supplied label for diagnostics (e.g. mission.name). */
+  name?: string;
+  /** ms since epoch when the mission was registered. */
+  started_at: number;
+  /** The token the mission runner reads each step. */
+  cancellation: MissionCancellationToken;
+}
+
+/**
+ * Generate a stable, URL-safe mission identifier.
+ *
+ * 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`.
+ */
+export function generateMissionId(): string {
+  const g = globalThis as { crypto?: { randomUUID?: () => string } };
+  if (g.crypto?.randomUUID) return `mn_${g.crypto.randomUUID()}`;
+  const a = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, "0");
+  const b = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, "0");
+  const c = Date.now().toString(16);
+  return `mn_${a}${b}${c}`;
+}
+
+/**
+ * Compute the canonical memory namespace for a mission's transcripts.
+ *
+ * The convention is `mission:<id>` so a downstream agent can recall
+ * every step the first agent ran via
+ * `memory_recall({ namespace: "mission:<id>", query: "" })`. This lives
+ * here (not in the memory module) because the adapter's transcript
+ * sink uses it and we want exactly one source of truth.
+ */
+export function missionTranscriptNamespace(missionId: string): string {
+  return `mission:${missionId}`;
+}
+
+export class MissionRegistry {
+  private readonly entries = new Map<string, MissionRegistryEntry>();
+
+  /**
+   * Register a fresh mission, returning the entry (with the
+   * cancellation token to hand to `runMission`) and a `dispose` hook
+   * to invoke when the mission ends. The id is caller-supplied so
+   * adapters can echo it in the tool response before this point.
+   */
+  register(missionId: string, opts?: { name?: string }): {
+    entry: MissionRegistryEntry;
+    dispose: () => void;
+  } {
+    const entry: MissionRegistryEntry = {
+      mission_id: missionId,
+      name: opts?.name,
+      started_at: Date.now(),
+      cancellation: { cancelled: false },
+    };
+    this.entries.set(missionId, entry);
+    return {
+      entry,
+      dispose: () => {
+        // Only remove if we're disposing the same entry — guards against
+        // a race where the same id is re-registered between dispose calls
+        // (unlikely but cheap to defend against).
+        if (this.entries.get(missionId) === entry) this.entries.delete(missionId);
+      },
+    };
+  }
+
+  /**
+   * Flip the cancellation token for the named mission.
+   *
+   * Returns `{ found: true }` when the mission existed (whether it was
+   * already cancelled or not), `{ found: false }` when the id is
+   * unknown (e.g. mission already finished + disposed).
+   */
+  cancel(missionId: string, reason?: string): { found: boolean; alreadyCancelled: boolean } {
+    const entry = this.entries.get(missionId);
+    if (!entry) return { found: false, alreadyCancelled: false };
+    const alreadyCancelled = entry.cancellation.cancelled === true;
+    entry.cancellation.cancelled = true;
+    if (reason !== undefined) entry.cancellation.reason = reason;
+    return { found: true, alreadyCancelled };
+  }
+
+  /** True when the named mission is currently registered. */
+  has(missionId: string): boolean {
+    return this.entries.has(missionId);
+  }
+
+  /**
+   * Snapshot of the active mission set (for diagnostics / mission_list
+   * tools down the road). Returns a shallow copy so callers can't
+   * mutate internal state.
+   */
+  list(): MissionRegistryEntry[] {
+    return [...this.entries.values()].map((e) => ({
+      mission_id: e.mission_id,
+      name: e.name,
+      started_at: e.started_at,
+      cancellation: { ...e.cancellation },
+    }));
+  }
+
+  /** Test-only: drop every registered mission. */
+  _clear(): void {
+    this.entries.clear();
+  }
+}

package/runtime/packages/core/src/mission-transcript-sink.ts

@@ -0,0 +1,81 @@
+/**
+ * Memory-backed mission transcript sink — Phase 1.f wiring.
+ *
+ * `createMemoryTranscriptSink(memory, missionId)` returns a
+ * `MissionTranscriptSink` the adapter hands to `runMission`. Each
+ * step's `MissionTranscriptEntry` is serialised to JSON and persisted
+ * via the shared `MemoryProvider` under the canonical
+ * `mission:<id>` namespace.
+ *
+ * Why JSON content (and not the structured `MemoryRecord` fields):
+ * `MemoryProvider.remember` only takes `content: string` (plus
+ * optional tags/path). We pack the full step snapshot into `content`
+ * so a downstream agent can `JSON.parse(record.content)` after
+ * `memory_recall(namespace="mission:<id>")`. Tags are used as
+ * coarse-grained filters (e.g. "step:ok" vs "step:error") for
+ * future status queries.
+ *
+ * The returned sink is best-effort by contract — `runMission` already
+ * swallows thrown errors, but we also defensively catch the await so a
+ * mem0 outage never propagates back into the run loop.
+ */
+
+import type { MemoryProvider } from "./memory/index.js";
+import type { MissionTranscriptSink, MissionTranscriptEntry } from "./mission.js";
+import { missionTranscriptNamespace } from "./mission-registry.js";
+
+/**
+ * Build a transcript sink that writes each step's entry to memory.
+ *
+ * @param memory      Active memory provider (caller has already
+ *                    confirmed `config.memory.enabled === true`).
+ * @param missionId   Mission identifier. Surfaced as the namespace
+ *                    and also embedded in the content for grep-ability.
+ */
+export function createMemoryTranscriptSink(
+  memory: MemoryProvider,
+  missionId: string,
+): MissionTranscriptSink {
+  const namespace = missionTranscriptNamespace(missionId);
+  return async (entry: MissionTranscriptEntry): Promise<void> => {
+    try {
+      const content = JSON.stringify({
+        // Echo mission_id in the payload too — recall() returns the
+        // content blob; mission_id in the namespace might be lost if
+        // the caller scopes their recall differently.
+        mission_id: entry.mission_id || missionId,
+        mission_name: entry.mission_name,
+        adapter: entry.adapter,
+        robot_id: entry.robot_id,
+        started_at: entry.started_at,
+        step_index: entry.step_index,
+        step_total: entry.step_total,
+        step: {
+          id: entry.result.id,
+          capability: entry.result.capability,
+          status: entry.result.status,
+          inputs: entry.result.inputs,
+          outputs: entry.result.outputs,
+          message: entry.result.message,
+          error: entry.result.error,
+          duration_ms: entry.result.duration_ms,
+        },
+      });
+      // Tags are deliberately stable + greppable so a future
+      // `memory_recall(tags=…)` can filter to "every cancelled step"
+      // or "every step that touched capability=drive_base".
+      await memory.remember({
+        namespace,
+        content,
+        tags: [
+          "mission_transcript",
+          `step:${entry.result.status}`,
+          `capability:${entry.result.capability}`,
+        ],
+        path: `${missionId}/${String(entry.step_index).padStart(3, "0")}-${entry.result.id}`,
+      });
+    } catch {
+      // Best-effort: transcript loss must NEVER abort the mission.
+    }
+  };
+}