@yemi33/minions 0.1.1587 → 0.1.1589

package/engine/model-discovery.js

@@ -0,0 +1,167 @@
+/**
+ * engine/model-discovery.js — Per-runtime model catalog cache + REST helpers.
+ *
+ * Backs the dashboard endpoints:
+ *   GET  /api/runtimes                        → listAllRuntimes()
+ *   GET  /api/runtimes/:name/models           → getRuntimeModels(name)
+ *   POST /api/runtimes/:name/models/refresh   → invalidateRuntimeModelsCache(name)
+ *                                              → getRuntimeModels(name, { force: true })
+ *
+ * Cache shape (per-runtime file at `adapter.modelsCache`):
+ *   { runtime: 'copilot', models: [{ id, name, provider }, ...] | null, cachedAt: ISO }
+ *
+ * Returning `{ models: null }` is the universal "free-text fallback" signal —
+ * the settings UI renders a free-text input instead of a dropdown. It happens in
+ * four cases:
+ *   1. `config.engine.disableModelDiscovery === true` (fleet-wide opt-out)
+ *   2. `adapter.capabilities.modelDiscovery !== true` (e.g. Claude — no API)
+ *   3. `adapter.listModels()` resolves to null/empty (no token, network error)
+ *   4. `adapter.listModels()` throws (transient API error — caller treats as null)
+ *
+ * Cache is persisted only when discovery actually ran (cases 3+4 still write a
+ * `{ models: null }` cache so we don't hammer the API on every refresh — TTL
+ * eventually re-tries). Cases 1+2 skip the cache write entirely.
+ */
+
+const fs = require('fs');
+const { resolveRuntime, listRuntimes } = require('./runtimes');
+
+// 1 hour — matches the spec ("< 1hr TTL"). Keep separate from ENGINE_DEFAULTS
+// so the test suite can override per-call without polluting the global config.
+const MODEL_CACHE_TTL_MS = 60 * 60 * 1000;
+
+function _readCacheFile(p) {
+  try {
+    const text = fs.readFileSync(p, 'utf8');
+    const obj = JSON.parse(text);
+    if (obj && typeof obj === 'object') return obj;
+  } catch { /* missing / malformed → cache miss */ }
+  return null;
+}
+
+function _writeCacheFile(p, obj) {
+  try { fs.writeFileSync(p, JSON.stringify(obj, null, 2)); } catch { /* best effort */ }
+}
+
+/**
+ * Return the registered runtime catalog for `GET /api/runtimes`.
+ *
+ * Shape: `[{ name, capabilities }, ...]`. Capabilities are spread into a fresh
+ * object so callers can't mutate the adapter's authoritative capability block.
+ */
+function listAllRuntimes() {
+  const names = listRuntimes();
+  const runtimes = [];
+  for (const name of names) {
+    let adapter;
+    try { adapter = resolveRuntime(name); } catch { continue; }
+    runtimes.push({
+      name,
+      capabilities: { ...(adapter && adapter.capabilities ? adapter.capabilities : {}) },
+    });
+  }
+  return runtimes;
+}
+
+/**
+ * Read or refresh the cached model list for a runtime.
+ *
+ * @param {string} runtimeName  Must be a registered runtime — caller maps the
+ *                              `Unknown runtime` throw onto an HTTP 404.
+ * @param {object} opts
+ * @param {boolean} opts.force  Skip the cache and call `listModels()` directly.
+ * @param {number}  opts.ttlMs  Cache freshness window (default 1h). Tests use a
+ *                              tiny window to exercise the miss path.
+ * @param {object}  opts.config Pass `getConfig()` result so the helper can
+ *                              honour `config.engine.disableModelDiscovery`
+ *                              without re-reading the file on every request.
+ * @returns {Promise<{runtime: string, models: object[]|null, cachedAt: string|null}>}
+ */
+async function getRuntimeModels(runtimeName, { force = false, ttlMs = MODEL_CACHE_TTL_MS, config = null } = {}) {
+  // Throws "Unknown runtime ..." for unregistered names. Caller turns this into
+  // a 404; bubbling the throw is intentional so misconfigurations surface loudly
+  // (mirrors the registry contract documented in engine/runtimes/index.js).
+  const adapter = resolveRuntime(runtimeName);
+
+  // Case 1: fleet-wide opt-out. Skip the adapter entirely — never call its
+  // listModels() (which can hit the network) when the user explicitly disabled
+  // discovery. No cache write either; flipping the flag back on must produce a
+  // fresh fetch, not a stale `null` cache hit.
+  if (config && config.engine && config.engine.disableModelDiscovery === true) {
+    return { runtime: runtimeName, models: null, cachedAt: null };
+  }
+
+  // Case 2: adapter doesn't support discovery (Claude). Same short-circuit —
+  // don't write a cache file (`engine/claude-models.json` stays absent / empty
+  // per the spec: "engine/claude-models.json (always null)").
+  if (!adapter.capabilities || adapter.capabilities.modelDiscovery !== true) {
+    return { runtime: runtimeName, models: null, cachedAt: null };
+  }
+
+  const cachePath = adapter.modelsCache || null;
+
+  // Cache hit path — only on non-forced reads. We accept any cached payload
+  // whose `cachedAt` parses to a valid timestamp within the TTL window;
+  // `models: null` cached entries also count as fresh so we don't re-hit the
+  // API every page load when the token is missing.
+  if (!force && cachePath) {
+    const cached = _readCacheFile(cachePath);
+    if (cached && typeof cached.cachedAt === 'string') {
+      const ts = Date.parse(cached.cachedAt);
+      if (Number.isFinite(ts)) {
+        const age = Date.now() - ts;
+        if (age >= 0 && age < ttlMs) {
+          const models = Array.isArray(cached.models) ? cached.models : null;
+          return { runtime: runtimeName, models, cachedAt: cached.cachedAt };
+        }
+      }
+    }
+  }
+
+  // Cache miss / forced refresh — call the adapter. Any failure (null return,
+  // empty array, throw) collapses to `models: null` so the dashboard falls back
+  // to free-text input. We do NOT distinguish "API unreachable" from "API
+  // returned an empty list" — both are unactionable from a UI standpoint.
+  let models = null;
+  try {
+    const result = await adapter.listModels();
+    if (Array.isArray(result) && result.length > 0) {
+      // Defensive copy — adapter caches its own result internally and we don't
+      // want that to be mutable through the response we return.
+      models = result.map(m => ({ ...m }));
+    }
+  } catch { /* swallow — network/transient errors map to null */ }
+
+  const cachedAt = new Date().toISOString();
+  if (cachePath) {
+    _writeCacheFile(cachePath, { runtime: runtimeName, models, cachedAt });
+  }
+  return { runtime: runtimeName, models, cachedAt };
+}
+
+/**
+ * Delete the cached models file for a runtime. Returns `true` if a file was
+ * removed, `false` if there was nothing to remove. Throws on unknown runtime
+ * (caller maps to 404). Filesystem errors other than ENOENT propagate so the
+ * route handler can surface a real I/O failure to the operator instead of
+ * silently no-oping.
+ */
+function invalidateRuntimeModelsCache(runtimeName) {
+  const adapter = resolveRuntime(runtimeName);
+  const cachePath = adapter && adapter.modelsCache;
+  if (!cachePath) return false;
+  try {
+    fs.unlinkSync(cachePath);
+    return true;
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return false;
+    throw e;
+  }
+}
+
+module.exports = {
+  listAllRuntimes,
+  getRuntimeModels,
+  invalidateRuntimeModelsCache,
+  MODEL_CACHE_TTL_MS,
+};

