wolverine-ai 6.0.2 → 6.1.1

package/README.md

@@ -1307,12 +1307,62 @@ Wolverine minimizes AI spend through 7 techniques:
 
 ## Configuration
 
-```
-.env.local                     ← Secrets only (API keys, admin key)
-server/config/settings.json    ← Everything else (models, port, clustering, telemetry, limits)
-```
+All settings are in `server/config/settings.json`. Each section has a `_` prefixed description field.
+
+### Settings Reference
+
+| Section | Key | Default | Description |
+|---------|-----|---------|-------------|
+| **models** | reasoning, coding, chat, tool, classifier, audit, compacting, research | `claude-sonnet-4-6` | AI model per task. Provider auto-detected from name. |
+| **embedding** | — | `text-embedding-3-small` | Vector embedding model for brain memory. |
+| **server** | port | `3000` | Server listen port. |
+| | maxRetries | `3` | Consecutive crashes before giving up. |
+| | maxMemoryMB | `512` | OOM kill threshold. |
+| **heal** | healTimeoutMs | `300000` (5 min) | Max time for entire heal attempt. |
+| | globalMaxHeals | `5` | Max heals across all errors per window. |
+| | globalWindowMs | `300000` (5 min) | Window for global heal rate limit. |
+| | loopMaxAttempts | `3` | Same-error failures before stop + bug report. |
+| | loopWindowMs | `600000` (10 min) | Window for loop guard. |
+| **agent** | aiCallTimeoutMs | `90000` (90 sec) | Timeout per AI API call. |
+| | maxTurns | `8` | Agent tool-use iterations per heal. |
+| | tokenBudget.simple | `20000` | Token budget for simple errors. |
+| | tokenBudget.moderate | `50000` | Token budget for moderate errors. |
+| | tokenBudget.complex | `100000` | Token budget for complex errors. |
+| **rateLimiting** | maxCallsPerWindow | `32` | AI calls allowed per window. |
+| | windowMs | `100000` | Rate limit window. |
+| | minGapMs | `5000` | Min delay between AI calls. |
+| | maxTokensPerHour | `1000000` | Hard token ceiling. |
+| **healthCheck** | intervalMs | `15000` (15 sec) | Health probe frequency. |
+| | timeoutMs | `5000` | Timeout per probe. |
+| | failThreshold | `3` | Consecutive failures before heal. |
+| | startDelayMs | `10000` | Grace period after boot. |
+| **errorMonitor** | defaultThreshold | `1` | 500 errors before triggering heal. |
+| | windowMs | `30000` | Error counting window. |
+| | cooldownMs | `60000` | Min time between heals on same route. |
+| **adaptiveLimiter** | thresholdYellow | `70` | CPU/memory % to start shedding 30% of requests. |
+| | thresholdRed | `85` | CPU/memory % to reject all non-essential requests. |
+| | reserveMB | `200` | Memory reserved for heal tools. |
+| **backup** | stabilityMs | `1800000` (30 min) | Time before backup marked STABLE. |
+| | retentionDays | `7` | Auto-delete old backups. |
+| | maxFileSizeMB | `10` | Skip files larger than this. |
+| **autoUpdate** | enabled | `false` | Auto-update framework from git. |
+| | intervalMs | `300000` (5 min) | Update check frequency. |
+| **telemetry** | enabled | `true` | Send heartbeats to dashboard. |
+| | heartbeatIntervalMs | `60000` (1 min) | Heartbeat frequency. |
+
+All values accept environment variable overrides (e.g., `WOLVERINE_HEAL_TIMEOUT_MS=600000`).
+
+### Secrets
+
+Secrets go in `.env.local` (never committed):
 
