@seeed-studio/solution-cli 0.3.1 → 0.4.0

package/lib/detector.js

@@ -226,7 +226,7 @@ export function detectDesktopApp() {
         appPath: appBase,
         binPath: path.join(appBase, 'Contents', 'MacOS', 'sensecraft-engine'),
         solutionsPath: path.join(appBase, 'Contents', 'Resources', '_up_', 'sensecraft-solutions', 'solutions'),
-        skillsPath: path.join(appBase, 'Contents', 'Resources', '_up_', 'sensecraft-solutions', 'skills', 'sensecraft')
+        skillsPath: path.join(appBase, 'Contents', 'Resources', '_up_', 'sensecraft-solutions', 'skills', 'solution-cli')
       });
       const cacheBin = path.join(
         os.homedir(),
@@ -258,7 +258,7 @@ export function detectDesktopApp() {
           appPath,
           binPath: path.join(appPath, 'resources', 'bin', 'sensecraft-engine.exe'),
           solutionsPath: path.join(appPath, 'resources', 'sensecraft-solutions', 'solutions'),
-          skillsPath: path.join(appPath, 'resources', 'sensecraft-solutions', 'skills', 'sensecraft')
+          skillsPath: path.join(appPath, 'resources', 'sensecraft-solutions', 'skills', 'solution-cli')
         });
       }
     }
@@ -271,7 +271,7 @@ export function detectDesktopApp() {
           appPath,
           binPath: path.join(appPath, 'sensecraft-engine'),
           solutionsPath: path.join(appPath, 'sensecraft-solutions', 'solutions'),
-          skillsPath: path.join(appPath, 'skills', 'sensecraft')
+          skillsPath: path.join(appPath, 'skills', 'solution-cli')
         });
       }
     }

package/lib/doctor.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { getPlatformInfo, getEngineBinDir, getEngineBinaryPath, getConfiguredEnginePath, getContentDir } from './platform.js';
-import { verifyEngineBinary } from './detector.js';
+import { verifyEngineBinary, detectDesktopApp } from './detector.js';
 import { loadLedger, computeFileHash } from './ledger.js';
 
 export function runDoctor() {
@@ -166,6 +166,24 @@ export function runDoctor() {
     });
   }
 
+  // Check 8: Desktop App (GUI)
+  const app = detectDesktopApp();
+  if (app.detected) {
+    checks.push({
+      id: 'desktop_app',
+      status: 'ok',
+      title: 'SenseCraft Solution Desktop App (GUI)',
+      detail: `Detected at ${app.appPath || app.binPath} (v${app.version || 'installed'})`
+    });
+  } else {
+    checks.push({
+      id: 'desktop_app',
+      status: 'ok',
+      title: 'SenseCraft Solution Desktop App (GUI)',
+      detail: 'Not detected (optional). For visual dashboard & GUI workflows, download at https://sensecraft.seeed.cc/download'
+    });
+  }
+
   const overall = checks.some(c => c.status === 'fail')
     ? 'fail'
     : checks.some(c => c.status === 'warn')

package/lib/downloader.js

@@ -281,3 +281,27 @@ export function pullSolutionContent(binPath, onProgress = () => {}) {
     return { success: false, warning: msg };
   }
 }
