wolverine-ai 1.0.0 → 1.1.0

package/PLATFORM.md

@@ -103,6 +103,14 @@ Content-Type: application/json
       "chat": { "tokens": 25000, "cost": 0.05, "calls": 60 },
       "classify": { "tokens": 3000, "cost": 0.001, "calls": 15 },
       "develop": { "tokens": 5000, "cost": 0.03, "calls": 5 }
+    },
+    "byModel": {
+      "gpt-5.4-mini": { "tokens": 30000, "cost": 0.06, "calls": 40 },
+      "gpt-4o-mini": { "tokens": 15000, "cost": 0.02, "calls": 45 }
+    },
+    "byTool": {
+      "call_endpoint": { "tokens": 5000, "cost": 0.01, "calls": 20 },
+      "search_brain": { "tokens": 2000, "cost": 0.005, "calls": 10 }
     }
   },
 

package/README.md

@@ -11,12 +11,21 @@ Built on patterns from [claw-code](https://github.com/instructkr/claw-code) —
 ## Quick Start
 
 ```bash
+# Install from npm
+npm i wolverine-ai
+
+# Or clone from GitHub
 git clone https://github.com/bobbyswhip/Wolverine.git
 cd Wolverine
 npm install
+
+# Configure
 cp .env.example .env.local
 # Edit .env.local — add your OPENAI_API_KEY and generate an ADMIN_KEY
+
+# Run
 npm start
+# or: npx wolverine server/index.js
 ```
 
 Dashboard opens at `http://localhost:PORT+1`. Server runs on `PORT`.
@@ -359,7 +368,8 @@ Startup:
 - Auto-registers on first run, retries every 60s until platform responds
 - Saves key to `.wolverine/platform-key` (survives restarts)
 - Sends one ~2KB JSON POST every 60 seconds (5s timeout, non-blocking)
-- Payload matches [PLATFORM.md](PLATFORM.md) spec: `instanceId`, `server`, `process`, `routes`, `repairs`, `usage`, `brain`, `backups`
+- Payload matches [PLATFORM.md](PLATFORM.md) spec: `instanceId`, `server`, `process`, `routes`, `repairs`, `usage` (tokens/cost/calls + `byCategory` + `byModel` + `byTool`), `brain`, `backups`
+- Platform analytics aggregates across all servers: total tokens/cost, breakdown by category (heal/chat/develop/security/classify/research/brain), by model, by tool
 - Secrets redacted before sending
 - Offline-resilient: queues up to 1440 heartbeats locally, drains on reconnect
 

package/SERVER_BEST_PRACTICES.md

@@ -19,13 +19,21 @@ server/
 
 ## Rules
 
+### Ports
+- **Development**: use port 3000 (standard, no admin required, firewall-friendly)
+- **Production**: use port 443 (HTTPS) or 80 (HTTP) behind a reverse proxy (nginx/caddy)
+- **Never** use random high ports in production — they bypass firewalls and confuse load balancers
+- **Always** use HTTPS in production — terminate TLS at the reverse proxy, not in Node
+- Dashboard runs on port+1 automatically (3001 in dev, not exposed in prod)
+
 ### Security
 - Never expose secrets in responses — use env vars, never hardcode
-- Validate ALL input — use express.json() with size limits
-- Use helmet() for HTTP security headers in production
+- Validate ALL input — Fastify has built-in JSON schema validation
+- Use HTTPS in production — reverse proxy (nginx/caddy) handles TLS
 - Rate limit public endpoints
-- Sanitize user input before database queries
+- Sanitize user input before database queries — use the SQL skill
 - Never return stack traces in production error responses
+- Use the sqlGuard() middleware on all routes that accept user input
 
 ### Scalability
 - Keep routes thin — business logic goes in services/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Self-healing Node.js server framework powered by AI. Catches crashes, diagnoses errors, generates fixes, verifies, and restarts — automatically.",
   "main": "src/index.js",
   "bin": {

package/server/config/settings.json

@@ -18,7 +18,7 @@
   },
 
   "server": {
-    "port": 6969,
+    "port": 3000,
     "maxRetries": 3,
     "maxMemoryMB": 512
   },

package/src/brain/brain.js

@@ -139,6 +139,58 @@ const SEED_DOCS = [
     text: "Telemetry architecture: 4 files, ~250 lines total. heartbeat.js sends one HTTP POST every 60s (5s timeout, non-blocking). register.js auto-registers and caches key in memory + disk. queue.js appends to JSONL file only on failure, trims lazily. telemetry.js collects from subsystems using optional chaining (no crashes if subsystem missing). All secrets redacted before sending. Response bodies drained immediately (res.resume). No blocking, no delays, no busy waits.",
     metadata: { topic: "telemetry-architecture" },
   },
+  {
+    text: "Server uses Fastify (migrated from Express). 5.6x faster routing: ~114k req/s vs Express ~20k req/s. Routes are async plugin functions: async function routes(fastify) { fastify.get('/', async () => ({...})); } module.exports = routes. Registered in index.js with fastify.register(require('./routes/X'), {prefix:'/X'}). JSON parsing is built-in, no middleware needed.",
+    metadata: { topic: "fastify" },
+  },
+  {
+    text: "npm package: wolverine-ai on npmjs.com. Install: npm i wolverine-ai. CLI: npx wolverine server/index.js. v1.0.0, 79 files, 125KB compressed. Includes src/, bin/, server/, examples/. GitHub: https://github.com/bobbyswhip/Wolverine",
+    metadata: { topic: "npm-package" },
+  },
+  {
+    text: "Dashboard has 9 panels: Overview (stats cards + recent events), Events (live SSE stream), Performance (endpoint metrics), Analytics (memory/CPU charts, route health, response times), Command (admin chat with 3-route classifier), Backups (server/ snapshots with status badges), Brain (vector store stats + function map), Repairs (error/resolution audit trail with tokens and cost), Tools (agent tool harness listing), Usage (token analytics by model/category/tool with USD costs).",
+    metadata: { topic: "dashboard-panels" },
+  },
+  {
+    text: "Command interface routing: AI classifier (CLASSIFIER_MODEL) returns SIMPLE/TOOLS/AGENT. SIMPLE = brain knowledge only (CHAT_MODEL, no tools). TOOLS = live data with function calling (TOOL_MODEL, call_endpoint/read_file/search_brain). AGENT SMALL = smart edit (CODING_MODEL, 1 AI call, structured JSON file operations). AGENT MEDIUM = single agent (REASONING_MODEL, 8 turns). AGENT LARGE = sub-agents (explore→plan→fix).",
+    metadata: { topic: "command-routing" },
+  },
+  {
+    text: "Smart edit: for SMALL tier tasks, one AI call returns JSON with file operations: [{action:'create',path:'server/routes/X.js',content:'...'},{action:'edit',path:'server/index.js',find:'...',replace:'...'}]. Creates backup before changes, restarts server after, tests endpoint, rescans brain with new routes. Skills auto-injected into prompt when relevant.",
+    metadata: { topic: "smart-edit" },
+  },
+  {
+    text: "Token tracking: every AI call tracked with input/output tokens + USD cost. Categories: heal, develop, chat, security, classify, research, brain. Tracked by model, by category, by tool. Persisted to .wolverine/usage.json (aggregates) and .wolverine/usage-history.jsonl (full timeline). Auto-saves on every call. Dashboard shows charts + cost breakdowns. Pricing from src/logger/pricing.js, customizable via .wolverine/pricing.json.",
+    metadata: { topic: "token-tracking" },
+  },
+  {
+    text: "Repair history: dedicated audit trail at .wolverine/repair-history.json. Each entry: error, file, line, resolution, success, mode (fast/agent/sub-agents), model, tokens, cost, iteration, duration, filesModified. Dashboard Repairs panel shows stats (total, success rate, total cost, avg tokens) + scrollable history with per-repair details.",
+    metadata: { topic: "repair-history" },
+  },
+  {
+    text: "Skill registry: auto-discovers skills from src/skills/ on startup. Each skill exports SKILL_NAME, SKILL_DESCRIPTION, SKILL_KEYWORDS, SKILL_USAGE. Registry matches skills to commands using token scoring (claw-code pattern). Matched skills get injected into agent prompts before AI calls. SQL skill auto-injects when building database features.",
+    metadata: { topic: "skill-registry" },
+  },
+  {
+    text: "Notifications: detects human-required errors (expired keys, billing, service down, certs, permissions, disk). Classifies errors as AI-fixable vs human-required using pattern matching. Generates AI summary (CHAT_MODEL). Fires before wasting tokens on repair. Console alert + dashboard event + optional webhook. Categories: auth, billing, service, cert, permission, disk.",
+    metadata: { topic: "notifications" },
+  },
+  {
+    text: "MCP integration: connect external tools via Model Context Protocol. Configure in .wolverine/mcp.json with per-server tool allowlists. Security: arg sanitization (secrets redacted before sending to MCP servers), result injection scanning, rate limiting per server, audit logging. Tools appear as mcp__server__tool in the agent. Supports stdio and HTTP transports.",
+    metadata: { topic: "mcp" },
+  },
+  {
+    text: "Demos: 7 demo servers in examples/demos/. Demo runner (examples/run-demo.js) copies demo into server/, runs wolverine, restores on exit. npm run demo:list shows all demos. Each demo is a proper Fastify server with routes/ that mirrors the real server/ structure. Tests: basic typo, multi-file, syntax error, secret leak, expired key, JSON config, null crash.",
+    metadata: { topic: "demos" },
+  },
+  {
+    text: "10 configurable models: REASONING_MODEL (multi-file agent), CODING_MODEL (code repair, Responses API for codex), CHAT_MODEL (simple text), TOOL_MODEL (function calling), CLASSIFIER_MODEL (routing), AUDIT_MODEL (injection detection), COMPACTING_MODEL (brain text compression), RESEARCH_MODEL (deep research), TEXT_EMBEDDING_MODEL (vectors). All in server/config/settings.json. Reasoning models auto-get 4x token limits for chain-of-thought.",
+    metadata: { topic: "model-slots" },
+  },
+  {
+    text: "Port best practices: development uses port 3000 (standard, no admin, firewall-friendly). Production uses 443 (HTTPS) or 80 (HTTP) behind a reverse proxy (nginx/caddy). Never use random high ports in production — they bypass firewalls and confuse load balancers. Always use HTTPS in production — terminate TLS at the proxy, not in Node. Dashboard auto-runs on port+1. Wolverine warns on startup if the port is non-standard.",
+    metadata: { topic: "port-security" },
+  },
 ];
 
 class Brain {

package/src/core/runner.js

@@ -140,6 +140,20 @@ class WolverineRunner {
       maxRetries: this.maxRetries,
     });
 
