create-walle 0.9.31 → 0.9.32

package/template/claude-task-manager/lib/agent-version-service.js

@@ -0,0 +1,650 @@
+'use strict';
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const path = require('path');
+const { execFile, spawn } = require('child_process');
+const agentCliCache = require('./agent-cli-cache');
+
+const CACHE_VERSION = 1;
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_REGISTRY_BASE_URL = 'https://registry.npmjs.org';
+const DEFAULT_VERSION_TIMEOUT_MS = 2500;
+const DEFAULT_REGISTRY_TIMEOUT_MS = 3000;
+const DEFAULT_UPGRADE_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_OUTPUT_BYTES = 128 * 1024;
+const MAX_JOB_OUTPUT_BYTES = 96 * 1024;
+const MAX_UPGRADE_JOBS = 24;
+const UPGRADE_JOB_TTL_MS = 60 * 60 * 1000;
+let _upgradeJobSeq = 0;
+const _upgradeJobs = new Map();
+
+const AGENT_DEFINITIONS = Object.freeze({
+  'claude-code': Object.freeze({
+    id: 'claude-code',
+    cli: 'claude',
+    name: 'Claude Code',
+    versionArgs: ['--version'],
+    latest: { kind: 'npm', package: '@anthropic-ai/claude-code' },
+    selfUpdate: { args: ['update'], label: 'claude update' },
+  }),
+  codex: Object.freeze({
+    id: 'codex',
+    cli: 'codex',
+    name: 'Codex',
+    versionArgs: ['--version'],
+    latest: { kind: 'npm', package: '@openai/codex' },
+    selfUpdate: { args: ['update'], label: 'codex update' },
+  }),
+  'gemini-cli': Object.freeze({
+    id: 'gemini-cli',
+    cli: 'gemini',
+    name: 'Gemini CLI',
+    versionArgs: ['--version'],
+    latest: { kind: 'npm', package: '@google/gemini-cli' },
+    packageManagers: Object.freeze({
+      'npm-global': { command: 'npm', args: ['install', '-g', '@google/gemini-cli@latest'], label: 'npm install -g @google/gemini-cli@latest' },
+      homebrew: { command: 'brew', args: ['upgrade', 'gemini-cli'], label: 'brew upgrade gemini-cli' },
+    }),
+  }),
+  opencode: Object.freeze({
+    id: 'opencode',
+    cli: 'opencode',
+    name: 'OpenCode',
+    versionArgs: ['--version'],
+    latest: { kind: 'npm', package: 'opencode-ai' },
+    selfUpdate: { args: ['upgrade'], label: 'opencode upgrade' },
+  }),
+  cursor: Object.freeze({
+    id: 'cursor',
+    cli: 'cursor-agent',
+    name: 'Cursor',
+    versionArgs: ['--version'],
+    latest: null,
+    selfUpdate: { args: ['update'], label: 'cursor-agent update' },
+  }),
+});
+
+const DEFAULT_AGENT_IDS = Object.freeze(Object.keys(AGENT_DEFINITIONS));
+
+function _readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function _writeJson(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2) + '\n');
+  try { fs.chmodSync(filePath, 0o600); } catch {}
+}
+
+function normalizeSemver(value) {
+  const match = String(value || '').match(/v?(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?/);
+  if (!match) return null;
+  const parts = match.slice(1).map((part) => Number(part));
+  if (parts.some((part) => !Number.isFinite(part))) return null;
+  return { major: parts[0], minor: parts[1], patch: parts[2], version: `${parts[0]}.${parts[1]}.${parts[2]}` };
+}
+
+function compareSemver(a, b) {
+  const left = normalizeSemver(a);
+  const right = normalizeSemver(b);
+  if (!left || !right) return null;
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] < right[key]) return -1;
+    if (left[key] > right[key]) return 1;
+  }
+  return 0;
+}
+
+function parseVersionText(stdout, stderr) {
+  const primary = String(stdout || '');
+  const primaryMatch = primary.match(/v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/);
+  if (primaryMatch) return primaryMatch[1].replace(/^v/, '');
+  const combined = `${primary}\n${String(stderr || '')}`;
+  const semverMatch = combined.match(/v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/);
+  if (semverMatch) return semverMatch[1].replace(/^v/, '');
+  const buildMatch = combined.match(/\b(\d{4}\.\d{2}\.\d{2}-[0-9A-Za-z.-]+)\b/);
+  return buildMatch ? buildMatch[1] : '';
+}
+
+function _trimOutput(text) {
+  const value = String(text || '');
+  if (Buffer.byteLength(value) <= MAX_OUTPUT_BYTES) return value;
+  return value.slice(0, MAX_OUTPUT_BYTES) + '\n[output truncated]';
+}
+
+function redactOutput(text) {
+  return String(text || '')
+    .replace(/sk-[A-Za-z0-9_-]{16,}/g, 'sk-[redacted]')
+    .replace(/pk_[A-Za-z0-9_-]{16,}/g, 'pk_[redacted]')
+    .replace(/npm_[A-Za-z0-9_-]{16,}/g, 'npm_[redacted]')
+    .replace(/ghp_[A-Za-z0-9_-]{16,}/g, 'ghp_[redacted]')
+    .replace(/glpat-[A-Za-z0-9_-]{16,}/g, 'glpat-[redacted]')
+    .replace(/xox[bpas]-[A-Za-z0-9-]{16,}/g, 'xox[redacted]')
+    .replace(/(password|passwd|secret|token)(\s*[=:]\s*)(".*?"|'.*?'|[^\s]+)/gi, '$1$2[redacted]');
+}
+
+function runCommand(command, args, opts = {}) {
+  const execFileImpl = opts.execFileImpl || execFile;
+  const timeout = Number(opts.timeoutMs) || DEFAULT_VERSION_TIMEOUT_MS;
+  const env = opts.env || process.env;
+  return new Promise((resolve) => {
+    execFileImpl(command, args || [], {
+      encoding: 'utf8',
+      timeout,
+      maxBuffer: MAX_OUTPUT_BYTES,
+      env,
+    }, (error, stdout, stderr) => {
+      resolve({
+        ok: !error,
+        error: error ? (error.message || String(error)) : '',
+        code: error && typeof error.code !== 'undefined' ? error.code : 0,
+        signal: error && error.signal ? error.signal : '',
+        stdout: _trimOutput(stdout),
+        stderr: _trimOutput(stderr),
+      });
+    });
+  });
+}
+
+function _newUpgradeJobId(agentId) {
+  _upgradeJobSeq = (_upgradeJobSeq + 1) % Number.MAX_SAFE_INTEGER;
+  return `agent-upgrade-${String(agentId || 'agent').replace(/[^a-z0-9_-]/gi, '-')}-${Date.now().toString(36)}-${_upgradeJobSeq.toString(36)}`;
+}
+
+function _appendJobOutput(job, stream, chunk) {
+  if (!job) return;
+  let text = redactOutput(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk || ''));
+  if (!text) return;
+  const maxBytes = Number(job.maxOutputBytes) || MAX_JOB_OUTPUT_BYTES;
+  if (Buffer.byteLength(text) > maxBytes) {
+    text = text.slice(-maxBytes);
+    job.outputTruncated = true;
+  }
+  const entry = { at: Date.now(), stream: stream || 'system', text };
+  job.output.push(entry);
+  job.outputBytes += Buffer.byteLength(text);
+  while (job.outputBytes > maxBytes && job.output.length > 0) {
+    const removed = job.output.shift();
+    job.outputBytes -= Buffer.byteLength(removed.text || '');
+    job.outputTruncated = true;
+  }
+  job.updatedAt = entry.at;
+}
+
+function _upgradeJobSnapshot(job) {
+  if (!job) return null;
+  return {
+    id: job.id,
+    agent: job.agent,
+    name: job.name,
+    status: job.status,
+    phase: job.phase,
+    pid: job.pid || 0,
+    commandLabel: job.commandLabel || '',
+    command: job.command || '',
+    args: Array.isArray(job.args) ? job.args.slice() : [],
+    plan: job.plan || null,
+    startedAt: job.startedAt,
+    updatedAt: job.updatedAt,
+    finishedAt: job.finishedAt || 0,
+    durationMs: job.finishedAt ? Math.max(0, job.finishedAt - job.startedAt) : Math.max(0, Date.now() - job.startedAt),
+    code: typeof job.code === 'number' ? job.code : null,
+    signal: job.signal || '',
+    error: job.error || '',
+    refreshError: job.refreshError || '',
+    reused: !!job.reused,
+    output: job.output.slice(),
+    outputBytes: job.outputBytes || 0,
+    outputTruncated: !!job.outputTruncated,
+  };
+}
+
+function _pruneUpgradeJobs(now = Date.now()) {
+  for (const [id, job] of _upgradeJobs) {
+    if (job.status !== 'running' && job.finishedAt && now - job.finishedAt > UPGRADE_JOB_TTL_MS) {
+      _upgradeJobs.delete(id);
+    }
+  }
+  while (_upgradeJobs.size > MAX_UPGRADE_JOBS) {
+    const oldest = _upgradeJobs.keys().next().value;
+    if (!oldest) break;
+    _upgradeJobs.delete(oldest);
+  }
+}
+
+function _findRunningUpgradeJob(agentId) {
+  for (const job of _upgradeJobs.values()) {
+    if (job.agent === agentId && job.status === 'running') return job;
+  }
+  return null;
+}
+
+function getUpgradeJob(jobId) {
+  _pruneUpgradeJobs();
+  return _upgradeJobSnapshot(_upgradeJobs.get(String(jobId || '')));
+}
+
+function listUpgradeJobs() {
+  _pruneUpgradeJobs();
+  const jobs = [..._upgradeJobs.values()]
+    .sort((a, b) => (b.updatedAt || b.startedAt || 0) - (a.updatedAt || a.startedAt || 0))
+    .map(_upgradeJobSnapshot);
+  return { ok: true, jobs };
+}
+
+async function startUpgradeJob(agentId, opts = {}) {
+  _pruneUpgradeJobs();
+  const status = opts.statusPayload || await getAgentVersionStatus({ ...opts, force: false });
+  const plan = buildUpgradePlan(agentId, status);
+  const existing = _findRunningUpgradeJob(plan.agent);
+  if (existing) {
+    const snapshot = _upgradeJobSnapshot(existing);
+    snapshot.reused = true;
+    return { ok: true, job: snapshot };
+  }
+
+  const now = Date.now();
+  const job = {
+    id: _newUpgradeJobId(plan.agent),
+    agent: plan.agent,
+    name: plan.name,
+    status: 'running',
+    phase: 'running',
+    commandLabel: plan.commandLabel || '',
+    command: plan.command,
+    args: plan.args.slice(),
+    plan,
+    pid: 0,
+    startedAt: now,
+    updatedAt: now,
+    finishedAt: 0,
+    code: null,
+    signal: '',
+    error: '',
+    refreshError: '',
+    output: [],
+    outputBytes: 0,
+    outputTruncated: false,
+    maxOutputBytes: Number(opts.maxJobOutputBytes) || MAX_JOB_OUTPUT_BYTES,
+  };
+  _upgradeJobs.set(job.id, job);
+  _appendJobOutput(job, 'system', `Starting ${plan.commandLabel || [path.basename(plan.command)].concat(plan.args).join(' ')}\n`);
+
+  const spawnImpl = opts.spawnImpl || spawn;
+  let child = null;
+  try {
+    child = spawnImpl(plan.command, plan.args, {
+      env: opts.env || process.env,
+      shell: false,
+      windowsHide: true,
+    });
+  } catch (e) {
+    job.status = 'failed';
+    job.phase = 'failed';
+    job.error = e && e.message ? e.message : String(e);
+    job.finishedAt = Date.now();
+    _appendJobOutput(job, 'stderr', `${job.error}\n`);
+    return { ok: true, job: _upgradeJobSnapshot(job) };
+  }
+
+  job.child = child;
+  job.pid = child && child.pid ? child.pid : 0;
+  const timeoutMs = Number(opts.upgradeTimeoutMs) || DEFAULT_UPGRADE_TIMEOUT_MS;
+  const timeout = setTimeout(() => {
+    if (job.status !== 'running') return;
+    job.error = `upgrade_timeout_after_${timeoutMs}ms`;
+    job.phase = 'failed';
+    job.status = 'failed';
+    job.finishedAt = Date.now();
+    _appendJobOutput(job, 'stderr', `Upgrade timed out after ${Math.round(timeoutMs / 1000)}s\n`);
+    try { child.kill('SIGTERM'); } catch {}
+    delete job.child;
+    delete job.timeout;
+  }, timeoutMs);
+  if (timeout.unref) timeout.unref();
+  job.timeout = timeout;
+
+  if (child.stdout && child.stdout.on) {
+    child.stdout.on('data', (chunk) => _appendJobOutput(job, 'stdout', chunk));
+  }
+  if (child.stderr && child.stderr.on) {
+    child.stderr.on('data', (chunk) => _appendJobOutput(job, 'stderr', chunk));
+  }
+  child.on('error', (e) => {
+    if (job.finishedAt) return;
+    job.status = 'failed';
+    job.phase = 'failed';
+    job.error = e && e.message ? e.message : String(e);
+    job.finishedAt = Date.now();
+    clearTimeout(timeout);
+    _appendJobOutput(job, 'stderr', `${job.error}\n`);
+    delete job.child;
+    delete job.timeout;
+  });
+  child.on('close', async (code, signal) => {
+    if (job.finishedAt && job.status === 'failed') return;
+    clearTimeout(timeout);
+    job.code = typeof code === 'number' ? code : null;
+    job.signal = signal || '';
+    if (code === 0) {
+      job.phase = 'refreshing';
+      _appendJobOutput(job, 'system', 'Updater finished. Refreshing version status...\n');
+      if (!opts.skipRefresh) {
+        try {
+          job.refreshed = await getAgentVersionStatus({ ...opts, force: true });
+        } catch (e) {
+          job.refreshError = e && e.message ? e.message : String(e);
+          _appendJobOutput(job, 'stderr', `Version refresh failed: ${job.refreshError}\n`);
+        }
+      }
+      job.status = 'succeeded';
+      job.phase = job.refreshError ? 'refresh_failed' : 'succeeded';
+      _appendJobOutput(job, 'system', job.refreshError ? 'Upgrade command succeeded; version refresh failed.\n' : 'Upgrade complete.\n');
+    } else {
+      job.status = 'failed';
+      job.phase = 'failed';
+      job.error = job.error || `upgrade_exited_${code === null ? 'unknown' : code}`;
+      _appendJobOutput(job, 'stderr', `Upgrade failed with exit code ${code === null ? 'unknown' : code}${signal ? ` (${signal})` : ''}\n`);
+    }
+    job.finishedAt = Date.now();
+    job.updatedAt = job.finishedAt;
+    delete job.child;
+    delete job.timeout;
+  });
+
+  return { ok: true, job: _upgradeJobSnapshot(job) };
+}
+
+function _registryPackageUrl(packageName, registryBaseUrl) {
+  const base = String(registryBaseUrl || DEFAULT_REGISTRY_BASE_URL).replace(/\/+$/, '');
+  return `${base}/${encodeURIComponent(packageName)}/latest`;
+}
+
+function fetchJson(url, opts = {}) {
+  const timeoutMs = Number(opts.timeoutMs) || DEFAULT_REGISTRY_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const parsed = new URL(url);
+    const client = parsed.protocol === 'http:' ? http : https;
+    const req = client.get(parsed, {
+      headers: {
+        Accept: 'application/json',
+        'User-Agent': 'ctm-agent-version-service',
+      },
+    }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        const next = new URL(res.headers.location, parsed).toString();
+        fetchJson(next, opts).then(resolve, reject);
+        return;
+      }
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        res.resume();
+        reject(new Error(`registry_http_${res.statusCode}`));
+        return;
+      }
+      let raw = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        raw += chunk;
+        if (Buffer.byteLength(raw) > MAX_OUTPUT_BYTES) {
+          req.destroy(new Error('registry_response_too_large'));
+        }
+      });
+      res.on('end', () => {
+        if (settled) return;
+        settled = true;
+        try {
+          resolve(JSON.parse(raw));
+        } catch (e) {
+          reject(new Error(`registry_json_parse_failed: ${e.message}`));
+        }
+      });
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error('registry_timeout'));
+    });
+    req.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    });
+  });
+}
+
+async function _latestVersion(def, opts) {
+  if (!def.latest) return { version: '', source: 'none', error: '' };
+  if (def.latest.kind !== 'npm') return { version: '', source: def.latest.kind || 'unknown', error: 'unsupported_latest_source' };
+  const fetchJsonImpl = opts.fetchJsonImpl || fetchJson;
+  const url = _registryPackageUrl(def.latest.package, opts.registryBaseUrl);
+  try {
+    const body = await fetchJsonImpl(url, { timeoutMs: opts.registryTimeoutMs || DEFAULT_REGISTRY_TIMEOUT_MS });
+    return {
+      version: String(body && body.version ? body.version : '').replace(/^v/, ''),
+      source: `npm:${def.latest.package}`,
+      url,
+      error: '',
+    };
+  } catch (e) {
+    return {
+      version: '',
+      source: `npm:${def.latest.package}`,
+      url,
+      error: e && e.message ? e.message : String(e),
+    };
+  }
+}
+
+function detectInstallSource(entry, def) {
+  const combined = `${entry && entry.path ? entry.path : ''}\n${entry && entry.realpath ? entry.realpath : ''}`.toLowerCase();
+  if (!entry || !entry.available) return 'missing';
+  if (def.id === 'cursor' && combined.includes('/cursor-agent/versions/')) return 'self-update';
+  if (combined.includes('/caskroom/')) return 'homebrew-cask';
+  if (combined.includes('/cellar/')) return 'homebrew';
+  if (def.latest && def.latest.package) {
+    const packagePath = `/node_modules/${def.latest.package.toLowerCase()}/`;
+    if (combined.includes(packagePath)) return 'npm-global';
+  }
+  if (combined.includes('/node_modules/')) return 'npm-global';
+  if (def.selfUpdate) return 'self-update';
+  return 'unknown';
+}
+
+function _deriveStatus(installedVersion, latestVersion, available) {
+  if (!available) return { status: 'missing', hasUpdate: false };
+  if (!installedVersion) return { status: 'version_unknown', hasUpdate: false };
+  if (!latestVersion) return { status: 'latest_unknown', hasUpdate: false };
+  const comparison = compareSemver(installedVersion, latestVersion);
+  if (comparison === null) return { status: 'latest_unknown', hasUpdate: false };
+  if (comparison < 0) return { status: 'update_available', hasUpdate: true };
+  if (comparison > 0) return { status: 'ahead', hasUpdate: false };
+  return { status: 'current', hasUpdate: false };
+}
+
+async function _checkAgent(def, availability, opts) {
+  const entry = availability && availability.agents ? availability.agents[def.cli] : null;
+  const available = !!(entry && entry.available && !entry.stale);
+  const installSource = detectInstallSource(entry, def);
+  let versionResult = { ok: false, stdout: '', stderr: '', error: '' };
+  let installedVersion = '';
+  if (available) {
+    versionResult = await runCommand(entry.path || def.cli, def.versionArgs || ['--version'], {
+      execFileImpl: opts.execFileImpl,
+      timeoutMs: opts.versionTimeoutMs || DEFAULT_VERSION_TIMEOUT_MS,
+      env: opts.env || process.env,
+    });
+    installedVersion = parseVersionText(versionResult.stdout, versionResult.stderr);
+  }
+  const latest = await _latestVersion(def, opts);
+  const derived = _deriveStatus(installedVersion, latest.version, available);
+  const canUpgrade = available && !!(
+    def.selfUpdate ||
+    (def.packageManagers && def.packageManagers[installSource])
+  );
+  return {
+    id: def.id,
+    cli: def.cli,
+    name: def.name,
+    available,
+    path: entry && entry.path ? entry.path : null,
+    realpath: entry && entry.realpath ? entry.realpath : null,
+    installSource,
+    installedVersion,
+    latestVersion: latest.version || '',
+    latestSource: latest.source || '',
+    latestUrl: latest.url || '',
+    status: derived.status,
+    hasUpdate: derived.hasUpdate,
+    canUpgrade,
+    upgradeMode: def.selfUpdate ? 'self-update' : (def.packageManagers && def.packageManagers[installSource] ? installSource : ''),
+    versionError: available && !installedVersion ? (versionResult.error || 'version_parse_failed') : '',
+    latestError: latest.error || '',
+  };
+}
+
+function _statusMap(rows) {
+  const map = {};
+  for (const row of rows || []) {
+    if (row && row.id) map[row.id] = row;
+  }
+  return map;
+}
+
+async function checkAgentVersions(opts = {}) {
+  const now = Number(opts.now) || Date.now();
+  const agentIds = Array.isArray(opts.agentIds) && opts.agentIds.length ? opts.agentIds : DEFAULT_AGENT_IDS;
+  const defs = agentIds.map((id) => AGENT_DEFINITIONS[id]).filter(Boolean);
+  const cliBins = defs.map((def) => def.cli);
+  const availability = agentCliCache.getAvailableAgents({
+    cacheFile: opts.cliCacheFile,
+    agents: cliBins,
+    env: opts.env || process.env,
+    now,
+    extraBinDirs: opts.extraBinDirs,
+  });
+  const agents = await Promise.all(defs.map((def) => _checkAgent(def, availability, opts)));
+  const updateCount = agents.filter((agent) => agent.hasUpdate).length;
+  return {
+    ok: true,
+    version: CACHE_VERSION,
+    generatedAt: now,
+    cached: false,
+    updateCount,
+    agents: _statusMap(agents),
+  };
+}
+
+async function getAgentVersionStatus(opts = {}) {
+  const now = Number(opts.now) || Date.now();
+  const ttlMs = Number(opts.ttlMs) || DEFAULT_TTL_MS;
+  if (!opts.force && opts.cacheFile) {
+    const cached = _readJson(opts.cacheFile);
+    if (cached && cached.version === CACHE_VERSION && cached.generatedAt && now - cached.generatedAt < ttlMs && cached.agents) {
+      return { ...cached, cached: true };
+    }
+  }
+  const status = await checkAgentVersions({ ...opts, now });
+  if (opts.cacheFile) {
+    try { _writeJson(opts.cacheFile, status); } catch (e) {
+      return { ...status, cacheError: e && e.message ? e.message : String(e) };
+    }
+  }
+  return status;
+}
+
+function _getDefinition(agentId) {
+  const def = AGENT_DEFINITIONS[String(agentId || '')];
+  if (!def) throw new Error('unknown_agent');
+  return def;
+}
+
+function buildUpgradePlan(agentId, statusPayload) {
+  const def = _getDefinition(agentId);
+  const row = statusPayload && statusPayload.agents ? statusPayload.agents[def.id] : null;
+  if (!row || !row.available) throw new Error('agent_not_available');
+  let command = row.path || def.cli;
+  let args = null;
+  let commandKind = '';
+  let commandLabel = '';
+  if (def.selfUpdate) {
+    args = def.selfUpdate.args.slice();
+    commandKind = 'self-update';
+    commandLabel = def.selfUpdate.label;
+  } else if (def.packageManagers && def.packageManagers[row.installSource]) {
+    const manager = def.packageManagers[row.installSource];
+    command = manager.command;
+    args = manager.args.slice();
+    commandKind = row.installSource;
+    commandLabel = manager.label;
+  }
+  if (!args) throw new Error('upgrade_not_supported_for_install_source');
+  return {
+    ok: true,
+    agent: def.id,
+    name: def.name,
+    currentVersion: row.installedVersion || '',
+    latestVersion: row.latestVersion || '',
+    status: row.status || '',
+    hasUpdate: !!row.hasUpdate,
+    installSource: row.installSource || '',
+    command,
+    args,
+    commandKind,
+    commandLabel,
+    changes: [
+      { description: row.latestVersion ? `Upgrade ${def.name} from ${row.installedVersion || 'unknown'} to ${row.latestVersion}` : `Run ${def.name}'s updater to check for the latest version` },
+      { description: `Command: ${commandLabel || [path.basename(command)].concat(args).join(' ')}` },
+    ],
+  };
+}
+
+async function upgradeAgentVersion(agentId, opts = {}) {
+  const status = opts.statusPayload || await getAgentVersionStatus({ ...opts, force: false });
+  const plan = buildUpgradePlan(agentId, status);
+  const result = await runCommand(plan.command, plan.args, {
+    execFileImpl: opts.execFileImpl,
+    timeoutMs: opts.upgradeTimeoutMs || DEFAULT_UPGRADE_TIMEOUT_MS,
+    env: opts.env || process.env,
+  });
+  if (!result.ok) {
+    const error = new Error(result.error || 'upgrade_failed');
+    error.result = result;
+    error.plan = plan;
+    throw error;
+  }
+  const refreshed = opts.skipRefresh
+    ? null
+    : await getAgentVersionStatus({ ...opts, force: true });
+  return {
+    ok: true,
+    plan,
+    result,
+    refreshed,
+  };
+}
+
+module.exports = {
+  AGENT_DEFINITIONS,
+  CACHE_VERSION,
+  DEFAULT_AGENT_IDS,
+  compareSemver,
+  normalizeSemver,
+  parseVersionText,
+  redactOutput,
+  detectInstallSource,
+  checkAgentVersions,
+  getAgentVersionStatus,
+  buildUpgradePlan,
+  upgradeAgentVersion,
+  startUpgradeJob,
+  getUpgradeJob,
+  listUpgradeJobs,
+  _registryPackageUrl,
+  _upgradeJobs,
+};