agent-security-lens 0.1.0

package/src/observations/observation-rules.mjs

@@ -0,0 +1,157 @@
+const OBSERVATION_RULES = {
+  "mcp-stdio-process": {
+    id: "obs-mcp-stdio-process",
+    title: "MCP stdio process configured",
+    category: "execution-risk",
+    severity: "high",
+    confidence: 0.9,
+    permissions: ["subprocess-spawn", "mcp-tool-access"],
+    why_it_matters: "This MCP configuration starts a local process. The agent can delegate tool calls to that process.",
+    recommended_actions: [
+      "Verify the MCP command and package source.",
+      "Pin package versions instead of using moving tags."
+    ],
+    recommended_alternatives: [
+      "Use a verified local MCP server with a pinned version."
+    ],
+    migration_instruction: "Replace moving MCP commands with pinned package versions and disable unused MCP servers.",
+    supersedes: ["mcp-stdio-process-server"]
+  },
+  "mcp-remote-endpoint": {
+    id: "obs-mcp-remote-endpoint",
+    title: "Remote MCP endpoint configured",
+    category: "remote-access-risk",
+    severity: "medium",
+    confidence: 0.86,
+    permissions: ["network-access", "external-endpoint", "mcp-tool-access"],
+    why_it_matters: "Remote MCP endpoints can provide tools or receive delegated tool calls from the agent environment.",
+    recommended_actions: [
+      "Verify the remote MCP owner.",
+      "Restrict exposed tools if filtering is supported."
+    ],
+    recommended_alternatives: [
+      "Use a local pinned MCP server for sensitive workspaces."
+    ],
+    migration_instruction: "Disable remote MCP endpoints for sensitive workspaces or replace them with local pinned MCP servers.",
+    supersedes: ["mcp-remote-endpoint"]
+  },
+  "mcp-filesystem-capability": {
+    id: "obs-mcp-filesystem-capability",
+    title: "Filesystem MCP capability configured",
+    category: "data-exposure-risk",
+    severity: "high",
+    confidence: 0.88,
+    permissions: ["filesystem-read", "filesystem-write", "mcp-tool-access"],
+    why_it_matters: "Filesystem MCP tools can allow the agent to read or modify local files through tool calls.",
+    recommended_actions: [
+      "Limit filesystem access to a dedicated workspace.",
+      "Disable write-capable filesystem tools unless required."
+    ],
+    recommended_alternatives: [
+      "Use read-only filesystem tooling for inspection tasks."
+    ],
+    migration_instruction: "Replace broad filesystem MCP access with workspace-scoped or read-only access.",
+    supersedes: ["mcp-filesystem-write"]
+  },
+  "remote-trigger-config": {
+    id: "obs-remote-trigger-config",
+    title: "Remote trigger channel configured",
+    category: "remote-access-risk",
+    severity: "medium",
+    confidence: 0.84,
+    permissions: ["remote-trigger", "credential-access"],
+    why_it_matters: "Remote trigger channels can start or influence agent sessions. Policies and allowlists determine who can reach the agent.",
+    recommended_actions: [
+      "Set explicit allowlists for remote users or groups.",
+      "Disable remote channels for sensitive workspaces."
+    ],
+    recommended_alternatives: [
+      "Use local-only mode for sensitive workflows."
+    ],
+    migration_instruction: "Set explicit allowFrom values and disable open group triggers.",
+    supersedes: ["openclaw-remote-channel-policy", "hermes-gateway-trigger"]
+  },
+  "scheduled-agent-execution": {
+    id: "obs-scheduled-agent-execution",
+    title: "Scheduled agent execution configured",
+    category: "persistence-automation-risk",
+    severity: "medium",
+    confidence: 0.84,
+    permissions: ["scheduled-execution"],
+    why_it_matters: "Scheduled tasks can start agent behavior later, when the user is not actively reviewing each action.",
+    recommended_actions: [
+      "Review scheduled task prompts and allowed tools.",
+      "Disable unused scheduled tasks."
+    ],
+    recommended_alternatives: [
+      "Use manual run mode for sensitive workflows."
+    ],
+    migration_instruction: "Disable scheduled execution until task prompts and tool permissions are reviewed.",
+    supersedes: ["openclaw-scheduled-task"]
+  },
+  "credential-reference": {
+    id: "obs-credential-reference",
+    title: "Credential reference in structured config",
+    category: "data-exposure-risk",
+    severity: "medium",
+    confidence: 0.82,
+    permissions: ["credential-access", "env-read"],
+    why_it_matters: "Structured config references credentials that may be inherited by tools, skills or MCP servers.",
+    recommended_actions: [
+      "Use scoped credentials for agent environments.",
+      "Remove unused secrets before running the agent."
+    ],
+    recommended_alternatives: [
+      "Use a dedicated low-privilege token for this agent."
+    ],
+    migration_instruction: "Move high-privilege secrets out of the agent environment and use scoped replacement tokens.",
+    supersedes: ["core-env-reference"]
+  }
+};
+
+function previewValue(value) {
+  if (typeof value === "string") return value;
+  return JSON.stringify(value).slice(0, 240);
+}
+
+export function findingsFromObservations({ observations, profileIds }) {
+  const seen = new Set();
+  const findings = [];
+
+  for (const observation of observations) {
+    const rule = OBSERVATION_RULES[observation.type];
+    const key = `${rule.id}:${observation.path}:${observation.json_path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    findings.push({
+      id: `${rule.id}:${observation.path}:${observation.json_path}`,
+      rule_id: rule.id,
+      title: rule.title,
+      category: rule.category,
+      severity: rule.severity,
+      confidence: rule.confidence,
+      permissions: rule.permissions,
+      profile_ids: profileIds,
+      why_it_matters: rule.why_it_matters,
+      recommended_actions: rule.recommended_actions,
+      recommended_alternatives: rule.recommended_alternatives,
+      migration_instruction: rule.migration_instruction,
+      supersedes: rule.supersedes || [],
+      evidence: {
+        path: observation.path,
+        line: observation.line || 1,
+        preview: `${observation.json_path}: ${previewValue(observation.value)}`
+      },
+      evidence_items: [
+        {
+          path: observation.path,
+          line: observation.line || 1,
+          preview: `${observation.json_path}: ${previewValue(observation.value)}`
+        }
+      ]
+    });
+  }
+
+  return findings;
+}

package/src/profiles/load-profiles.mjs

@@ -0,0 +1,130 @@
+import { access, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..", "..");
+
+const PROFILE_FILES = [
+  "profiles/generic-agent/profile.json",
+  "profiles/openclaw-like/profile.json",
+  "profiles/hermes-like/profile.json",
+  "profiles/mcp-server/profile.json",
+  "profiles/skill-runtime/profile.json"
+];
+
+export async function loadProfiles() {
+  const profiles = [];
+  for (const file of PROFILE_FILES) {
+    const content = await readFile(join(ROOT, file), "utf8");
+    profiles.push(JSON.parse(content));
+  }
+  return profiles;
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function detectProfile(root) {
+  const lowerRoot = root.toLowerCase();
+  if (lowerRoot.includes(".openclaw")) {
+    return {
+      profileId: "openclaw-like",
+      signals: [{ type: "path-name", value: ".openclaw" }]
+    };
+  }
+  if (lowerRoot.includes(".hermes")) {
+    return {
+      profileId: "hermes-like",
+      signals: [{ type: "path-name", value: ".hermes" }]
+    };
+  }
+
+  const hermesHints = [
+    ".hermes",
+    ".hermes/config.json",
+    ".hermes/config.yaml",
+    "optional-mcps",
+    "optional-skills",
+    "gateway",
+    "cron",
+    "memory",
+    "skills/openclaw-imports"
+  ];
+  for (const hint of hermesHints) {
+    if (await exists(join(root, hint))) {
+      return {
+        profileId: "hermes-like",
+        signals: [{ type: "path-exists", value: hint }]
+      };
+    }
+  }
+
+  const openclawHints = [
+    "openclaw.json",
+    ".openclaw/openclaw.json",
+    "SOUL.md",
+    "TOOLS.md",
+    "workspace/skills"
+  ];
+  for (const hint of openclawHints) {
+    if (await exists(join(root, hint))) {
+      return {
+        profileId: "openclaw-like",
+        signals: [{ type: "path-exists", value: hint }]
+      };
+    }
+  }
+
+  return {
+    profileId: "generic-agent",
+    signals: []
+  };
+}
+
+function expandProfile(profiles, profileId) {
+  const profile = profiles.find((item) => item.id === profileId);
+  if (!profile) {
+    throw new Error(`Unknown profile: ${profileId}`);
+  }
+  const expanded = [profile];
+  for (const parentId of profile.extends || []) {
+    const parent = profiles.find((item) => item.id === parentId);
+    if (parent && !expanded.some((item) => item.id === parent.id)) {
+      expanded.push(parent);
+    }
+  }
+  return expanded;
+}
+
+export async function resolveProfileSelection({ profiles, requestedProfile, root }) {
+  if (requestedProfile) {
+    return {
+      mode: "requested",
+      requested_profile: requestedProfile,
+      selected_profile: requestedProfile,
+      detection_signals: [{ type: "cli-profile", value: requestedProfile }],
+      profiles: expandProfile(profiles, requestedProfile)
+    };
+  }
+
+  const detected = await detectProfile(root);
+  return {
+    mode: "autodetected",
+    requested_profile: null,
+    selected_profile: detected.profileId,
+    detection_signals: detected.signals,
+    profiles: expandProfile(profiles, detected.profileId)
+  };
+}
+
+export async function selectProfiles({ profiles, requestedProfile, root }) {
+  const selection = await resolveProfileSelection({ profiles, requestedProfile, root });
+  return selection.profiles;
+}

package/src/recommendations/component-alternative-graph.mjs

@@ -0,0 +1,94 @@
+function activeAt(edge, at) {
+  const timestamp = new Date(at).getTime();
+  const starts = new Date(edge.valid_from).getTime();
+  const ends = edge.valid_until ? new Date(edge.valid_until).getTime() : Number.POSITIVE_INFINITY;
+  return Number.isFinite(timestamp) && timestamp >= starts && timestamp <= ends;
+}
+
+function indexedComponents(components = []) {
+  return new Map(components.map((component) => [component.id, component]));
+}
+
+function isStrictReviewed(component) {
+  return (
+    component?.intelligence_state === "strict_reviewed"
+    && component?.publication_gate?.strict_pass === true
+  );
+}
+
+export function findComponentAlternatives({
+  componentId,
+  graph = {},
+  components = [],
+  at = new Date().toISOString(),
+  includePeers = false
+}) {
+  if (!componentId) return [];
+  const policy = graph.policy || {};
+  const allowedRelationships = new Set(policy.agent_facing_relationships || []);
+  const minimumConfidence = Number(policy.minimum_confidence ?? 1);
+  const minimumSafetyDelta = Number(policy.minimum_safety_delta ?? 0);
+  const componentIndex = indexedComponents(components);
+  const source = componentIndex.get(componentId);
+
+  return (graph.edges || [])
+    .filter((edge) => edge.source_component_id === componentId)
+    .filter((edge) => edge.status === "active" && activeAt(edge, at))
+    .filter((edge) => includePeers || allowedRelationships.has(edge.relationship_type))
+    .filter((edge) => includePeers || edge.confidence >= minimumConfidence)
+    .filter((edge) => includePeers || edge.safety_delta >= minimumSafetyDelta)
+    .map((edge) => {
+      const target = componentIndex.get(edge.target_component_id);
+      return { edge, source, target };
+    })
+    .filter(({ source: sourceComponent, target }) =>
+      isStrictReviewed(sourceComponent)
+      && isStrictReviewed(target)
+      && sourceComponent.type === target.type
+    )
+    .sort((left, right) =>
+      right.edge.safety_delta - left.edge.safety_delta
+      || right.edge.confidence - left.edge.confidence
+      || Number(right.target.trust_score || 0) - Number(left.target.trust_score || 0)
+    )
+    .map(({ edge, target }) => ({
+      id: edge.id,
+      component_id: target.id,
+      name: target.name,
+      component_type: target.type,
+      relationship_type: edge.relationship_type,
+      confidence: edge.confidence,
+      safety_delta: edge.safety_delta,
+      trust_score: target.trust_score,
+      decision: target.decision,
+      reason: edge.reason,
+      shared_capabilities: edge.shared_capabilities,
+      unsupported_source_capabilities: edge.unsupported_source_capabilities,
+      conditions: edge.conditions,
+      migration: edge.migration,
+      evidence: edge.evidence,
+      valid_from: edge.valid_from,
+      valid_until: edge.valid_until
+    }));
+}
+
+export function alternativeCoverageFor({ componentId, graph = {}, alternatives = [] }) {
+  const gap = (graph.coverage_gaps || []).find((item) => item.component_id === componentId);
+  if (alternatives.length) {
+    return {
+      status: alternatives.some((item) => item.relationship_type === "verified_alternative")
+        ? "verified"
+        : "conditional",
+      reviewed_alternative_count: alternatives.length,
+      reason: null,
+      graph_version: graph.version || null
+    };
+  }
+  return {
+    status: "gap",
+    reviewed_alternative_count: 0,
+    reason: gap?.reason || "No evidence-backed safer functional alternative is currently available.",
+    target_research_queries: gap?.target_research_queries || [],
+    graph_version: graph.version || null
+  };
+}

package/src/recommendations/load-recommendations.mjs

@@ -0,0 +1,17 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..", "..");
+
+const RECOMMENDATION_PACK_FILES = ["data/recommendations/core/recommendations.json"];
+
+export async function loadRecommendationPacks() {
+  const packs = [];
+  for (const file of RECOMMENDATION_PACK_FILES) {
+    const content = await readFile(join(ROOT, file), "utf8");
+    packs.push(JSON.parse(content));
+  }
+  return packs;
+}

package/src/recommendations/match-recommendations.mjs

@@ -0,0 +1,79 @@
+function intersects(left = [], right = []) {
+  return left.some((item) => right.includes(item));
+}
+
+function includesAll(left = [], right = []) {
+  return right.every((item) => left.includes(item));
+}
+
+function appliesToFinding(recommendation, finding) {
+  const appliesTo = recommendation.applies_to || {};
+
+  if (appliesTo.rule_ids?.length && !appliesTo.rule_ids.includes(finding.rule_id)) {
+    return false;
+  }
+  if (appliesTo.categories?.length && !appliesTo.categories.includes(finding.category)) {
+    return false;
+  }
+  if (appliesTo.permissions_any?.length && !intersects(finding.permissions, appliesTo.permissions_any)) {
+    return false;
+  }
+  if (appliesTo.permissions_all?.length && !includesAll(finding.permissions, appliesTo.permissions_all)) {
+    return false;
+  }
+  if (appliesTo.profile_ids?.length && !intersects(finding.profile_ids, appliesTo.profile_ids)) {
+    return false;
+  }
+
+  return true;
+}
+
+function publicRecommendation(recommendation) {
+  return {
+    id: recommendation.id,
+    title: recommendation.title,
+    type: recommendation.type,
+    status: recommendation.status,
+    source: recommendation.source,
+    confidence: recommendation.confidence,
+    rank: recommendation.rank,
+    recommended_actions: recommendation.recommended_actions,
+    recommended_alternatives: recommendation.recommended_alternatives,
+    agent_instruction: recommendation.agent_instruction,
+    one_step_commands: recommendation.one_step_commands || [],
+    rollback_note: recommendation.rollback_note
+  };
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+export function applyRecommendations(findings, recommendationPacks) {
+  const recommendations = recommendationPacks.flatMap((pack) => pack.recommendations || []);
+
+  return findings.map((finding) => {
+    const matched = recommendations
+      .filter((recommendation) => appliesToFinding(recommendation, finding))
+      .sort((left, right) => right.rank - left.rank || right.confidence - left.confidence)
+      .map(publicRecommendation);
+
+    const topRecommendation = matched[0];
+    const recommendedActions = unique([
+      ...(topRecommendation?.recommended_actions || []),
+      ...(finding.recommended_actions || [])
+    ]);
+    const recommendedAlternatives = unique([
+      ...(topRecommendation?.recommended_alternatives || []),
+      ...(finding.recommended_alternatives || [])
+    ]);
+
+    return {
+      ...finding,
+      recommended_actions: recommendedActions,
+      recommended_alternatives: recommendedAlternatives,
+      migration_instruction: topRecommendation?.agent_instruction || finding.migration_instruction || "",
+      recommendations: matched
+    };
+  });
+}

package/src/report/comparison-console.mjs

@@ -0,0 +1,71 @@
+export function renderComparisonConsole(result) {
+  const lines = [];
+  const delta = result.score.delta >= 0 ? `+${result.score.delta}` : String(result.score.delta);
+
+  lines.push("AgentSecurityLens Assessment Comparison");
+  lines.push("");
+  lines.push(`Previous: ${result.comparison.previous_assessment_id}`);
+  lines.push(`Current: ${result.comparison.current_assessment_id}`);
+  lines.push(`Trust Score: ${result.score.previous} -> ${result.score.current} (${delta})`);
+  lines.push(
+    `Findings: ${result.finding_counts.previous} -> ${result.finding_counts.current} ` +
+      `(added ${result.finding_counts.added}, resolved ${result.finding_counts.resolved}, persistent ${result.finding_counts.persistent})`
+  );
+  lines.push("");
+
+  if (result.profiles.added.length || result.profiles.removed.length || result.profiles.changed.length) {
+    lines.push("Profile Changes:");
+    for (const item of result.profiles.added) lines.push(`- Added ${item.id}@${item.version}`);
+    for (const item of result.profiles.removed) lines.push(`- Removed ${item.id}@${item.version}`);
+    for (const item of result.profiles.changed) {
+      lines.push(`- Changed ${item.id}: ${item.previous_version} -> ${item.current_version}`);
+    }
+    lines.push("");
+  }
+
+  if (result.rule_packs.added.length || result.rule_packs.removed.length || result.rule_packs.changed.length) {
+    lines.push("Rule Pack Changes:");
+    for (const item of result.rule_packs.added) lines.push(`- Added ${item.id}@${item.version}`);
+    for (const item of result.rule_packs.removed) lines.push(`- Removed ${item.id}@${item.version}`);
+    for (const item of result.rule_packs.changed) {
+      lines.push(`- Changed ${item.id}: ${item.previous_version} -> ${item.current_version}`);
+    }
+    lines.push("");
+  }
+
+  if (
+    result.recommendation_packs.added.length ||
+    result.recommendation_packs.removed.length ||
+    result.recommendation_packs.changed.length
+  ) {
+    lines.push("Recommendation Pack Changes:");
+    for (const item of result.recommendation_packs.added) lines.push(`- Added ${item.id}@${item.version}`);
+    for (const item of result.recommendation_packs.removed) lines.push(`- Removed ${item.id}@${item.version}`);
+    for (const item of result.recommendation_packs.changed) {
+      lines.push(`- Changed ${item.id}: ${item.previous_version} -> ${item.current_version}`);
+    }
+    lines.push("");
+  }
+
+  if (result.findings.added.length) {
+    lines.push("Added Findings:");
+    for (const finding of result.findings.added) {
+      lines.push(`- [${finding.severity}] ${finding.title} (${finding.evidence.path}:${finding.evidence.line})`);
+    }
+    lines.push("");
+  }
+
+  if (result.findings.resolved.length) {
+    lines.push("Resolved Findings:");
+    for (const finding of result.findings.resolved) {
+      lines.push(`- [${finding.severity}] ${finding.title} (${finding.evidence.path}:${finding.evidence.line})`);
+    }
+    lines.push("");
+  }
+
+  if (!result.findings.added.length && !result.findings.resolved.length) {
+    lines.push("No finding delta detected.");
+  }
+
+  return lines.join("\n");
+}

package/src/report/console.mjs

@@ -0,0 +1,103 @@
+export function renderConsole(result) {
+  const lines = [];
+  lines.push("AgentSecurityLens Security Assessment");
+  lines.push("");
+  lines.push(`Assessment ID: ${result.assessment.id}`);
+  lines.push(`Target: ${result.assessment.target_path}`);
+  lines.push(`Trust Score: ${result.summary.trust_score}/100`);
+  lines.push(`Findings: ${result.summary.total_findings}`);
+  lines.push(`Categories: ${Object.entries(result.summary.by_category).map(([key, value]) => `${key}=${value}`).join(", ") || "none"}`);
+  lines.push(`Profile Coverage Avg: ${result.summary.profile_coverage_average}`);
+  lines.push("");
+  lines.push("Profiles:");
+  for (const profile of result.profiles) {
+    lines.push(`- ${profile.id}@${profile.version} (${profile.status}, confidence ${profile.confidence})`);
+  }
+  lines.push("");
+  lines.push("Rule Packs:");
+  for (const pack of result.rule_packs) {
+    lines.push(`- ${pack.id}@${pack.version} (${pack.rule_count} rules)`);
+  }
+  lines.push("");
+  if (result.recommendation_packs?.length) {
+    lines.push("Recommendation Packs:");
+    for (const pack of result.recommendation_packs) {
+      lines.push(`- ${pack.id}@${pack.version} (${pack.status}, ${pack.recommendation_count} recommendations)`);
+    }
+    lines.push("");
+  }
+  if (result.trust_signal_taxonomies?.length) {
+    lines.push("Trust Signal Taxonomies:");
+    for (const taxonomy of result.trust_signal_taxonomies) {
+      lines.push(`- ${taxonomy.id}@${taxonomy.version} (${taxonomy.status}, ${taxonomy.signal_count} signals)`);
+    }
+    lines.push("");
+  }
+  lines.push("Profile Selection:");
+  lines.push(`- Mode: ${result.lineage.profile_selection.mode}`);
+  lines.push(`- Selected: ${result.lineage.profile_selection.selected_profile}`);
+  if (result.lineage.profile_selection.detection_signals.length) {
+    const signals = result.lineage.profile_selection.detection_signals
+      .map((signal) => `${signal.type}:${signal.value}`)
+      .join(", ");
+    lines.push(`- Signals: ${signals}`);
+  }
+  lines.push("");
+
+  if (result.risk_domains?.length) {
+    lines.push("Risk Domains:");
+    for (const domain of result.risk_domains) {
+      lines.push(`- ${domain.title}: ${domain.count} finding(s), highest=${domain.highest_severity}`);
+    }
+    lines.push("");
+  }
+
+  if (result.trust_signals?.length) {
+    const summary = result.summary.trust_signal_summary;
+    lines.push("Trust Signals:");
+    lines.push(`- Total: ${summary.total}, net weight=${summary.net_weight}`);
+    lines.push(
+      `- Direction: ${Object.entries(summary.by_direction).map(([key, value]) => `${key}=${value}`).join(", ")}`
+    );
+    for (const signal of result.trust_signals.slice(0, 5)) {
+      lines.push(`- ${signal.title} (${signal.signal_id}, ${signal.weight}) at ${signal.evidence.path}:${signal.evidence.line}`);
+    }
+    lines.push("");
+  }
+
+  if (result.findings.length === 0) {
+    lines.push("No risk findings detected by the current rule packs.");
+    lines.push("Known limitation: this does not prove the agent environment is safe.");
+    return lines.join("\n");
+  }
+
+  lines.push("Detailed Findings:");
+  for (const finding of result.findings) {
+    lines.push("");
+    lines.push(`[${finding.severity.toUpperCase()}] ${finding.title}`);
+    lines.push(`Category: ${finding.category}`);
+    lines.push(`Evidence: ${finding.evidence.path}:${finding.evidence.line}`);
+    if (finding.evidence_items.length > 1) {
+      lines.push(`Additional evidence: ${finding.evidence_items.length - 1} more match(es) in this file`);
+    }
+    lines.push(`Why it matters: ${finding.why_it_matters}`);
+    if (finding.recommended_actions.length) {
+      lines.push(`Actions: ${finding.recommended_actions.join("; ")}`);
+    }
+    if (finding.recommended_alternatives.length) {
+      lines.push(`Alternatives: ${finding.recommended_alternatives.join("; ")}`);
+    }
+    if (finding.migration_instruction) {
+      lines.push(`Migration: ${finding.migration_instruction}`);
+    }
+    if (finding.recommendations?.length) {
+      const top = finding.recommendations[0];
+      lines.push(`Top recommendation: ${top.title} (${top.id}, confidence ${top.confidence})`);
+      if (top.one_step_commands?.length) {
+        lines.push(`One-step instruction: ${top.one_step_commands[0].command}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}