serpentstack 0.2.13 → 0.2.15

package/lib/commands/persistent.js

@@ -23,7 +23,7 @@ import {
   getEffectiveModel,
   isAgentEnabled,
 } from '../utils/config.js';
-import { detectModels, modelShortName } from '../utils/models.js';
+import { detectModels, modelShortName, detectSystemCapabilities } from '../utils/models.js';
 
 // ─── Helpers ────────────────────────────────────────────────
 
@@ -174,18 +174,65 @@ function printPreflightStatus(hasOpenClaw, available) {
   return hasOpenClaw;
 }
 
+// ─── Model Install ──────────────────────────────────────────
+
+/**
+ * Run `ollama pull <model>` with live progress output.
+ * Returns true if the pull succeeded.
+ */
+function ollamaPull(modelName) {
+  return new Promise((resolve) => {
+    console.log();
+    info(`Downloading ${bold(modelName)}... ${dim('(this may take a few minutes)')}`);
+    console.log();
+
+    const child = spawn('ollama', ['pull', modelName], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    // Stream progress to the terminal
+    child.stdout.on('data', (data) => {
+      const line = data.toString().trim();
+      if (line) process.stderr.write(`    ${line}\r`);
+    });
+    child.stderr.on('data', (data) => {
+      const line = data.toString().trim();
+      if (line) process.stderr.write(`    ${line}\r`);
+    });
+
+    child.on('close', (code) => {
+      process.stderr.write('\x1b[K'); // clear the progress line
+      if (code === 0) {
+        success(`${bold(modelName)} installed`);
+        console.log();
+        resolve(true);
+      } else {
+        error(`Failed to download ${bold(modelName)} (exit code ${code})`);
+        console.log();
+        resolve(false);
+      }
+    });
+
+    child.on('error', (err) => {
+      error(`Could not run ollama pull: ${err.message}`);
+      console.log();
+      resolve(false);
+    });
+  });
+}
+
 // ─── Model Picker ───────────────────────────────────────────
 
 async function pickModel(rl, agentName, currentModel, available) {
   const choices = [];
 
-  // Local models first
+  // Section 1: Installed local models
   if (available.local.length > 0) {
-    console.log(`    ${dim('── Local')} ${green('free')} ${dim('──────────────────────')}`);
+    console.log(`    ${dim('── Installed')} ${green('ready')} ${dim('────────────────────')}`);
     for (const m of available.local) {
       const isCurrent = m.id === currentModel;
       const idx = choices.length;
-      choices.push(m);
+      choices.push({ ...m, action: 'use' });
       const marker = isCurrent ? green('>') : ' ';
       const num = dim(`${idx + 1}.`);
       const label = isCurrent ? bold(m.name) : m.name;
@@ -197,14 +244,48 @@ async function pickModel(rl, agentName, currentModel, available) {
     }
   }
 
-  // Cloud models
+  // Section 2: Downloadable models — always shown if we have recommendations
+  if (available.recommended.length > 0) {
+    const liveTag = available.recommendedLive
+      ? dim(`live from ollama.com`)
+      : dim(`cached list`);
+    const needsOllama = !available.ollamaInstalled ? dim(' · requires Ollama') : '';
+    console.log(`    ${dim('── Download')} ${cyan('free')} ${dim('(')}${liveTag}${needsOllama}${dim(') ──')}`);
+    const toShow = available.recommended.slice(0, 8);
+    for (const r of toShow) {
+      const idx = choices.length;
+      const isCurrent = `ollama/${r.name}` === currentModel;
+      choices.push({
+        id: `ollama/${r.name}`,
+        name: r.name,
+        params: r.params,
+        size: r.size,
+        description: r.description,
+        tier: 'downloadable',
+        action: 'download',
+      });
+      const marker = isCurrent ? green('>') : ' ';
+      const num = dim(`${idx + 1}.`);
+      const label = isCurrent ? bold(r.name) : r.name;
+      const params = r.params ? dim(` ${r.params}`) : '';
+      const size = r.size ? dim(` (${r.size})`) : '';
+      const desc = r.description ? dim(` — ${r.description}`) : '';
+      const tag = isCurrent ? green(' ← current') : '';
+      console.log(`  ${marker} ${num} ${label}${params}${size}${desc}${tag}`);
+    }
+    if (available.recommended.length > toShow.length) {
+      console.log(`    ${dim(`... and ${available.recommended.length - toShow.length} more at`)} ${cyan('ollama.com/library')}`);
+    }
+  }
+
+  // Section 3: Cloud models
   if (available.cloud.length > 0) {
     const apiNote = available.hasApiKey ? green('key ✓') : yellow('needs API key');
     console.log(`    ${dim('── Cloud')} ${apiNote} ${dim('─────────────────────')}`);
     for (const m of available.cloud) {
       const isCurrent = m.id === currentModel;
       const idx = choices.length;
-      choices.push(m);
+      choices.push({ ...m, action: 'use' });
       const marker = isCurrent ? green('>') : ' ';
       const num = dim(`${idx + 1}.`);
       const label = isCurrent ? bold(m.name) : m.name;
@@ -216,13 +297,14 @@ async function pickModel(rl, agentName, currentModel, available) {
 
   if (choices.length === 0) {
     warn('No models available. Install Ollama and pull a model first.');
+    console.log(`    ${dim('$')} ${bold('curl -fsSL https://ollama.com/install.sh | sh')}`);
     console.log(`    ${dim('$')} ${bold('ollama pull llama3.2')}`);
     return currentModel;
   }
 
-  // If current model isn't in either list, add it
+  // If current model isn't in any list, add it at the top
   if (!choices.some(c => c.id === currentModel)) {
-    choices.unshift({ id: currentModel, name: modelShortName(currentModel), tier: 'custom' });
+    choices.unshift({ id: currentModel, name: modelShortName(currentModel), tier: 'custom', action: 'use' });
     console.log(`    ${dim(`Current: ${modelShortName(currentModel)} (not in detected models)`)}`);
   }
 
@@ -234,7 +316,45 @@ async function pickModel(rl, agentName, currentModel, available) {
 
   const selected = (idx >= 0 && idx < choices.length) ? choices[idx] : choices[Math.max(0, currentIdx)];
 
-  if (selected.tier === 'cloud' && available.local.length > 0) {
+  // If they selected a downloadable model, handle Ollama install + pull
+  if (selected.action === 'download') {
+    if (!available.ollamaInstalled) {
+      console.log();
+      warn('Ollama is required to run local models.');
+      console.log();
+      console.log(`  ${dim('Install Ollama (free, open-source):')}`);
+      console.log(`    ${dim('$')} ${bold('curl -fsSL https://ollama.com/install.sh | sh')}`);
+      console.log(`    ${dim('$')} ${bold('ollama serve')}`);
+      console.log();
+      info(`After installing, re-run ${bold('serpentstack persistent --agents')} to download and select ${bold(selected.name)}.`);
+      console.log();
+
+      // Save the selection anyway so it's remembered
+      return selected.id;
+    }
+
+    if (!available.ollamaRunning) {
+      console.log();
+      warn('Ollama is installed but not running.');
+      console.log(`    ${dim('$')} ${bold('ollama serve')}`);
+      console.log();
+      info(`Start Ollama, then re-run ${bold('serpentstack persistent --agents')} to download ${bold(selected.name)}.`);
+      console.log();
+      return selected.id;
+    }
+
+    rl.pause();
+    const pulled = await ollamaPull(selected.name);
+    rl.resume();
+
+    if (!pulled) {
+      warn(`Download failed. Keeping previous model: ${bold(modelShortName(currentModel))}`);
+      return currentModel;
+    }
+  }
+
+  // Warn about cloud model costs
+  if (selected.tier === 'cloud' && (available.local.length > 0 || available.recommended.length > 0)) {
     warn(`Cloud models cost tokens per heartbeat. Consider a local model for persistent agents.`);
   }
   if (selected.tier === 'cloud' && !available.hasApiKey) {
@@ -505,9 +625,25 @@ async function runConfigure(projectDir, config, soulPath) {
 
 // ─── Agents Flow ────────────────────────────────────────────
 
+// Agent description summaries for the enable/disable flow
+const AGENT_SUMMARIES = {
+  'log-watcher': 'Monitors your dev server health and log output every 30–60s. Catches backend crashes, frontend build errors, and import failures — reports them with file paths and suggested fixes.',
+  'test-runner': 'Runs your test suite every 5 min and lint/typecheck every 15 min. Catches regressions before you commit — shows which test failed, what changed, and whether the test or source needs fixing.',
+  'skill-maintainer': 'Checks every hour whether your .skills/ files still match the actual codebase. When code patterns drift from what skills describe, it proposes exact updates so IDE agents stay accurate.',
+};
+
 async function runAgents(projectDir, config, parsed, available) {
+  // Show system capabilities so users know what models they can run
+  const sys = detectSystemCapabilities();
+
+  divider('Your System');
+  console.log(`    ${dim('RAM:')} ${bold(sys.totalGB + ' GB')} total, ${sys.freeGB} GB free`);
+  console.log(`    ${dim(sys.recommendation)}`);
+  console.log();
+
   divider('Agents');
-  console.log(`  ${dim('Enable/disable each agent and pick a model.')}`);
+  console.log(`  ${dim('Each agent runs in its own terminal on a schedule.')}`);
+  console.log(`  ${dim('Enable the ones you want, then pick a model for each.')}`);
   console.log();
 
   const rl = createInterface({ input: stdin, output: stdout });
@@ -519,8 +655,23 @@ async function runAgents(projectDir, config, parsed, available) {
       const currentModel = existingAgent?.model || 'ollama/llama3.2';
       const schedule = (agentMd.meta.schedule || []).map(s => s.every).join(', ');
 
-      console.log(`  ${bold(name)}  ${dim(agentMd.meta.description || '')}`);
-      console.log(`    ${dim(`Schedule: ${schedule || 'none'}`)}`);
+      // Show rich description
+      console.log(`  ${bold(name)}  ${dim(`(${schedule || 'manual'})`)}`);
+      const summary = AGENT_SUMMARIES[name] || agentMd.meta.description || '';
+      if (summary) {
+        // Word-wrap summary to ~70 chars, indented
+        const words = summary.split(' ');
+        let line = '';
+        for (const word of words) {
+          if (line.length + word.length + 1 > 68) {
+            console.log(`    ${dim(line)}`);
+            line = word;
+          } else {
+            line = line ? `${line} ${word}` : word;
+          }
+        }
+        if (line) console.log(`    ${dim(line)}`);
+      }
 
       const enabled = await askYesNo(rl, `Enable ${bold(name)}?`, currentEnabled);
 

package/lib/utils/models.js

@@ -1,4 +1,5 @@
 import { execFile } from 'node:child_process';
+import { freemem, totalmem } from 'node:os';
 
 // ─── Fallback Recommendations ───────────────────────────────
 // Used only when the Ollama library API is unreachable.
@@ -183,16 +184,20 @@ async function detectOpenClawAuth() {
 
   try {
     const status = await execAsync('openclaw', ['models', 'status']);
-    if (status.includes('api_key') || status.includes('configured')) {
+    // Check for API key in status output (e.g. "api_key=1" or "Configured models")
+    if (status.includes('api_key=') || status.includes('Configured models')) {
       result.hasApiKey = true;
     }
 
-    const list = await execAsync('openclaw', ['models', 'list', '--json']);
+    // Try JSON output first, fall back to text parsing
     try {
-      const models = JSON.parse(list);
-      if (Array.isArray(models)) {
-        result.models = models
-          .filter(m => m.available && !m.local)
+      const list = await execAsync('openclaw', ['models', 'list', '--json']);
+      const parsed = JSON.parse(list);
+      // Handle both { models: [...] } and bare array
+      const modelsArr = Array.isArray(parsed) ? parsed : (parsed.models || []);
+      if (modelsArr.length > 0) {
+        result.models = modelsArr
+          .filter(m => !m.local) // only cloud models
           .map(m => ({
             id: m.key || m.name,
             name: modelShortName(m.key || m.name),
@@ -201,13 +206,16 @@ async function detectOpenClawAuth() {
           }));
       }
     } catch {
-      const text = await execAsync('openclaw', ['models', 'list']);
-      const lines = text.trim().split('\n').filter(l => l.trim() && !l.startsWith('Model'));
-      result.models = lines.map(l => {
-        const id = l.trim().split(/\s+/)[0];
-        if (!id || id.length < 3) return null;
-        return { id, name: modelShortName(id), provider: id.split('/')[0], tier: 'cloud' };
-      }).filter(Boolean);
+      // Fall back to text output parsing
+      try {
+        const text = await execAsync('openclaw', ['models', 'list']);
+        const lines = text.trim().split('\n').filter(l => l.trim() && !l.startsWith('Model'));
+        result.models = lines.map(l => {
+          const id = l.trim().split(/\s+/)[0];
+          if (!id || id.length < 3) return null;
+          return { id, name: modelShortName(id), provider: id.split('/')[0], tier: 'cloud' };
+        }).filter(Boolean);
+      } catch { /* use fallback below */ }
     }
   } catch {
     result.models = [
@@ -266,6 +274,38 @@ export function modelShortName(model) {
   return model;
 }
 
+/**
+ * Detect system capabilities for model recommendations.
+ * Returns { totalRAM, freeRAM, maxModelSize, recommendation }.
+ */
+export function detectSystemCapabilities() {
+  const total = totalmem();
+  const free = freemem();
+  const totalGB = total / (1024 ** 3);
+  const freeGB = free / (1024 ** 3);
+
+  // Ollama needs ~2GB overhead; model needs to fit in remaining RAM
+  const availableForModel = Math.max(0, freeGB - 2);
+
+  let recommendation;
+  if (totalGB >= 32) {
+    recommendation = 'Your system can handle large models (up to 24B parameters)';
+  } else if (totalGB >= 16) {
+    recommendation = 'Good for medium models (up to 8B parameters)';
+  } else if (totalGB >= 8) {
+    recommendation = 'Best with small models (3B–4B parameters)';
+  } else {
+    recommendation = 'Limited RAM — use cloud models or very small local models';
+  }
+
+  return {
+    totalGB: totalGB.toFixed(0),
+    freeGB: freeGB.toFixed(1),
+    availableGB: availableForModel.toFixed(1),
+    recommendation,
+  };
+}
+
 function execAsync(cmd, args) {
   return new Promise((resolve, reject) => {
     execFile(cmd, args, { timeout: 5000 }, (err, stdout) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serpentstack",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "CLI for SerpentStack — AI-driven development standards with project-specific skills and persistent agents",
   "type": "module",
   "bin": {