+    // Port safety check
+    const port = parseInt(process.env.PORT, 10) || 3000;
+    const safeDevPorts = [3000, 3001, 8080, 8443];
+    const safeProdPorts = [80, 443, 8080, 8443];
+    const env = process.env.NODE_ENV || "development";
+
+    if (env === "production" && port !== 443 && port !== 80 && port !== 8443 && port !== 8080) {
+      console.log(chalk.yellow(`  ⚠️  Port ${port} in production — recommend 443 (HTTPS) or 80 (HTTP) behind a reverse proxy`));
+    } else if (env !== "production" && !safeDevPorts.includes(port) && port < 1024) {
+      console.log(chalk.yellow(`  ⚠️  Port ${port} requires root/admin — use 3000 for local development`));
+    } else if (port > 9999) {
+      console.log(chalk.yellow(`  ⚠️  Port ${port} is non-standard — use 3000 (dev) or 443 (prod) for best compatibility`));
+    }
+
     // Initialize brain (scan project, seed docs, embed function map)
     try {
       await this.brain.init();

package/src/dashboard/server.js

@@ -1029,6 +1029,7 @@ main{overflow-y:auto;padding:24px}
   <a data-panel="events">📋 Events</a>
   <a data-panel="perf">⚡ Performance</a>
   <a data-panel="analytics">📊 Analytics</a>
+  <a data-panel="processes">⚙️ Processes</a>
   <div class="sep"></div>
   <div class="label">Agent</div>
   <a data-panel="command">💬 Command</a>
@@ -1059,6 +1060,32 @@ main{overflow-y:auto;padding:24px}
 </div>
 <div class="panel" id="p-events"><div class="card"><h3>Live Event Stream</h3><div class="ev-list" id="ev-all"></div></div></div>
 <div class="panel" id="p-perf"><div class="card"><h3>Endpoint Metrics</h3><div id="perf-list"><div class="empty">No traffic yet</div></div></div></div>
+<div class="panel" id="p-processes">
+  <div class="stats" style="grid-template-columns:repeat(4,1fr)">
+    <div class="stat-card heal"><div class="stat-val" id="proc-pid">-</div><div class="stat-lbl">Server PID</div></div>
+    <div class="stat-card up"><div class="stat-val" id="proc-up">-</div><div class="stat-lbl">Uptime</div></div>
+    <div class="stat-card err"><div class="stat-val" id="proc-mem">-</div><div class="stat-lbl">Memory (RSS)</div></div>
+    <div class="stat-card brain"><div class="stat-val" id="proc-cpu">-</div><div class="stat-lbl">CPU %</div></div>
+  </div>
+  <div class="row2">
+    <div class="card">
+      <h3>System</h3>
+      <div id="proc-sys"><div class="empty">Loading...</div></div>
+    </div>
+    <div class="card">
+      <h3>Process Health</h3>
+      <div id="proc-health"><div class="empty">Loading...</div></div>
+    </div>
+  </div>
+  <div class="card">
+    <h3>Memory Timeline</h3>
+    <div id="proc-mem-chart" style="height:160px"></div>
+  </div>
+  <div class="card">
+    <h3>Active Connections & Listeners</h3>
+    <div id="proc-listen"><div class="empty">Loading...</div></div>
+  </div>
+</div>
 <div class="panel" id="p-analytics">
   <div class="stats" style="grid-template-columns:repeat(4,1fr)">
     <div class="stat-card heal"><div class="stat-val" id="a-mem">-</div><div class="stat-lbl">Memory (RSS)</div></div>
@@ -1280,6 +1307,59 @@ async function refresh(){
         return '<div class="mrow" style="flex-wrap:wrap"><div style="flex:1"><span style="margin-right:6px">'+icon+'</span><span class="ep">'+esc(r.error).slice(0,60)+'</span></div><span class="vals">'+r.mode+' &middot; '+r.tokens.toLocaleString()+' tokens &middot; '+cost+' &middot; iter '+r.iteration+' &middot; '+(r.duration/1000).toFixed(1)+'s</span><div style="width:100%;font-size:.75rem;color:var(--text2);margin-top:4px">'+date+' — '+esc(r.resolution).slice(0,100)+'</div></div>';
       }).join('');
     }
