serpentstack 0.2.14 → 0.2.16

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 ────────────────────────────────────────────────
 
@@ -33,6 +33,19 @@ function which(cmd) {
   });
 }
 
+function execPromise(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 15000 }, (err, stdout, stderr) => {
+      if (err) {
+        const msg = stderr?.trim() || stdout?.trim() || err.message;
+        reject(new Error(msg));
+      } else {
+        resolve(stdout);
+      }
+    });
+  });
+}
+
 async function ask(rl, label, defaultValue) {
   const hint = defaultValue ? ` ${dim(`[${defaultValue}]`)}` : '';
   const answer = await rl.question(`  ${green('?')} ${bold(label)}${hint}: `);
@@ -244,13 +257,13 @@ async function pickModel(rl, agentName, currentModel, available) {
     }
   }
 
-  // Section 2: Recommended models (not installed, auto-download on select)
-  if (available.ollamaInstalled && available.recommended.length > 0) {
+  // Section 2: Downloadable models — always shown if we have recommendations
+  if (available.recommended.length > 0) {
     const liveTag = available.recommendedLive
-      ? dim(`fetched from ollama.com`)
+      ? dim(`live from ollama.com`)
       : dim(`cached list`);
-    console.log(`    ${dim('── Download')} ${cyan('free')} ${dim('(')}${liveTag}${dim(') ──')}`);
-    // Show a reasonable subset (not 50 models)
+    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;
@@ -316,9 +329,33 @@ async function pickModel(rl, agentName, currentModel, available) {
 
   const selected = (idx >= 0 && idx < choices.length) ? choices[idx] : choices[Math.max(0, currentIdx)];
 
-  // If they selected a downloadable model, pull it now
+  // If they selected a downloadable model, handle Ollama install + pull
   if (selected.action === 'download') {
-    // Close rl temporarily so ollama pull can use the terminal
+    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();
@@ -401,7 +438,7 @@ end tell`;
 
 // ─── Stop Flow ──────────────────────────────────────────────
 
-function stopAllAgents(projectDir) {
+async function stopAllAgents(projectDir) {
   cleanStalePids(projectDir);
   const running = listPids(projectDir);
 
@@ -413,19 +450,31 @@ function stopAllAgents(projectDir) {
 
   let stopped = 0;
   for (const { name, pid } of running) {
+    // Remove cron jobs for this agent
     try {
-      process.kill(pid, 'SIGTERM');
-      removePid(projectDir, name);
-      cleanWorkspace(projectDir, name);
-      success(`Stopped ${bold(name)} ${dim(`(PID ${pid})`)}`);
-      stopped++;
-    } catch (err) {
-      if (err.code === 'ESRCH') {
-        removePid(projectDir, name);
-      } else {
-        error(`Failed to stop ${bold(name)}: ${err.message}`);
-      }
+      await execPromise('openclaw', ['cron', 'list', '--json']).then(out => {
+        const jobs = JSON.parse(out);
+        const agentJobs = (Array.isArray(jobs) ? jobs : jobs.jobs || [])
+          .filter(j => j.agent === name || (j.name && j.name.startsWith(`${name}-`)));
+        return Promise.all(agentJobs.map(j =>
+          execPromise('openclaw', ['cron', 'rm', j.id || j.name]).catch(() => {})
+        ));
+      });
+    } catch { /* cron cleanup is best-effort */ }
+
+    // Remove agent from OpenClaw
+    try {
+      await execPromise('openclaw', ['agents', 'delete', name, '--force']);
+    } catch { /* best-effort */ }
+
+    // Clean up PID and workspace
+    if (pid > 0) {
+      try { process.kill(pid, 'SIGTERM'); } catch { /* already dead */ }
     }
+    removePid(projectDir, name);
+    cleanWorkspace(projectDir, name);
+    success(`Stopped ${bold(name)}`);
+    stopped++;
   }
 
   if (stopped > 0) {
@@ -601,9 +650,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 });
@@ -615,8 +680,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);
 
@@ -697,8 +777,9 @@ async function runStart(projectDir, parsed, config, soulPath, hasOpenClaw) {
   console.log();
 
   const sharedSoul = readFileSync(soulPath, 'utf8');
-  let started = 0;
+  let registered = 0;
 
+  // Step 1: Generate workspaces and register agents with OpenClaw
   for (const { name, agentMd } of toStart) {
     try {
       const effectiveModel = getEffectiveModel(name, agentMd.meta, config);
@@ -709,38 +790,110 @@ async function runStart(projectDir, parsed, config, soulPath, hasOpenClaw) {
 
       const workspacePath = generateWorkspace(projectDir, name, overriddenMd, sharedSoul);
       const absWorkspace = resolve(workspacePath);
-      const absProject = resolve(projectDir);
 
-      const openclawCmd = `OPENCLAW_STATE_DIR='${join(absWorkspace, '.state')}' openclaw start --workspace '${absWorkspace}'`;
-      const method = openInTerminal(`SerpentStack: ${name}`, openclawCmd, absProject);
+      // Register agent with OpenClaw (idempotent — will update if exists)
+      try {
+        await execPromise('openclaw', [
+          'agents', 'add', name,
+          '--workspace', absWorkspace,
+          '--model', effectiveModel,
+          '--non-interactive',
+        ]);
+        success(`${green('✓')} Registered ${bold(name)} ${dim(`(${modelShortName(effectiveModel)})`)}`);
+      } catch (err) {
+        // Agent may already exist — that's fine
+        if (err.message && err.message.includes('already exists')) {
+          info(`${bold(name)} already registered with OpenClaw`);
+        } else {
+          warn(`Could not register ${bold(name)}: ${err.message || 'unknown error'}`);
+        }
+      }
 
-      if (method) {
-        writePid(projectDir, name, -1);
-        success(`${bold(name)} opened in ${method} ${dim(`(${modelShortName(effectiveModel)})`)}`);
-        started++;
-      } else {
-        warn(`No terminal detected — starting ${bold(name)} in background`);
-        const child = spawn('openclaw', ['start', '--workspace', absWorkspace], {
-          stdio: 'ignore',
-          detached: true,
-          cwd: absProject,
-          env: { ...process.env, OPENCLAW_STATE_DIR: join(absWorkspace, '.state') },
-        });
-        child.unref();
-        writePid(projectDir, name, child.pid);
-        success(`${bold(name)} started ${dim(`PID ${child.pid}`)}`);
-        started++;
+      // Add cron jobs for the agent's schedule
+      const schedules = agentMd.meta.schedule || [];
+      for (const sched of schedules) {
+        try {
+          await execPromise('openclaw', [
+            'cron', 'add',
+            '--agent', name,
+            '--every', sched.every,
+            '--message', `Run task: ${sched.task}`,
+            '--name', `${name}-${sched.task}`,
+            '--light-context',
+          ]);
+        } catch {
+          // Cron job may already exist — non-fatal
+        }
       }
+
+      writePid(projectDir, name, -1); // marker
+      registered++;
     } catch (err) {
       error(`${bold(name)}: ${err.message}`);
     }
   }
 
-  console.log();
-  if (started > 0) {
-    success(`${started} agent(s) launched — fangs out 🐍`);
+  if (registered === 0) {
+    console.log();
+    error('No agents were registered.');
     console.log();
+    return;
   }
+
+  console.log();
+
+  // Step 2: Check if gateway is running, start it if not
+  let gatewayRunning = false;
+  try {
+    const healthResp = await fetch('http://127.0.0.1:18789/health');
+    gatewayRunning = healthResp.ok;
+  } catch {
+    // not running
+  }
+
+  if (!gatewayRunning) {
+    info('Starting OpenClaw gateway...');
+
+    const method = openInTerminal(
+      'OpenClaw Gateway',
+      'openclaw gateway',
+      resolve(projectDir),
+    );
+
+    if (method) {
+      success(`Gateway opened in ${method}`);
+    } else {
+      // Fallback: start in background
+      const child = spawn('openclaw', ['gateway'], {
+        stdio: 'ignore',
+        detached: true,
+        cwd: resolve(projectDir),
+      });
+      child.unref();
+      success(`Gateway started in background ${dim(`(PID ${child.pid})`)}`);
+    }
+
+    // Give gateway a moment to start
+    console.log(`  ${dim('Waiting for gateway...')}`);
+    await new Promise(r => setTimeout(r, 3000));
+  } else {
+    success('Gateway is already running');
+  }
+
+  console.log();
+  success(`${registered} agent(s) registered — fangs out 🐍`);
+  console.log();
+
+  printBox('Your agents are running', [
+    `${dim('The OpenClaw gateway manages your agents on their schedules.')}`,
+    `${dim('View agent activity with:')}`,
+    '',
+    `${dim('$')} ${bold('openclaw tui')}                     ${dim('# interactive terminal UI')}`,
+    `${dim('$')} ${bold('openclaw cron list')}                ${dim('# see scheduled tasks')}`,
+    `${dim('$')} ${bold('openclaw agents list')}              ${dim('# see registered agents')}`,
+    `${dim('$')} ${bold('serpentstack persistent --stop')}    ${dim('# stop all agents')}`,
+  ]);
+  console.log();
 }
 
 // ─── Main Entry Point ───────────────────────────────────────
@@ -753,7 +906,7 @@ export async function persistent({ stop = false, configure = false, agents = fal
   // ── Stop (doesn't need full preflight) ──
   if (stop) {
     cleanStalePids(projectDir);
-    stopAllAgents(projectDir);
+    await stopAllAgents(projectDir);
     return;
   }
 

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.
@@ -273,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/lib/utils/ui.js

@@ -94,7 +94,7 @@ export function printHeader() {
 
 export function divider(label) {
   if (label) {
-    console.log(`  ${DIM}── ${RESET}${BOLD}${label}${RESET} ${DIM}${'─'.repeat(Math.max(0, 50 - stripAnsi(label).length))}${RESET}`);
+    console.log(`  ${DIM}──${RESET} ${GREEN}${BOLD}${label}${RESET} ${DIM}${'─'.repeat(Math.max(0, 50 - stripAnsi(label).length))}${RESET}`);
   } else {
     console.log(`  ${DIM}${'─'.repeat(54)}${RESET}`);
   }

package/package.json

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