wolverine-ai 3.1.0 → 3.1.1

package/.env.example

@@ -0,0 +1,20 @@
+# Wolverine — Secrets Only
+# Copy to .env.local and fill in your keys.
+# All other settings are in server/config/settings.json
+
+# ── API Keys ─────────────────────────────────────────────────────
+# Your OpenAI API key (required)
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+# ── Dashboard Admin Key  (make your own) ──────────────────────────────────────────
+# Required for the agent command interface on the dashboard.
+# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+WOLVERINE_ADMIN_KEY=
+
+# ── Custom Secrets ───────────────────────────────────────────────
+# Add any secret here — wolverine automatically redacts its value
+# from all AI calls, logs, brain storage, and dashboard output.
+#
+# DATABASE_URL=postgres://user:pass@host:5432/db
+# JWT_SECRET=my-secret
+# STRIPE_SECRET_KEY=sk_live_xxx

package/CLAUDE.md

@@ -0,0 +1,146 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+Wolverine is a self-healing Node.js server framework. It wraps a server process, catches crashes AND caught 500 errors, diagnoses them with AI (OpenAI or Anthropic), generates fixes, verifies them, and restarts — automatically. Published as `wolverine-ai` on npm (v3.1.0). 65 exports, 83 files, 6 skills.
+
+## Commands
+
+```bash
+npm start                        # Run server/index.js under wolverine (self-healing)
+npm run server                   # Run server/index.js directly (no healing)
+npm run test:pentest             # Security scan for secret leakage
+npm run demo:list                # List demo scenarios
+npm run demo -- 01               # Run specific demo
+npx wolverine server/index.js    # CLI entry point
+wolverine --info                 # System detection
+wolverine --update               # Safe framework upgrade
+wolverine --backup "reason"      # Create server snapshot
+wolverine --list-backups         # Show all snapshots
+wolverine --rollback <id>        # Restore specific backup
+wolverine --rollback-latest      # Restore most recent
+```
+
+No standard test runner — demos in `tests/fixtures/` serve as integration tests.
+
+## Architecture
+
+### Heal Pipeline (src/core/wolverine.js)
+
+```
+Error detected (crash OR caught 500 via IPC)
+  → Empty stderr? → Just restart, no AI ($0.00)
+  → Parse error → classify type → redact secrets
+  → Injection scan (skip if < 20 chars)
+  → Loop guard: same error failed 3+ times in 10min? → File bug report, stop
+  → Rate limit: 5 heals per 5min max
+  → Operational fix (zero tokens):
+      missing_module → deps.diagnose() → npm install
+      EADDRINUSE → kill stale process
+      ENOENT → create missing file
+      EACCES → chmod
+  → Token budget by complexity: simple=20K, moderate=50K, complex=100K
+  → Goal Loop (3 iterations):
+      1. Fast path: CODING_MODEL, JSON with code+commands, backup diff context
+      2. Agent: dynamic prompt (400 tokens simple, 1200 complex), 18 tools
+      3. Sub-agents: explore→plan→fix (Haiku triage, Sonnet/Opus fix only)
+  → Verify: syntax → boot probe (route probe skipped — ErrorMonitor is safety net)
+  → Success: retryCount reset, record to brain with full context
+  → Fail: rollback, brain records "DO NOT REPEAT", next iteration
+```
+
+`heal()` wraps `_healImpl()` with 5-minute `Promise.race` timeout.
+
+### IPC Error Chain (caught 500s without crash)
+
+1. **error-hook.js** — preloaded via `--require`, patches Fastify/Express for IPC. WeakSet dedup.
+2. **runner.js** — spawns child with `stdio: ["inherit","inherit","pipe","ipc"]`, listens `child.on("message")`
+3. **error-monitor.js** — tracks errors per normalized route (`/api/users/123` → `/api/users/:id`), threshold=1, 60s cooldown. Health check failures also trigger heal.
+
+### AI Client (src/core/ai-client.js)
+
+Dual provider: OpenAI + Anthropic. Auto-detected from model name (`claude-*` → Anthropic). All responses normalized to `{content, toolCalls, usage}`. **Anthropic prompt caching** — system prompt marked `cache_control: ephemeral`, 90% cheaper on repeat calls. Per-model output limits with 10% buffer. Every call tracked: latencyMs, success/failure, tokens, cost.
+
+Embeddings always use OpenAI (Anthropic has no embedding API).
+
+### Agent (src/agent/agent-engine.js)
+
+**Dynamic system prompt**: simple errors (TypeError/ReferenceError) get 400-token compact prompt with 7 tools. Complex errors get full prompt with all 18 tools + strategy table.
+
+18 tools: file (read/write/edit/glob/grep/list_dir/move_file), shell (bash_exec/git_log/git_diff), database (inspect_db/run_db_fix), diagnostics (check_port/check_env), deps (audit_deps/check_migration), research (web_fetch), control (done).
+
+**Cost optimizations**: zero-cost structural compaction (no LLM, extracts signals from messages), tool result truncation (4K cap), token estimation (`text.length/4`), pre/post tool hooks (`.wolverine/hooks.json`), error-graceful tools (`[ERROR]` results not thrown).
+
+**Protected paths**: agent cannot modify `src/`, `bin/`, `tests/`, `node_modules/`, `.env`, `package.json`. Only `server/` is editable.
+
+### Provider Config (server/config/settings.json)
+
+```json
+{ "provider": "hybrid", "openai_settings": {...}, "anthropic_settings": {...}, "hybrid_settings": {...} }
+```
+
+Config loader reads `{provider}_settings`. Env vars override per-role. Missing config sections auto-patched on startup via `_ensureDefaults()`.
+
+### Brain (src/brain/vector-store.js + brain.js)
+
+IVF-indexed vector store: k-means++ clustering, BM25 keyword search, binary persistence. 60 seed docs. Benchmarks: 100=0.2ms, 10K=4.4ms, 50K=23.7ms.
+
+**Namespace isolation**: error heals search only `errors/fixes/learnings/functions` — seed docs (20K tokens) excluded unless query is about wolverine itself. Function map hash check skips re-embedding if unchanged.
+
+### Backup (src/backup/backup-manager.js)
+
+All backups in `~/.wolverine-safe-backups/` (outside project, survives git pull/npm install). States: UNSTABLE → VERIFIED → STABLE (30min). Protected files never rolled back: `settings.json`, `db.js`, `.env.local`.
+
+### Skills (src/skills/ — 6 files)
+
+- **sql.js** — injection prevention, SafeDB, idempotency guard
+- **deps.js** — dependency diagnosis (zero tokens), npm audit, migration paths
+- **update.js** — safe framework upgrade, emergency backup, brain seed merge
+- **backup.js** — agent-friendly backup/rollback with CLI commands
+- **loop-guard.js** — infinite loop detection, bug reports, process dedup (PID file)
+- **skill-registry.js** — auto-discovery + token-scored matching
+
+### Telemetry (src/platform/)
+
+Heartbeats every 60s. Stable instance ID (persisted to `.wolverine/instance-id`). Cumulative usage from disk (not session-only). `byModel` with latency/success/tokens-per-sec/cost-per-call. `byProvider` aggregated. Auto-update checks every 5min, selective git checkout (never touches `server/`).
+
+## Key Constraints
+
+- **Server port is always 3000.** Any other port breaks APIs. Kill 3000 and bind there.
+- **Dashboard on PORT+1** (3001).
+- **heal() has 5-minute timeout.** `Promise.race` recovery.
+- **Global rate limit: 5 heals per 5 minutes.**
+- **Loop guard: 3 failed heals on same error in 10min → stop + bug report.**
+- **Error threshold: 1** — single 500 triggers heal. 60s cooldown per route.
+- **Empty stderr → just restart, no AI.** Prevents token burn on signal kills.
+- **bash_exec: 30s default, 60s cap.**
+- **Process dedup via PID file.** Kills old process on startup.
+- **Both API keys needed for hybrid mode** — OPENAI_API_KEY for embeddings.
+- **Auto-update: selective git checkout** — only updates `src/`, `bin/`, `package.json`. Never touches `server/`.
+- **Rollback protects:** `settings.json`, `db.js`, `.env.local` never overwritten.
+
+## Configuration
+
+- **Secrets:** `.env.local` (OPENAI_API_KEY, ANTHROPIC_API_KEY, WOLVERINE_ADMIN_KEY)
+- **Settings:** `server/config/settings.json` — provider, 3 model presets, cluster, telemetry, rate limits, health checks, autoUpdate, errorMonitor
+- **10 model slots:** reasoning, coding, chat, tool, classifier, audit, compacting, research, embedding
+- **Config priority:** env vars > `{provider}_settings` > defaults
+
+## Files That Matter Most
+
+| File | Why |
+|------|-----|
+| `src/core/wolverine.js` | Heal pipeline, operational fixes, goal loop, token budgets |
+| `src/core/runner.js` | Process manager, IPC, health/error monitors, loop guard, auto-update |
+| `src/core/ai-client.js` | Dual provider, prompt caching, output limits, latency tracking |
+| `src/agent/agent-engine.js` | Dynamic prompt, 18 tools, zero-cost compaction, hooks |
+| `src/agent/sub-agents.js` | Dynamic token budgets, Haiku triage, restricted tool sets |
+| `src/core/verifier.js` | Syntax + boot probe, error classification comparison |
+| `src/brain/vector-store.js` | IVF + BM25 + binary persistence |
+| `src/brain/brain.js` | 60 seed docs, namespace isolation, function map hash |
+| `src/skills/loop-guard.js` | Infinite loop detection, bug reports, process dedup |
+| `src/skills/update.js` | Safe upgrade, emergency backup, brain seed merge |
+| `src/platform/auto-update.js` | Version lock, dep verification, max 1 attempt per boot |
+| `server/config/settings.json` | Provider selection, 3 model presets, all config |

package/README.md

@@ -450,6 +450,8 @@ Three layers prevent token waste:
 
 | Technique | What it does | Cost |
 |-----------|-------------|------|
+| **Dynamic system prompt** | Simple errors get 400-token prompt with 7 tools. Complex get 1200 with 18 + strategy | 50% on 70% of heals |
+| **Brain namespace isolation** | Seed docs (20K tokens) excluded from error heals — only searched for wolverine queries | 50% context reduction |
 | **Prompt caching** | Anthropic system prompt cached server-side — 90% cheaper on repeat calls | 12-16K tokens saved per heal |
 | **Tool result truncation** | Tool output capped at 4K chars — prevents context blowup from large reads | Up to 30K saved per turn |
 | **Zero-cost compaction** | Extracts structural signals (tools, files, errors) from history — no LLM call | $0.00 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "3.1.0",
+  "version": "3.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": {
@@ -49,10 +49,9 @@
     "src/",
     "server/",
     "examples/",
-    "PLATFORM.md",
-    "TELEMETRY.md",
-    "SERVER_BEST_PRACTICES.md",
-    "README.md"
+    "README.md",
+    "CLAUDE.md",
+    ".env.example"
   ],
   "dependencies": {
     "@anthropic-ai/sdk": "^0.82.0",