@yemi33/minions 0.1.1698 → 0.1.1699

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.1699 (2026-05-04)
+
+### Features
+-  Gracefully handle missing runtime across Command Center and LLM call sites
+
+### Fixes
+- yemi33/minions#2022
+
 ## 0.1.1698 (2026-05-04)
 
 ### Features

package/dashboard.js

@@ -1825,6 +1825,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
     if (onAbortReady) onAbortReady(p1.abort);
     result = await p1;
     llm.trackEngineUsage(label, result.usage);
+    if (result.missingRuntime) return result;
 
     if (result.text) {
       updateSession(store, sessionKey, result.sessionId || sessionId, true);
@@ -1862,6 +1863,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   if (onAbortReady) onAbortReady(p2.abort);
   result = await p2;
   llm.trackEngineUsage(label, result.usage);
+  if (result.missingRuntime) return result;
 
   if (result.text) {
     updateSession(store, sessionKey, result.sessionId, false);
@@ -1879,6 +1881,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   if (onAbortReady) onAbortReady(p3.abort);
   result = await p3;
   llm.trackEngineUsage(label, result.usage);
+  if (result.missingRuntime) return result;
 
   if (result.text) {
     updateSession(store, sessionKey, result.sessionId, false);
@@ -1912,6 +1915,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
     if (onAbortReady) onAbortReady(p1.abort);
     result = await p1;
     llm.trackEngineUsage(label, result.usage);
+    if (result.missingRuntime) return result;
 
     if (result.text) {
       updateSession(store, sessionKey, result.sessionId || sessionId, true);
@@ -1948,6 +1952,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
   if (onAbortReady) onAbortReady(p2.abort);
   result = await p2;
   llm.trackEngineUsage(label, result.usage);
+  if (result.missingRuntime) return result;
 
   if (result.text) {
     updateSession(store, sessionKey, result.sessionId, false);
@@ -1966,6 +1971,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
   if (onAbortReady) onAbortReady(p3.abort);
   result = await p3;
   llm.trackEngineUsage(label, result.usage);
+  if (result.missingRuntime) return result;
 
   if (result.text) {
     updateSession(store, sessionKey, result.sessionId, false);
@@ -2071,6 +2077,10 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     if (session) session._docHash = docHash;
   }
 
+  if (result.missingRuntime) {
+    return { answer: result.text || result.stderr || 'Minions runtime is not installed or configured.', content: null, actions: [] };
+  }
+
   if (result.code !== 0 || !result.text) {
     console.error(`[doc-chat] Failed: code=${result.code}, empty=${!result.text}, filePath=${filePath}, stderr=${(result.stderr || '').slice(0, 200)}`);
     return { answer: 'Failed to process request. Try again.', content: null, actions: [] };
@@ -2125,6 +2135,10 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
     if (session) session._docHash = docHash;
   }
 
+  if (result.missingRuntime) {
+    return { answer: result.text || result.stderr || 'Minions runtime is not installed or configured.', content: null, actions: [] };
+  }
+
   if (result.code !== 0 || !result.text) {
     console.error(`[doc-chat-stream] Failed: code=${result.code}, empty=${!result.text}, filePath=${filePath}, stderr=${(result.stderr || '').slice(0, 200)}`);
     return { answer: 'Failed to process request. Try again.', content: null, actions: [] };
@@ -5054,6 +5068,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         _ccHeartbeatTimer = null;
       }
     };
+    const finishMissingRuntime = (result, liveState) => {
+      const text = result.text || result.stderr || 'Minions runtime is not installed or configured.';
+      liveState.donePayload = { type: 'done', text, actions: [], sessionId: null, missingRuntime: true };
+      if (liveState.writer) liveState.writer(liveState.donePayload);
+      if (liveState.endResponse) liveState.endResponse();
+      _scheduleCcLiveCleanup(tabId);
+    };
     try {
       const body = await readBody(req);
       if (!body.message && !body.reconnect) { res.statusCode = 400; res.end('message required'); return; }
@@ -5176,6 +5197,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const result = await llmPromise;
         trackUsage('command-center', result.usage);
 
+        if (result.missingRuntime) {
+          finishMissingRuntime(result, liveState);
+          return;
+        }
+
         // Handle failure — non-zero exit with text = max_turns or partial success, still usable
         if (!result.text && wasResume && result.code !== 0 && !req.destroyed) {
           // Resume failed (stale/expired session) — auto-retry as fresh session (skip if client already disconnected)
@@ -5198,6 +5224,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             Object.assign(result, retryResult);
           }
         }
+        if (result.missingRuntime) {
+          finishMissingRuntime(result, liveState);
+          return;
+        }
         if (!result.text) {
           if (req.destroyed) { _ccStreamEnded = true; return; } // client already gone — nothing to send
           const debugInfo = result.code !== 0 ? `(exit code ${result.code})` : '(empty response)';
@@ -5381,6 +5411,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         model: 'haiku', maxTurns: 1, timeout: 30000, label: 'schedule-parse', direct: true,
         engineConfig: CONFIG.engine,
       });
+      if (result.missingRuntime) {
+        return jsonReply(res, 503, { error: result.text || result.stderr || 'Minions runtime is not installed or configured.', missingRuntime: true });
+      }
       const parsed = JSON.parse(result.text.trim());
       if (!parsed.cron) return jsonReply(res, 422, { error: 'Could not parse schedule' });
       return jsonReply(res, 200, { cron: parsed.cron, description: parsed.description || '' });

package/engine/consolidation.js

@@ -201,6 +201,10 @@ function consolidateWithLLM(items, existingNotes, files, config) {
     if (_cleared) return;
     clearTimeout(timeoutHandle);
     trackEngineUsage('consolidation', result.usage);
+    if (result.missingRuntime) {
+      _fallback(`LLM consolidation skipped: ${result.text || result.stderr || 'runtime unavailable'} — falling back to regex`);
+      return;
+    }
 
     const extractedText = result.text || '';
     const rawText = result.raw || '';

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-04T06:31:58.762Z"
+  "cachedAt": "2026-05-04T06:56:12.183Z"
 }

package/engine/kb-sweep.js

@@ -135,6 +135,10 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
         engineConfig: opts.engineConfig,
       });
       trackEngineUsage('kb-sweep', result.usage);
+      if (result.missingRuntime) {
+        log('warn', `[kb-sweep] batch ${b + 1} LLM skipped: ${result.text || result.stderr || 'runtime unavailable'}`);
+        continue;
+      }
     } catch (e) { log('warn', `[kb-sweep] batch ${b + 1} LLM error: ${e.message}`); continue; }
 
     let batchPlan;