-`settings.json` is inside `server/` so the agent can read and edit it. Config loader priority: **env vars > settings.json > defaults**.
+```bash
+OPENAI_API_KEY=           # Required for OpenAI models
+ANTHROPIC_API_KEY=        # Required for Claude models
+WOLVERINE_ADMIN_KEY=      # Dashboard agent command interface
+CDP_API_KEY_ID=           # x402 payments (free at cdp.coinbase.com)
+CDP_API_KEY_SECRET=       # x402 payments
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "6.0.2",
+  "version": "6.1.1",
   "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/src/brain/brain.js

@@ -201,6 +201,10 @@ const SEED_DOCS = [
     text: "x402 troubleshooting — common issues and fixes. (1) 'Unauthorized' from CDP facilitator: the @coinbase/x402 package handles JWT auth internally using CDP_API_KEY_ID + CDP_API_KEY_SECRET from env vars — do NOT set a facilitator URL in settings.json. (2) '400 Bad Request': payload format mismatch — v2 uses x402Version:2, network:'eip155:8453', amount (not maxAmountRequired). Parse base64 JSON directly, don't use decodePayment(). (3) 'invalid_exact_evm_payload_signature': EIP-712 signature wrong — check domain (name:'USD Coin', version:'2', chainId:8453, verifyingContract:USDC). (4) USDC not moving: old middleware only verified without settling — must use x402ResourceServer.verifyPayment() + settlePayment() which goes through the CDP facilitator. (5) Frontend value as hex (0xf4240): must use decimal strings ('1000000'). (6) ESM errors: @coinbase/x402 needs Node 22+. (7) Packages disappearing after --update: they're in package.json dependencies + auto-installed on startup when vault exists. (8) Credits granted before settlement: verify+settle must both be in preHandler, not onSend. (9) v2 auth trick: pass @coinbase/x402's facilitator config to @x402/core HTTPFacilitatorClient — this gives v2 protocol with CDP auth that actually works.",
     metadata: { topic: "x402-troubleshooting" },
   },
+  {
+    text: "settings.json configuration — all wolverine behavior is configurable in server/config/settings.json. Sections: (1) models: 8 task-specific AI model slots (reasoning, coding, chat, tool, classifier, audit, compacting, research). Provider auto-detected from model name. (2) embedding: vector embedding model for brain. (3) server: port, maxRetries, maxMemoryMB. (4) heal: healTimeoutMs (default 300000/5min), globalMaxHeals (5 heals per globalWindowMs 300000/5min — prevents runaway costs), loopMaxAttempts (3 failed heals on same error in loopWindowMs 600000/10min = stop + bug report). (5) agent: aiCallTimeoutMs (90000/90s per AI call), maxTurns (8 agent iterations per heal), tokenBudget by complexity (simple: 20000, moderate: 50000, complex: 100000). (6) rateLimiting: maxCallsPerWindow (32), windowMs, minGapMs (5000), maxTokensPerHour (1000000). (7) healthCheck: intervalMs (15000), timeoutMs (5000), failThreshold (3), startDelayMs (10000). (8) errorMonitor: defaultThreshold (1 = single 500 triggers heal), windowMs (30000), cooldownMs (60000). (9) adaptiveLimiter: thresholdYellow (70% CPU/mem = start shedding 30% requests), thresholdRed (85% = reject all non-essential), reserveMB (200MB reserved for heal tools). (10) backup: stabilityMs (1800000/30min before STABLE), retentionDays (7), maxFileSizeMB (10). (11) autoUpdate: enabled, intervalMs. (12) telemetry: enabled, heartbeatIntervalMs. All values accept env var overrides (e.g. WOLVERINE_HEAL_TIMEOUT_MS). Description fields prefixed with _ explain each section inline.",
+    metadata: { topic: "configuration" },
+  },
   {
     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" },

package/src/core/config.js

@@ -98,6 +98,36 @@ function loadConfig() {
       windowMs: parseInt(process.env.WOLVERINE_ERROR_WINDOW_MS, 10) || fileConfig.errorMonitor?.windowMs || 30000,
       cooldownMs: parseInt(process.env.WOLVERINE_ERROR_COOLDOWN_MS, 10) || fileConfig.errorMonitor?.cooldownMs || 60000,
     },
+
+    heal: {
+      healTimeoutMs:    parseInt(process.env.WOLVERINE_HEAL_TIMEOUT_MS, 10)         || fileConfig.heal?.healTimeoutMs    || 300000,
+      globalMaxHeals:   parseInt(process.env.WOLVERINE_RATE_MAX_GLOBAL_HEALS, 10)   || fileConfig.heal?.globalMaxHeals   || 5,
+      globalWindowMs:   parseInt(process.env.WOLVERINE_RATE_GLOBAL_WINDOW_MS, 10)   || fileConfig.heal?.globalWindowMs   || 300000,
+      loopMaxAttempts:  parseInt(process.env.WOLVERINE_LOOP_MAX_ATTEMPTS, 10)       || fileConfig.heal?.loopMaxAttempts  || 3,
+      loopWindowMs:     parseInt(process.env.WOLVERINE_LOOP_WINDOW_MS, 10)          || fileConfig.heal?.loopWindowMs     || 600000,
+    },
+
+    agent: {
+      aiCallTimeoutMs: parseInt(process.env.WOLVERINE_AI_CALL_TIMEOUT_MS, 10) || fileConfig.agent?.aiCallTimeoutMs || 90000,
+      maxTurns:        parseInt(process.env.WOLVERINE_AGENT_MAX_TURNS, 10)    || fileConfig.agent?.maxTurns        || 8,
+      tokenBudget: {
+        simple:   fileConfig.agent?.tokenBudget?.simple   || 20000,
+        moderate: fileConfig.agent?.tokenBudget?.moderate  || 50000,
+        complex:  fileConfig.agent?.tokenBudget?.complex   || 100000,
+      },
+    },
+
+    adaptiveLimiter: {
+      thresholdYellow: fileConfig.adaptiveLimiter?.thresholdYellow || 70,
+      thresholdRed:    fileConfig.adaptiveLimiter?.thresholdRed    || 85,
+      reserveMB:       fileConfig.adaptiveLimiter?.reserveMB       || 200,
+    },
+
+    backup: {
+      stabilityMs:   fileConfig.backup?.stabilityMs   || 1800000,
+      retentionDays: fileConfig.backup?.retentionDays  || 7,
+      maxFileSizeMB: fileConfig.backup?.maxFileSizeMB  || 10,
+    },
   };
 
   // Migrate old settings.json to new format + ensure defaults

package/src/core/runner.js

@@ -69,8 +69,8 @@ class WolverineRunner {
       windowMs: cfg.rateLimiting.windowMs,
       minGapMs: cfg.rateLimiting.minGapMs,
       maxTokensPerHour: cfg.rateLimiting.maxTokensPerHour,
-      maxGlobalHealsPerWindow: parseInt(process.env.WOLVERINE_RATE_MAX_GLOBAL_HEALS, 10) || 5,
-      globalWindowMs: parseInt(process.env.WOLVERINE_RATE_GLOBAL_WINDOW_MS, 10) || 300000,
+      maxGlobalHealsPerWindow: cfg.heal?.globalMaxHeals || 5,
+      globalWindowMs: cfg.heal?.globalWindowMs || 300000,
     });
     this.backupManager = new BackupManager(this.cwd);
     this.logger = new EventLogger(this.cwd);

package/src/core/wolverine.js

@@ -32,7 +32,9 @@ const { getSummary: getServerContextSummary } = require("./server-context");
  * The engine tries fast path first. If that fails verification, it escalates to the agent.
  */
 async function heal(opts) {
-  const HEAL_TIMEOUT_MS = parseInt(process.env.WOLVERINE_HEAL_TIMEOUT_MS, 10) || 300000; // 5 min
+  const { loadConfig } = require("./config");
+  const _cfg = loadConfig();
+  const HEAL_TIMEOUT_MS = _cfg.heal?.healTimeoutMs || 300000;
   try {
     return await Promise.race([
       _healImpl(opts),

package/src/templates/server/config/settings.json

@@ -7,7 +7,7 @@
     "env": "development"
   },
 
-  "_models": "AI models for each task. Provider auto-detected from name (claude-* = Anthropic, gpt-* = OpenAI). Using one model across all roles maximizes prompt cache hits. See wolverine dashboard at localhost:PORT+1/analytics for per-role cost/speed metrics.",
+  "_models": "AI models for each task. Provider auto-detected from name (claude-* = Anthropic, gpt-* = OpenAI). Using one model across all roles maximizes prompt cache hits. Dashboard at localhost:PORT+1/analytics shows per-role cost/speed.",
   "models": {
     "reasoning": "claude-sonnet-4-6",
     "coding": "claude-sonnet-4-6",
@@ -22,20 +22,40 @@
   "_embedding": "Vector embedding model for brain memory. Requires OPENAI_API_KEY.",
   "embedding": "text-embedding-3-small",
 
-  "_server": "port: server listen port | maxRetries: consecutive crashes before giving up | maxMemoryMB: OOM threshold",
+  "_server": "port: listen port (3000) | maxRetries: crashes before giving up | maxMemoryMB: OOM kill threshold",
   "server": {
     "port": 3000,
     "maxRetries": 3,
     "maxMemoryMB": 512
   },
 
+  "_heal": "Controls the self-healing pipeline. healTimeoutMs: max time for entire heal attempt. globalMaxHeals/globalWindowMs: rate limit across ALL errors (prevents runaway costs). loopMaxAttempts/loopWindowMs: same-error loop guard (stops after N failures on the same error).",
+  "heal": {
+    "healTimeoutMs": 300000,
+    "globalMaxHeals": 5,
+    "globalWindowMs": 300000,
+    "loopMaxAttempts": 3,
+    "loopWindowMs": 600000
+  },
+
+  "_agent": "Controls the AI agent. aiCallTimeoutMs: max time per AI API call. maxTurns: agent tool-use iterations per heal. tokenBudget: max tokens per heal attempt (simple/moderate/complex auto-selected).",
+  "agent": {
+    "aiCallTimeoutMs": 90000,
+    "maxTurns": 8,
+    "tokenBudget": {
+      "simple": 20000,
+      "moderate": 50000,
+      "complex": 100000
+    }
+  },
+
   "_telemetry": "Heartbeat reports server health to the dashboard. Disable for fully offline servers.",
   "telemetry": {
     "enabled": true,
     "heartbeatIntervalMs": 60000
   },
 
-  "_rateLimiting": "AI call budget. Prevents runaway costs from heal loops.",
+  "_rateLimiting": "AI call budget per window. Prevents runaway costs from heal loops.",
   "rateLimiting": {
     "maxCallsPerWindow": 32,
     "windowMs": 100000,
@@ -51,13 +71,27 @@
     "startDelayMs": 10000
   },
 
-  "_errorMonitor": "Tracks caught 500 errors per route. defaultThreshold: how many 500s before triggering a heal. cooldownMs: minimum time between heals on the same route.",
+  "_errorMonitor": "Tracks caught 500 errors per route. defaultThreshold: how many 500s trigger a heal. cooldownMs: min time between heals on same route.",
   "errorMonitor": {
     "defaultThreshold": 1,
     "windowMs": 30000,
     "cooldownMs": 60000
   },
 
+  "_adaptiveLimiter": "CPU/memory-based request throttling. thresholdYellow: start shedding 30% of requests. thresholdRed: reject all non-essential. reserveMB: memory reserved for heal tools.",
+  "adaptiveLimiter": {
+    "thresholdYellow": 70,
+    "thresholdRed": 85,
+    "reserveMB": 200
+  },
+
+  "_backup": "Server snapshots. stabilityMs: time before backup is marked STABLE. retentionDays: auto-delete old backups. maxFileSizeMB: skip files larger than this.",
+  "backup": {
+    "stabilityMs": 1800000,
+    "retentionDays": 7,
+    "maxFileSizeMB": 10
+  },
+
   "_autoUpdate": "Auto-updates wolverine framework from git. Only updates src/ and bin/ — never touches server/ code.",
   "autoUpdate": {
     "enabled": false,