package/engine/preflight.js

@@ -1,6 +1,11 @@
 /**
  * engine/preflight.js — Prerequisite and health checks for Minions.
  * Used by `minions init`, `minions start`, and `minions doctor`.
+ *
+ * Per-runtime binary + model-discovery checks (P-9e8a3f1d) — for every distinct
+ * CLI in use across `engine.defaultCli`, `engine.ccCli`, and `agents.<id>.cli`,
+ * we resolve the adapter from the registry and run its `resolveBinary()`. The
+ * cache is warmed via `listModels()` when the runtime supports discovery.
  */
 
 const fs = require('fs');
@@ -8,9 +13,12 @@ const path = require('path');
 const { execSync } = require('child_process');
 
 /**
- * Resolve the Claude Code CLI binary path.
+ * Resolve the Claude Code CLI binary path. Legacy helper preserved for back-
+ * compat — the runtime registry's `resolveRuntime('claude').resolveBinary()`
+ * is now the canonical resolver. This wrapper only exists so external tooling
+ * that still calls `findClaudeBinary()` keeps working until cleanup ships.
+ *
  * Returns the path if found, null otherwise.
- * Reuses the same search logic as spawn-agent.js.
  */
 function findClaudeBinary() {
   const searchPaths = [
@@ -71,6 +79,91 @@ function findClaudeBinary() {
   return null;
 }
 
+// ─── Runtime fleet enumeration (P-9e8a3f1d) ─────────────────────────────────
+
+/**
+ * Collect the unique set of CLI runtimes that any part of the fleet would
+ * spawn given a config. Mirrors the union scanned by
+ * `shared.runtimeConfigWarnings` so unknown-CLI warnings and binary checks
+ * always cover the same surface.
+ *
+ * Without a config (legacy callers), returns just `['claude']` — the
+ * historical default.
+ */
+function _distinctRuntimes(config) {
+  const set = new Set();
+  if (!config || typeof config !== 'object') {
+    set.add('claude');
+    return Array.from(set);
+  }
+  const engine = config.engine || {};
+  set.add(engine.defaultCli ? String(engine.defaultCli) : 'claude');
+  if (engine.ccCli) set.add(String(engine.ccCli));
+  for (const agent of Object.values(config.agents || {})) {
+    if (agent && agent.cli) set.add(String(agent.cli));
+  }
+  return Array.from(set).sort();
+}
+
+/**
+ * Try to resolve a runtime's binary via the registry. Returns a preflight
+ * result entry — never throws. Unknown-runtime errors collapse to a single
+ * warn entry so the rest of the loop keeps running.
+ */
+function _checkRuntimeBinary(runtimeName) {
+  let adapter;
+  try {
+    adapter = require('./runtimes').resolveRuntime(runtimeName);
+  } catch (e) {
+    return {
+      name: `Runtime: ${runtimeName}`,
+      ok: false,
+      message: `unknown runtime — ${e.message}`,
+    };
+  }
+  let resolved = null;
+  try { resolved = adapter.resolveBinary({ env: process.env }); }
+  catch { /* defensive — treat any throw as "not found" so the loop keeps running */ }
+  if (resolved && resolved.bin) {
+    const shim = resolved.native === false ? ' (node shim)' : '';
+    const lead = Array.isArray(resolved.leadingArgs) && resolved.leadingArgs.length
+      ? ` (leadingArgs: ${resolved.leadingArgs.join(' ')})` : '';
+    return {
+      name: `Runtime: ${runtimeName}`,
+      ok: true,
+      message: `${resolved.bin}${shim}${lead}`,
+    };
+  }
+  const hint = (typeof adapter.installHint === 'string' && adapter.installHint)
+    ? adapter.installHint
+    : `${runtimeName} CLI binary not found on PATH`;
+  return {
+    name: `Runtime: ${runtimeName}`,
+    ok: false,
+    message: `not found — ${hint}`,
+  };
+}
+
+/**
+ * Fire-and-forget cache warm. We never await: cache warming is a side effect
+ * for the next dashboard / doctor read, not something runPreflight should
+ * block on. Errors are swallowed — discovery is best-effort.
+ *
+ * Silent no-op when the runtime can't enumerate models (Claude has no public
+ * mechanism, hence `capabilities.modelDiscovery: false`) or when the user
+ * explicitly disabled discovery via `engine.disableModelDiscovery`. Those
+ * branches live inside `model-discovery.getRuntimeModels`, so we just delegate.
+ */
+function _warmModelCache(runtimeName, config) {
+  if (!runtimeName) return;
+  let md;
+  try { md = require('./model-discovery'); }
+  catch { return; /* legacy installs may not have model-discovery yet */ }
+  Promise.resolve()
+    .then(() => md.getRuntimeModels(runtimeName, { config }))
+    .catch(() => { /* swallow — best effort */ });
+}
+
 /**
  * Run prerequisite checks. Returns { passed, results } where results is an
  * array of { name, ok, message } objects.
@@ -78,6 +171,7 @@ function findClaudeBinary() {
  * Options:
  *   - warnOnly: if true, missing items don't cause passed=false (for init)
  *   - verbose: include extra detail in messages
+ *   - config:  fleet config for runtime checks + runtime-config warnings
  */
 function runPreflight(opts = {}) {
   const results = [];
@@ -102,18 +196,37 @@ function runPreflight(opts = {}) {
     allOk = false;
   }
 
-  // 3. Claude Code CLI
-  const claudeBin = findClaudeBinary();
-  if (claudeBin) {
-    const isNative = !claudeBin.endsWith('cli.js');
-    const label = isNative ? 'native' : path.basename(path.dirname(path.dirname(claudeBin)));
-    results.push({ name: 'Claude Code CLI', ok: true, message: label });
-  } else {
-    results.push({ name: 'Claude Code CLI', ok: false, message: 'not found — install from https://claude.ai/download or: npm install -g @anthropic-ai/claude-code' });
-    allOk = false;
+  // 3. Per-runtime binary check (P-9e8a3f1d). Legacy single-runtime callers
+  //    (no config passed) still get exactly one entry — for `claude` — so the
+  //    historical "3 results" shape is preserved.
+  const runtimes = _distinctRuntimes(opts.config);
+  for (const runtimeName of runtimes) {
+    const r = _checkRuntimeBinary(runtimeName);
+    if (r.ok === false) allOk = false;
+    results.push(r);
+    // Warm the model cache in the background — silent no-op when the
+    // runtime can't enumerate or the user disabled discovery.
+    if (opts.config) _warmModelCache(runtimeName, opts.config);
   }
 
-  // Auth is handled by Claude Code itself (API key, Claude Max, etc.) — no check needed here.
+  // Auth is handled by each runtime CLI itself (Claude API key, GH_TOKEN for
+  // Copilot, etc.) — preflight doesn't probe credentials.
+
+  // 4. Runtime fleet config warnings (P-3b8e5f1d) — only when the caller hands
+  //    us the config. checkOrExit() / cli start() / doctor() pass it; legacy
+  //    callers don't, in which case we skip silently.
+  if (opts && opts.config && typeof opts.config === 'object') {
+    try {
+      const shared = require('./shared');
+      let runtimeNames = [];
+      try { runtimeNames = require('./runtimes').listRuntimes(); }
+      catch { /* registry may be missing during partial installs */ }
+      const warns = shared.runtimeConfigWarnings(opts.config, runtimeNames);
+      for (const w of warns) {
+        results.push({ name: `Runtime config (${w.id})`, ok: 'warn', message: w.message });
+      }
+    } catch { /* defensive — preflight must never throw */ }
+  }
 
   return { passed: allOk, results };
 }
@@ -125,7 +238,7 @@ function printPreflight(results, { label = 'Preflight checks' } = {}) {
   console.log(`\n  ${label}:\n`);
   let allOk = true;
   for (const r of results) {
-    const icon = r.ok === true ? '\u2713' : r.ok === 'warn' ? '!' : '\u2717';
+    const icon = r.ok === true ? '✓' : r.ok === 'warn' ? '!' : '✗';
     const prefix = r.ok === true ? '  ' : r.ok === 'warn' ? '  ' : '  ';
     console.log(`${prefix} ${icon} ${r.name}: ${r.message}`);
     if (r.ok === false) allOk = false;
@@ -148,12 +261,108 @@ function checkOrExit({ exitOnFail = false, label = 'Preflight checks' } = {}) {
   return ok;
 }
 
+// ─── Doctor extras (P-9e8a3f1d) ─────────────────────────────────────────────
+
+const _FEATURE_FLAG_DEFAULTS = {
+  claudeBareMode: false,
+  claudeFallbackModel: undefined,
+  copilotDisableBuiltinMcps: true,
+  copilotSuppressAgentsMd: true,
+  copilotStreamMode: 'on',
+  copilotReasoningSummaries: false,
+  maxBudgetUsd: undefined,
+  disableModelDiscovery: false,
+};
+
+/**
+ * Build the fleet-defaults summary entries surfaced by `minions doctor`.
+ * Three classes of output:
+ *   1. `Fleet` — `defaultCli` + `defaultModel`
+ *   2. `CC overrides` — only when `ccCli` or `ccModel` is set
+ *   3. `Active fleet flags` — only when any feature flag deviates from default
+ */
+function _fleetSummaryResults(config) {
+  const results = [];
+  if (!config || typeof config !== 'object') return results;
+  const engine = config.engine || {};
+  const defaultCli = engine.defaultCli ? String(engine.defaultCli) : 'claude';
+  const defaultModel = engine.defaultModel ? String(engine.defaultModel) : '(runtime default)';
+  results.push({ name: 'Fleet', ok: true, message: `defaultCli=${defaultCli}  defaultModel=${defaultModel}` });
+
+  const ccBits = [];
+  if (engine.ccCli) ccBits.push(`ccCli=${engine.ccCli}`);
+  if (engine.ccModel) ccBits.push(`ccModel=${engine.ccModel}`);
+  if (ccBits.length > 0) {
+    results.push({ name: 'CC overrides', ok: true, message: ccBits.join('  ') });
+  }
+
+  const nonDefault = [];
+  for (const [k, def] of Object.entries(_FEATURE_FLAG_DEFAULTS)) {
+    if (engine[k] === undefined) continue;
+    if (engine[k] !== def) nonDefault.push(`${k}=${JSON.stringify(engine[k])}`);
+  }
+  if (nonDefault.length > 0) {
+    results.push({ name: 'Active fleet flags', ok: true, message: nonDefault.join('  ') });
+  }
+  return results;
+}
+
 /**
- * Run extended doctor checks (preflight + runtime health).
+ * Build the per-runtime model-discovery entries surfaced by `minions doctor`.
+ * Emits one entry per distinct runtime in the fleet:
+ *   - "discovery disabled (engine.disableModelDiscovery)" — fleet-wide opt-out
+ *   - "discovery unavailable (no enumeration mechanism)" — adapter doesn't support it
+ *   - "<N> models cached" — listModels returned a non-empty array
+ *   - "discovery unavailable (...)" — listModels returned null/threw (no token, transient API error)
+ */
+async function _modelDiscoveryResults(config) {
+  const results = [];
+  if (!config || typeof config !== 'object') return results;
+  let md;
+  try { md = require('./model-discovery'); } catch { return results; }
+  let registry;
+  try { registry = require('./runtimes'); } catch { return results; }
+  const fleetDisabled = config.engine && config.engine.disableModelDiscovery === true;
+  const runtimes = _distinctRuntimes(config);
+  for (const runtimeName of runtimes) {
+    let adapter;
+    try { adapter = registry.resolveRuntime(runtimeName); }
+    catch { continue; /* unknown-cli warning was already emitted by runtimeConfigWarnings */ }
+
+    if (fleetDisabled) {
+      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery disabled (engine.disableModelDiscovery)' });
+      continue;
+    }
+    if (!adapter.capabilities || adapter.capabilities.modelDiscovery !== true) {
+      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery unavailable (no enumeration mechanism)' });
+      continue;
+    }
+    try {
+      const out = await md.getRuntimeModels(runtimeName, { config });
+      if (Array.isArray(out.models) && out.models.length > 0) {
+        results.push({ name: `Models: ${runtimeName}`, ok: true, message: `${out.models.length} models cached` });
+      } else {
+        results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: 'discovery unavailable (API returned no models — check token)' });
+      }
+    } catch (e) {
+      results.push({ name: `Models: ${runtimeName}`, ok: 'warn', message: `discovery error — ${e && e.message ? e.message : 'unknown'}` });
+    }
+  }
+  return results;
+}
+
+/**
+ * Run extended doctor checks (preflight + runtime health + fleet summary +
+ * per-runtime model discovery).
  * Requires minionsHome path for runtime checks.
  */
 function doctor(minionsHome) {
-  const { passed, results } = runPreflight();
+  // Read config first so preflight can include runtime-fleet warnings.
+  const configPathForPreflight = path.join(minionsHome, 'config.json');
+  let preflightConfig = null;
+  try { preflightConfig = JSON.parse(fs.readFileSync(configPathForPreflight, 'utf8')); }
+  catch { /* missing/invalid config is its own check below */ }
+  const { passed, results } = runPreflight({ config: preflightConfig });
 
   // Runtime checks
   const runtimeResults = [];
@@ -248,12 +457,11 @@ function doctor(minionsHome) {
     req.on('timeout', () => { req.destroy(); resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash' }); });
   });
 
-  return dashCheck.then(dashResult => {
+  return dashCheck.then(async dashResult => {
     runtimeResults.push(dashResult);
 
     // Check playbooks
     const playbooksDir = path.join(minionsHome, 'playbooks');
-    // Discover all .md playbooks in the directory — don't hardcode
     let playbooks = [];
     try { playbooks = fs.readdirSync(playbooksDir).filter(f => f.endsWith('.md')); } catch { /* dir may not exist */ }
     if (playbooks.length > 0) {
@@ -264,10 +472,17 @@ function doctor(minionsHome) {
 
     // Check port 7331 availability (only if dashboard isn't running)
     if (dashResult.ok !== true) {
-      // Dashboard isn't running, port should be free
       runtimeResults.push({ name: 'Port 7331', ok: 'warn', message: 'dashboard not running — port status unknown' });
     }
 
+    // Fleet defaults + per-runtime model discovery (P-9e8a3f1d). Both depend
+    // on the config that we already loaded above; re-using `preflightConfig`
+    // avoids a second JSON.parse round-trip.
+    const fleetSummary = _fleetSummaryResults(preflightConfig);
+    runtimeResults.push(...fleetSummary);
+    const modelResults = await _modelDiscoveryResults(preflightConfig);
+    runtimeResults.push(...modelResults);
+
     // Print all
     const allResults = [...results, ...runtimeResults];
     const ok = printPreflight(allResults, { label: 'Minions Doctor' });
@@ -286,4 +501,17 @@ function doctor(minionsHome) {
   });
 }
 
-module.exports = { findClaudeBinary, runPreflight, printPreflight, checkOrExit, doctor };
+module.exports = {
+  findClaudeBinary,
+  runPreflight,
+  printPreflight,
+  checkOrExit,
+  doctor,
+  // Exposed for unit tests (P-9e8a3f1d) — engine code MUST go through
+  // runPreflight/doctor, never these helpers directly.
+  _distinctRuntimes,
+  _checkRuntimeBinary,
+  _warmModelCache,
+  _fleetSummaryResults,
+  _modelDiscoveryResults,
+};