+    // Processes panel
+    if(proc){
+      $('proc-pid').textContent=proc.pid||'-';
+      if(proc.current){
+        $('proc-mem').textContent=proc.current.rss+'MB';
+        $('proc-cpu').textContent=proc.current.cpu+'%';
+      }
+      // Uptime from server stats
+      if(sr.session){
+        const u=Math.round((sr.session.uptime||0)/1000);
+        const h=Math.floor(u/3600),m=Math.floor((u%3600)/60),s=u%60;
+        $('proc-up').textContent=(h>0?h+'h ':'')+(m>0?m+'m ':'')+s+'s';
+      }
+      // Leak detection
+      if(proc.leakDetection){
+        const ld=proc.leakDetection;
+        $('proc-health').innerHTML='<div class="mrow"><span>Leak Detection</span><span class="vals">'+(ld.warning?'<span style="color:var(--yellow)">⚠️ Growing</span>':'<span style="color:var(--green)">✅ Stable</span>')+' ('+ld.consecutiveGrowth+'/'+ld.threshold+' samples)</span></div>'
+          +'<div class="mrow"><span>Peak Memory</span><span class="vals"><b>'+(proc.peak?.memory||0)+'MB</b></span></div>'
+          +'<div class="mrow"><span>Avg Memory</span><span class="vals"><b>'+(proc.average?.memory||0)+'MB</b></span></div>'
+          +'<div class="mrow"><span>Avg CPU</span><span class="vals"><b>'+(proc.average?.cpu||0)+'%</b></span></div>'
+          +'<div class="mrow"><span>Process Alive</span><span class="vals">'+(proc.alive?'<span style="color:var(--green)">✅ Yes</span>':'<span style="color:var(--red)">❌ No</span>')+'</span></div>';
+      }
+      // Memory timeline chart
+      if(proc.samples&&proc.samples.length>1){
+        const s=proc.samples,max=Math.max(...s.map(e=>e.rss))||1,w=$('proc-mem-chart').offsetWidth||500,h=150;
+        const bw=Math.max(3,Math.floor(w/s.length)-1);
+        let svg='<svg width="'+w+'" height="'+h+'">';
+        s.forEach((e,i)=>{
+          const bh=Math.max(2,Math.round((e.rss/max)*h*0.85));
+          const c=e.rss>400?'var(--red)':e.rss>200?'var(--yellow)':'var(--blue)';
+          svg+='<rect x="'+(i*(bw+1))+'" y="'+(h-bh)+'" width="'+bw+'" height="'+bh+'" fill="'+c+'" rx="1"><title>'+e.rss+'MB</title></rect>';
+        });
+        svg+='</svg>';
+        $('proc-mem-chart').innerHTML=svg;
+      }
+    }
+    // System info
+    const sysInfo=await fetch(B+'/api/system').then(r=>r.json()).catch(()=>({}));
+    if(sysInfo&&sysInfo.cpu){
+      $('proc-sys').innerHTML=[
+        '<div class="mrow"><span>Platform</span><span class="vals">'+esc(sysInfo.platform)+'/'+esc(sysInfo.arch)+'</span></div>',
+        '<div class="mrow"><span>CPU</span><span class="vals">'+esc((sysInfo.cpu.model||'').slice(0,40))+' ('+sysInfo.cpu.cores+' cores)</span></div>',
+        '<div class="mrow"><span>RAM</span><span class="vals">'+sysInfo.memory.totalGB+'GB total, '+sysInfo.memory.freeGB+'GB free ('+sysInfo.memory.usedPercent+'%)</span></div>',
+        '<div class="mrow"><span>Disk</span><span class="vals">'+sysInfo.disk.totalGB+'GB total, '+sysInfo.disk.freeGB+'GB free ('+sysInfo.disk.usedPercent+'%)</span></div>',
+        '<div class="mrow"><span>Node</span><span class="vals">'+esc(sysInfo.nodeVersion)+'</span></div>',
+        '<div class="mrow"><span>Hostname</span><span class="vals">'+esc(sysInfo.hostname)+'</span></div>',
+        '<div class="mrow"><span>Environment</span><span class="vals">'+esc(sysInfo.environment?.type||'unknown')+(sysInfo.environment?.cloud?' ('+sysInfo.environment.cloud+')':'')+'</span></div>',
+      ].join('');
+      // Listening ports
+      $('proc-listen').innerHTML='<div class="mrow"><span>Server</span><span class="vals">:'+(sysInfo.hostname?'running':'?')+'</span></div>'
+        +'<div class="mrow"><span>Dashboard</span><span class="vals">:'+P+'</span></div>'
+        +'<div class="mrow"><span>Workers Recommended</span><span class="vals">'+sysInfo.recommended?.workers+'</span></div>';
+    }
     // Analytics: process + routes
     if(proc&&proc.current){
       $('a-mem').textContent=proc.current.rss+'MB';

package/src/platform/telemetry.js

@@ -52,6 +52,8 @@ function collectHeartbeat(subsystems) {
       totalCost: usage?.session?.totalCostUsd || 0,
       totalCalls: usage?.session?.totalCalls || 0,
       byCategory: usage?.byCategory || {},
+      byModel: usage?.byModel || {},
+      byTool: usage?.byTool || {},
     },
 
     brain: { totalMemories: brain?.getStats()?.totalEntries || 0 },