@@ -212,6 +216,10 @@ ${body}`;
           engineConfig: opts.engineConfig,
         });
         trackEngineUsage('kb-sweep', result.usage);
+        if (result.missingRuntime) {
+          log('warn', `[kb-sweep] rewrite ${c.entry.category}/${c.entry.file} skipped: ${result.text || result.stderr || 'runtime unavailable'}`);
+          continue;
+        }
         let newBody = (result.text || '').trim();
         // Strip accidental code fence
         const fence = newBody.match(/^```(?:markdown|md)?\s*([\s\S]*?)```$/);

package/engine/llm.js

@@ -23,6 +23,7 @@ const { resolveRuntime } = require('./runtimes');
 const MINIONS_DIR = shared.MINIONS_DIR;
 const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
 const COPILOT_TASK_COMPLETE_GRACE_MS = 3000;
+const MISSING_RUNTIME_EXIT_CODE = 78;
 
 // ─── Engine-Usage Metrics ────────────────────────────────────────────────────
 
@@ -96,6 +97,85 @@ function _resolveBin(runtime) {
 
 function _resetBinCache() { _binCache.clear(); }
 
+function _runtimeInstallHint(runtimeName, runtime) {
+  if (runtime && typeof runtime.installHint === 'string' && runtime.installHint) return runtime.installHint;
+  return `install the ${runtimeName || 'selected'} CLI and make sure it is on PATH`;
+}
+
+function _missingRuntimeMessage(runtimeName, runtime, reason) {
+  const selected = runtime?.name || runtimeName || 'configured';
+  if (!runtime) {
+    return [
+      `Minions can't run the configured runtime "${selected}".`,
+      '',
+      reason || 'The configured runtime is not registered.',
+      '',
+      'Choose a supported runtime in Settings -> Engine -> defaultCli/ccCli, then install its CLI:',
+      '- Claude Code: npm install -g @anthropic-ai/claude-code or download from https://claude.ai/download',
+      '- GitHub Copilot CLI: install via GitHub CLI/gh-copilot or download from https://github.com/github/copilot-cli/releases',
+      '',
+      'After installing, restart Minions so the dashboard and engine inherit the updated PATH.',
+    ].join('\n');
+  }
+  const lines = [
+    `Minions can't run the "${selected}" runtime yet.`,
+    '',
+    reason || `The ${selected} CLI binary was not found on PATH.`,
+    '',
+    `Install steps for "${selected}": ${_runtimeInstallHint(selected, runtime)}.`,
+    '',
+    'After installing, restart Minions so the dashboard and engine inherit the updated PATH.',
+  ];
+  if (selected !== 'claude') {
+    lines.push('Or switch Settings -> Engine -> defaultCli/ccCli back to "claude" after installing Claude Code.');
+  } else {
+    lines.push('Or switch Settings -> Engine -> defaultCli/ccCli to "copilot" after installing GitHub Copilot CLI.');
+  }
+  return lines.join('\n');
+}
+
+function _missingRuntimeResult(runtimeName, runtime, reason) {
+  const message = _missingRuntimeMessage(runtimeName, runtime, reason);
+  return {
+    text: message,
+    usage: null,
+    sessionId: null,
+    code: MISSING_RUNTIME_EXIT_CODE,
+    stderr: message,
+    raw: '',
+    toolUses: [],
+    runtime: runtime?.name || runtimeName || null,
+    errorClass: shared.FAILURE_CLASS.CONFIG_ERROR,
+    missingRuntime: true,
+  };
+}
+
+function _resolvedCallResult(result) {
+  const promise = Promise.resolve(result);
+  promise.abort = () => {};
+  return promise;
+}
+
+function _resolveRuntimeNameFor(callOpts = {}) {
+  let runtimeName = callOpts.cli;
+  if (!runtimeName && callOpts.engineConfig) runtimeName = resolveCcCli(callOpts.engineConfig);
+  return runtimeName || 'claude';
+}
+
+function _runtimeUnavailableResult(callOpts = {}) {
+  const runtimeName = _resolveRuntimeNameFor(callOpts);
+  let runtime = null;
+  try {
+    runtime = resolveRuntime(runtimeName);
+  } catch (err) {
+    return _missingRuntimeResult(runtimeName, null, err.message);
+  }
+  if (!_resolveBin(runtime)) {
+    return _missingRuntimeResult(runtimeName, runtime, `The ${runtime.name} CLI binary was not found on PATH or in the runtime cache.`);
+  }
+  return null;
+}
+
 // ─── Spawn Helpers ───────────────────────────────────────────────────────────
 
 /**
@@ -386,10 +466,7 @@ function _createStreamAccumulator({
 function _resolveRuntimeFor(callOpts) {
   // Explicit `cli` opt wins; otherwise fall to `engineConfig` resolution;
   // otherwise default to claude (the historical behavior).
-  let runtimeName = callOpts.cli;
-  if (!runtimeName && callOpts.engineConfig) runtimeName = resolveCcCli(callOpts.engineConfig);
-  if (!runtimeName) runtimeName = 'claude';
-  return resolveRuntime(runtimeName);
+  return resolveRuntime(_resolveRuntimeNameFor(callOpts));
 }
 
 function _resolveModelFor(callOpts) {
@@ -434,6 +511,9 @@ function callLLM(promptText, sysPromptText, opts = {}) {
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
   } = opts;
 
+  const unavailable = _runtimeUnavailableResult({ cli: cliOverride, engineConfig });
+  if (unavailable) return _resolvedCallResult(unavailable);
+
   const runtime = _resolveRuntimeFor({ cli: cliOverride, engineConfig });
   const model = _resolveModelForRuntime(runtime, { model: modelOverride, engineConfig });
   const runtimeFeatureOpts = _resolveRuntimeFeatureOpts({
@@ -531,6 +611,9 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
   } = opts;
 
+  const unavailable = _runtimeUnavailableResult({ cli: cliOverride, engineConfig });
+  if (unavailable) return _resolvedCallResult(unavailable);
+
   const runtime = _resolveRuntimeFor({ cli: cliOverride, engineConfig });
   const model = _resolveModelForRuntime(runtime, { model: modelOverride, engineConfig });
   const runtimeFeatureOpts = _resolveRuntimeFeatureOpts({

package/engine/pipeline.js

@@ -488,7 +488,9 @@ async function executePlanStage(stage, stageState, run, config) {
       timeout: 120000, label: 'pipeline-plan', model: 'sonnet', maxTurns: 1,
       engineConfig: config.engine,
     });
-    if (result.text) {
+    if (result.missingRuntime) {
+      log('warn', `Pipeline plan LLM skipped: ${result.text || result.stderr || 'runtime unavailable'} — falling back to raw meeting context`);
+    } else if (result.text) {
       content = result.text;
       log('info', `Pipeline plan: LLM generated ${content.length} chars from meeting context`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1698",
+  "version": "0.1.1699",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"