+
+export function updateSolutionContent(binPath, onProgress = () => {}) {
+  const contentDir = path.join(getScHome(), 'content', 'solutions');
+  const isEmptyStore = !fs.existsSync(contentDir) || fs.readdirSync(contentDir).filter(f => !f.startsWith('.')).length === 0;
+
+  if (isEmptyStore) {
+    onProgress('Initial solution content store is empty; performing full initial pull...');
+    return pullSolutionContent(binPath, onProgress);
+  }
+
+  onProgress('Updating official solution definitions from CDN (sensecraft-engine content update)...');
+  try {
+    execFileSync(binPath, ['content', 'update'], {
+      encoding: 'utf8',
+      timeout: 120000,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    onProgress('Solution content successfully updated to latest.');
+    return { success: true };
+  } catch (err) {
+    onProgress('Notice: incremental update fell back to full pull.');
+    return pullSolutionContent(binPath, onProgress);
+  }
+}

package/lib/gotchas.js

@@ -0,0 +1,126 @@
+/**
+ * @file gotchas.js
+ * Edge hardware & chip troubleshooting knowledge base for Solution CLI.
+ */
+
+export const GOTCHAS_DATABASE = [
+  {
+    id: 'rk3588_npu_device_missing',
+    chip: 'rk3588',
+    title: 'RK3588/RK3576 NPU 设备节点缺失或无权访问 (/dev/rknn)',
+    keywords: ['rk3588', 'rk3576', 'rknn', '/dev/rknn', 'npu', 'permission denied', 'no such file'],
+    symptoms: '容器内运行推理时报错 "cannot open /dev/rknn" 或 "Permission denied"',
+    root_cause: '宿主机未加载 rknpu 内核模块，或者 Docker 容器启动时未正确挂载 /dev/rknn 设备节点及配置 udev 权限。',
+    solution: [
+      '1. 检查宿主机内核节点：ls -l /dev/rknn (若不存在，执行 sudo modprobe rknpu)',
+      '2. 赋予设备访问权限：sudo chmod 666 /dev/rknn',
+      '3. Docker 启动或 Compose 配置中必须显式透传设备：',
+      '   devices:\n     - /dev/rknn:/dev/rknn\n     - /dev/dma_heap:/dev/dma_heap',
+      '4. 检查驱动日志：dmesg | grep -i rknpu'
+    ],
+    forbidden: '不要在容器内尝试执行 apt install 重新安装原厂内核 BSP，底层驱动必须依赖宿主机内核。'
+  },
+  {
+    id: 'rk3588_docker_nftables_conflict',
+    chip: 'rk3588',
+    title: 'Rockchip Ubuntu Docker 网络互通死锁 (iptables-legacy 冲突)',
+    keywords: ['rk3588', 'rk3576', 'docker', 'iptables', 'nftables', 'network', 'bridge'],
+    symptoms: 'Docker 服务启动失败，或容器内无法通过桥接网关访问外部网络与外设流。',
+    root_cause: 'Rockchip 定制 Linux 6.1 内核对 nftables 的支持不完备，而较新版 Docker 默认尝试使用 iptables-nft。',
+    solution: [
+      '1. 切换系统默认 iptables 为 legacy 模式：',
+      '   sudo update-alternatives --set iptables /usr/sbin/iptables-legacy',
+      '   sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy',
+      '2. 重启 Docker 守护进程：sudo systemctl restart docker'
+    ],
+    forbidden: '切勿卸载 iptables 软件包或随意清空 iptables -F，这会导致 Docker 默认 NAT 转发链彻底损坏。'
+  },
+  {
+    id: 'recamera_vpss_overflow',
+    chip: 'recamera',
+    title: 'reCamera (SG2002 / RV1126B) 图像管道溢出 (VPSS FIFO overflow)',
+    keywords: ['recamera', 'vpss', 'fifo', 'overflow', 'sg2002', 'rv1126b', 'isp', 'vi'],
+    symptoms: '视频流卡死、黑屏，dmesg 频繁刷新 "VPSS FIFO overflow" 或 "VI drop frame"',
+    root_cause: '推理进程处理帧率低于摄像头输入帧率，导致硬件 ISP/VPSS 环形缓冲区被填满并阻塞硬件通道。',
+    solution: [
+      '1. 在 rkipc.ini 或流媒体配置中适当降低码流分辨率（从 1440P 降至 1080P 或 720P）',
+      '2. 限制推理帧率（如设置 skip_frames: 2，每秒处理 10~15 帧）',
+      '3. 检查模型加载是否启用了硬件 NPU 加速（.cvimodel / .rknn），避免 CPU 软解码'
+    ],
+    forbidden: '不要在视频流已卡死时直接硬重启机器，应先优雅杀掉流媒体服务以释放 VI/VPSS 通道。'
+  },
+  {
+    id: 'recamera_process_kill_safety',
+    chip: 'recamera',
+    title: 'reCamera 服务热重启安全规约：严禁 while true 且必须 sleep 3',
+    keywords: ['recamera', 'restart', 'fork bomb', 'sleep 3', 'pgrep', 'kill', 'watchdog'],
+    symptoms: '修改二进制或配置后设备网络全断，SSH/HTTP 无法连接，只能拔电硬重启。',
+    root_cause: '1. 硬件 VPSS/VI 资源被旧进程锁定未完全释放即启动新进程；2. 监控脚本使用死循环在二进制闪退时触发 Fork 风暴耗尽内核 PID。',
+    solution: [
+      '1. 优雅停止进程：for p in $(pgrep -f rkipc); do kill -9 $p; done',
+      '2. 关键安全延迟：必须等待 3 秒释放硬件通道：sleep 3',
+      '3. 安全拉起新服务：/userdata/rkipc.patch -c /userdata/rkipc.ini &'
+    ],
+    forbidden: '严禁在脚本中使用 while true; do /path/app; sleep 1; done 守护！一旦二进制参数错误快速退出，会导致系统瘫痪。'
+  },
+  {
+    id: 'jetson_nvidia_runtime_missing',
+    chip: 'jetson',
+    title: 'Jetson Orin (J4012/J2012) 容器缺失 NVIDIA Container Runtime',
+    keywords: ['jetson', 'orin', 'j4012', 'j4011', 'j2012', 'cuda', 'tensorrt', 'nvidia runtime'],
+    symptoms: 'Docker 容器启动报 "CUDA driver version is insufficient" 或无法找到 /dev/nvhost-* 设备',
+    root_cause: 'Docker 守护进程未配置默认 nvidia runtime，或运行 docker compose 时未指定 runtime: nvidia。',
+    solution: [
+      '1. 检查 /etc/docker/daemon.json 是否包含 "default-runtime": "nvidia"',
+      '2. 运行单个容器时添加参数：docker run --runtime nvidia ...',
+      '3. Compose 配置中加入：\n   runtime: nvidia\n   environment:\n     - NVIDIA_VISIBLE_DEVICES=all\n     - NVIDIA_DRIVER_CAPABILITIES=all'
+    ],
+    forbidden: '不要在 Jetson 容器内盲目安装标准 x86 的 NVIDIA 官方显卡驱动，Jetson 采用系统级统一内存 L4T BSP。'
+  },
+  {
+    id: 'hailo_driver_version_mismatch',
+    chip: 'hailo',
+    title: 'reComputer R2000 / RPi Hailo-8 驱动与运行库版本不匹配',
+    keywords: ['hailo', 'hailo8', 'libhailort', 'hailortcli', 'version mismatch', 'r2000'],
+    symptoms: '容器或应用启动报 "libhailort.so.4.21.0 not found" 或 "Driver version mismatch"',
+    root_cause: 'HailoRT 的内核驱动 (PCIe Driver)、用户态动态库 (libhailort) 和 GStreamer 插件版本必须严格完全一致（如均为 4.21.0）。',
+    solution: [
+      '1. 检查当前内核驱动状态：hailortcli fw-control identify',
+      '2. 检查动态库版本：ls -l /usr/lib/libhailort.so*',
+      '3. 确保宿主机与容器内镜像使用的 HailoRT 版本一致（官方套件均已固定为 4.21.0）'
+    ],
+    forbidden: '不要在已有应用正在占用 /dev/hailo0 时启动第二个推理容器，Hailo-8 默认排他独占访问。'
+  }
+];
+
+/**
+ * Searches the gotchas troubleshooting database.
+ *
+ * @param {Object} options
+ * @param {string} [options.query] - Search term
+ * @param {string} [options.chip] - Target chip/platform (rk3588, recamera, jetson, hailo)
+ * @returns {Array<Object>} Matched gotchas records
+ */
+export function searchGotchas({ query = '', chip = '' } = {}) {
+  const q = String(query || '').trim().toLowerCase();
+  const c = String(chip || '').trim().toLowerCase();
+
+  return GOTCHAS_DATABASE.filter((item) => {
+    if (c && !item.chip.toLowerCase().includes(c)) {
+      return false;
+    }
+    if (!q) return true;
+    const tokens = q.split(/\s+/).filter(Boolean);
+    const haystack = [
+      item.id,
+      item.chip,
+      item.title,
+      item.symptoms,
+      item.root_cause,
+      ...(item.keywords || []),
+      ...(Array.isArray(item.solution) ? item.solution : [item.solution]),
+    ].join(' ').toLowerCase();
+
+    return tokens.every((t) => haystack.includes(t));
+  });
+}

package/lib/installer.js

@@ -9,8 +9,8 @@ import {
   getConfiguredEnginePath
 } from './platform.js';
 import { detectExistingEngine, detectDesktopApp, verifyEngineBinary, compareSemver } from './detector.js';
-import { downloadEngine, fetchManifest, validateReleaseManifest, pullSolutionContent } from './downloader.js';
-import { scanLocalAgents, promptAgentSelection } from './agent.js';
+import { downloadEngine, fetchManifest, validateReleaseManifest, pullSolutionContent, updateSolutionContent } from './downloader.js';
+import { getKnownAgents, scanLocalAgents, promptAgentSelection } from './agent.js';
 import {
   recordInstallation,
   removeInstallation,
@@ -22,21 +22,47 @@ import {
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const BUNDLED_SKILLS_SRC = path.resolve(__dirname, '..', 'skills', 'sensecraft');
+const SKILL_DIR_NAME = 'solution-cli';
+const LEGACY_SKILL_DIR_NAME = 'sensecraft';
+const BUNDLED_SKILLS_SRC = path.resolve(__dirname, '..', 'skills', SKILL_DIR_NAME);
+
+function assertCanonicalSkillState(ledger, agents) {
+  const allAgents = agents;
+  const errors = [];
+
+  for (const agent of allAgents) {
+    const skillsDir = agent.skillsDir || agent.getSkillsDir();
+    const expectedTarget = path.resolve(path.join(skillsDir, SKILL_DIR_NAME));
+    const legacySkill = path.join(skillsDir, LEGACY_SKILL_DIR_NAME, 'SKILL.md');
+    if (fs.lstatSync(legacySkill, { throwIfNoEntry: false })) {
+      errors.push(`${agent.id} still has legacy skill at ${legacySkill}; run uninstall --agent ${agent.id} before installing solution-cli. If the file is untracked or remains after uninstall because it was modified, back it up and retire the legacy skill directory before retrying; user files are not removed automatically.`);
+    }
+    const record = ledger.installations?.[agent.id];
+    if (record && path.resolve(record.target_dir) !== expectedTarget) {
+      errors.push(`${agent.id} is managed at legacy target ${record.target_dir}; run uninstall --agent ${agent.id} before installing solution-cli`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Legacy SenseCraft skill state blocks canonical solution-cli installation:\n- ${errors.join('\n- ')}`);
+  }
+}
 
 export async function runInstall(options = {}) {
   const {
     agent = null,
+    skillsDir = null,
     yes = false,
     dryRun = false,
     skipContent = false,
     force = false,
     enginePath = null,
+    isUpdate = false,
     logger = console.log
   } = options;
 
   logger('\x1b[1m\x1b[34m====================================================\x1b[0m');
-  logger('\x1b[1m\x1b[34m  SenseCraft Engine & AI Agent Skill Installer     \x1b[0m');
+  logger(`\x1b[1m\x1b[34m  Solution CLI ${isUpdate ? 'Updater' : 'Installer'}                         \x1b[0m`);
   logger('\x1b[1m\x1b[34m====================================================\x1b[0m\n');
 
   const platform = getPlatformInfo();
@@ -46,13 +72,16 @@ export async function runInstall(options = {}) {
 
   // --- Step 0: Pre-validate agent targets before ANY download/side-effects (Codex Medium 11) ---
   const scanned = scanLocalAgents();
-  const selectedAgents = await promptAgentSelection(scanned, agent, yes);
+  const selectedAgents = await promptAgentSelection(scanned, agent, yes, skillsDir);
 
   if (selectedAgents.length === 0) {
-    logger('\nNo agents selected. Installation halted with no filesystem modifications.');
+    logger('\nNo agents selected. Operation halted with no filesystem modifications.');
     return { success: true, engineBin: null, installedAgents: [] };
   }
 
+  // Validate ownership and legacy targets before engine selection or pointer/download writes.
+  assertCanonicalSkillState(loadLedger(), selectedAgents);
+
   // --- Step 1: Detect & Verify Engine Candidate ---
   logger('🔍 Phase 1: Inspecting host environment for existing Engine/App...');
   let engineBin = null;
@@ -120,8 +149,13 @@ export async function runInstall(options = {}) {
 
   // --- Step 2: Content Cache ---
   if (!skipContent && !dryRun) {
-    logger('\n🔄 Phase 2: Ensuring IoT solutions catalog is populated...');
-    pullSolutionContent(engineBin, msg => logger(`  ${msg}`));
+    if (isUpdate) {
+      logger('\n🔄 Phase 2: Updating IoT solutions catalog to latest...');
+      updateSolutionContent(engineBin, msg => logger(`  ${msg}`));
+    } else {
+      logger('\n🔄 Phase 2: Ensuring IoT solutions catalog is populated...');
+      pullSolutionContent(engineBin, msg => logger(`  ${msg}`));
+    }
   } else if (skipContent) {
     logger('\n🔄 Phase 2: Skipped solution pull (--skip-content).');
   }
@@ -135,9 +169,10 @@ export async function runInstall(options = {}) {
 
   runWithLock(() => {
     const ledger = dryRun ? { installations: {} } : loadLedger();
+    assertCanonicalSkillState(ledger, selectedAgents);
 
     for (const a of selectedAgents) {
-      const destDir = path.resolve(path.join(a.skillsDir, 'sensecraft'));
+      const destDir = path.resolve(path.join(a.skillsDir, SKILL_DIR_NAME));
       logger(`\nConfiguring ${a.name} at: ${destDir}...`);
 
       if (dryRun) {
@@ -161,7 +196,7 @@ export async function runInstall(options = {}) {
         const preservedStat = fs.lstatSync(preservedSkillPath, { throwIfNoEntry: false });
         if (preservedStat && !preservedStat.isSymbolicLink()) {
           const preservedSkill = fs.readFileSync(preservedSkillPath, 'utf8');
-          const oldPathMatch = preservedSkill.match(/\*\*SenseCraft Runtime\*\*:[\s\S]*?full absolute path: `"([^"]+)"/);
+          const oldPathMatch = preservedSkill.match(/\*\*Solution CLI Runtime\*\*:[\s\S]*?full absolute path: `"([^"]+)"/);
           const normalizePath = value => path.normalize(value.replaceAll('\\', '/'));
           if (oldPathMatch && normalizePath(oldPathMatch[1]) !== normalizePath(engineBin)) {
             logger(`  ⚠️ Preserved user-modified SKILL.md still contains its previous Engine path; user text was not rewritten.`);
@@ -178,9 +213,9 @@ export async function runInstall(options = {}) {
         if (skillStat && !skillStat.isSymbolicLink()) {
           let content = fs.readFileSync(skillMdPath, 'utf8');
           const escapedBinPath = engineBin.replace(/\\/g, '/');
-          const instructionBlock = `\n> **SenseCraft Runtime**: All steps run via \`${escapedBinPath}\`. If shell $PATH does not contain \`sensecraft-engine\`, always invoke using the full absolute path: \`"${escapedBinPath}" <subcommand>\`.\n\n`;
+          const instructionBlock = `\n> **Solution CLI Runtime**: Engine operations such as \`device\`, \`deploy\`, and \`logs\` must use the full absolute path: \`"${escapedBinPath}" <subcommand>\`. Use \`solution-cli\` for catalog and product queries; if it is not on $PATH, invoke \`npx -y --package=@seeed-studio/solution-cli@latest solution-cli <args>\`.\n\n`;
 
-          if (!content.includes('SenseCraft Runtime:')) {
+          if (!content.includes('**Solution CLI Runtime**:')) {
             content = content.replace(/(---[\s\S]*?---\n)/, `$1${instructionBlock}`);
             fs.writeFileSync(skillMdPath, content, 'utf8');
           }
@@ -189,7 +224,7 @@ export async function runInstall(options = {}) {
       }
 
       // Write installation marker safely without following external symlinks (Codex P2)
-      const markerPath = path.join(destDir, '.installed-by-sensecraft');
+      const markerPath = path.join(destDir, '.installed-by-solution-cli');
       if (isSafePathInside(markerPath, destDir)) {
         const markerStat = fs.lstatSync(markerPath, { throwIfNoEntry: false });
         if (markerStat && markerStat.isSymbolicLink()) {
@@ -210,14 +245,17 @@ export async function runInstall(options = {}) {
   });
 
   logger('\n\x1b[1m\x1b[32m====================================================\x1b[0m');
-  logger('\x1b[1m\x1b[32m  🎉 SenseCraft Setup Completed Successfully!      \x1b[0m');
+  logger('\x1b[1m\x1b[32m  🎉 Solution CLI Setup Completed Successfully!   \x1b[0m');
   logger('\x1b[1m\x1b[32m====================================================\x1b[0m');
   logger(`\n🔧 Engine Binary: ${engineBin}`);
   logger(`🤖 Configured Agents:`);
   installedAgents.forEach(a => logger(`   - ${a.name}: ${a.path}`));
-  logger('\n👉 You can now open Work Buddy or your chosen Agent and ask:');
-  logger('   "帮我把边缘安全方案 (edge_security) 部署到 Jetson (192.168.1.100)"');
-  logger('   "查看当前有哪些可部署的物联网方案"');
+  logger('\n👉 [Instructions for AI Agent / 助手后续操作]:');
+  logger('   Solution CLI skill is now installed and activated.');
+  logger('   - Search IoT solutions: solution-cli hub search "<query>" --json');
+  logger('   - Check deployment specs: sensecraft-engine deploy-info <solution-id> --lang zh');
+  logger('   - Deploy (Local/Remote): sensecraft-engine deploy --params ./.sensecraft-work/body.json --yes');
+  logger('   Please inform the user that the skill is ready for solution selection and deployment.');
   logger('----------------------------------------------------\n');
 
   return {
@@ -234,6 +272,7 @@ export function runStatus(options = {}) {
   const engineCheck = verifyEngineBinary(binPath);
   const ledger = loadLedger();
   const scannedAgents = scanLocalAgents();
+  const app = detectDesktopApp();
 
   const statusObj = {
     engine: {
@@ -243,6 +282,12 @@ export function runStatus(options = {}) {
       valid: engineCheck.valid,
       deployersCount: engineCheck.deployers?.length || 0
     },
+    desktop_app: {
+      detected: Boolean(app.detected),
+      compatible: Boolean(app.compatible),
+      appPath: app.appPath || null,
+      version: app.version || null
+    },
     content: {
       dir: getContentDir(),
       manifestExists: fs.existsSync(path.join(getContentDir(), 'manifest.json'))
@@ -262,10 +307,16 @@ export function runStatus(options = {}) {
     return statusObj;
   }
 
-  logger('\n📊 SenseCraft System Status:\n');
+  logger('\n📊 Solution CLI System Status:\n');
   logger(`  Engine Binary: ${binPath}`);
   logger(`  Engine Version: ${engineCheck.version || 'Not installed'} (${engineCheck.valid ? 'Valid' : 'Invalid'})`);
   logger(`  Deployers Available: ${engineCheck.deployers?.length || 0}`);
+  if (app.detected) {
+    logger(`  Desktop App (GUI): Detected at ${app.appPath || app.binPath} (v${app.version || 'installed'})`);
+  } else {
+    logger('  Desktop App (GUI): \x1b[90mNot detected\x1b[0m');
+    logger('    💡 可视化看板与桌面客户端下载: https://sensecraft.seeed.cc/download');
+  }
   logger(`  Content Directory: ${getContentDir()} (${statusObj.content.manifestExists ? 'Ready' : 'Not cached'})`);
   logger('\n  Configured Agent Skills:');
 
@@ -286,7 +337,7 @@ export function runUninstall(options = {}) {
   const installedIds = Object.keys(ledger.installations || {});
 
   if (installedIds.length === 0) {
-    logger('No managed SenseCraft skills are currently recorded in the ledger.');
+    logger('No managed Solution CLI skills are currently recorded in the ledger.');
     return;
   }
 
@@ -380,3 +431,46 @@ function copyFolderSafely(srcDir, destDir, baseDestDir, priorFiles, force, logge
 
   return { filesWritten, updatedFiles, preservedFiles };
 }
+
+/**
+ * Runs update on existing installed agents and synchronizes solution content and engine.
+ *
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+export async function runUpdate(options = {}) {
+  const logger = options.logger || console.log;
+
+  let targetAgent = options.agent;
+  if (!targetAgent && !options.skillsDir) {
+    const scanned = scanLocalAgents();
+    const installed = scanned.filter(a => a.installed);
+    if (installed.length > 0) {
+      targetAgent = installed.map(a => a.id).join(',');
+    }
+  }
+
+  return runInstall({
+    ...options,
+    agent: targetAgent,
+    yes: options.yes !== undefined ? options.yes : true,
+    isUpdate: true,
+    logger,
+  });
+}
+
+/**
+ * Returns formatted scan of local AI agents.
+ *
+ * @returns {Array<Object>}
+ */
+export function listAgents() {
+  const scanned = scanLocalAgents();
+  return scanned.map(a => ({
+    id: a.id,
+    name: a.name,
+    detected: a.detected,
+    installed: a.installed,
+    skillsDir: a.skillsDir,
+  }));
+}