wolverine-ai 6.1.2 → 6.2.0

package/README.md

@@ -1615,6 +1615,177 @@ AI summary generated with CHAT_MODEL, secrets redacted, optional webhook deliver
 
 ---
 
+## Wolverine Claw
+
+Agentic AI agent mode powered by [OpenClaw](https://github.com/openclaw/openclaw) with Wolverine self-healing. Run an always-on AI assistant that automatically recovers from crashes, heals its own errors, and learns from past fixes.
+
+### What It Does
+
+Wolverine Claw wraps the OpenClaw gateway (WebSocket control plane + Pi agent runtime) in Wolverine's process manager. When the agent crashes or encounters errors, Wolverine's AI heal pipeline kicks in — diagnoses the error, generates a fix, verifies it, and restarts. The agent gets access to Wolverine's brain (semantic memory), backup system (workspace snapshots), and self-healing tools.
+
+### Setup (Existing OpenClaw Users)
+
+If you already have OpenClaw installed, the setup wizard detects your config and merges it:
+
+```bash
+npm install wolverine-ai
+wolverine-claw --setup
+```
+
+The wizard will:
+1. Detect your OpenClaw installation and `~/.openclaw/config.yml`
+2. Merge your gateway port, model, channels, and security settings with wolverine defaults
+3. Scaffold `wolverine-claw/` with merged config
+4. Validate Node version, API keys, and dependencies
+5. Show next steps
+
+Preview without changes: `wolverine-claw --setup --dry`
+
+### Setup (Fresh Install)
+
+```bash
+git clone https://github.com/bobbyswhip/Wolverine.git
+cd Wolverine
+npm install
+cp .env.example .env.local
+# Edit .env.local — add ANTHROPIC_API_KEY or OPENAI_API_KEY
+wolverine-claw --setup
+npm run claw
+```
+
+### Commands
+
+```bash
+# Start
+npm run claw              # Start with self-healing
+npm run claw:direct       # Start without healing (debugging)
+wolverine --claw          # Same as npm run claw, via main CLI
+
+# Setup & Config
+wolverine-claw --setup    # Guided onboarding wizard
+wolverine-claw --info     # Show configuration and status
+wolverine --setup-claw    # Same setup, from main CLI
+
+# Backups
+wolverine --backup "reason"    # Snapshot workspace
+wolverine --list-backups       # Show all snapshots
+wolverine --rollback-latest    # Restore most recent
+```
+
+### Architecture
+
+```
+wolverine-claw/
+├── config/
+│   └── settings.json              # Gateway, agent, channels, healing, security
+├── index.js                       # Entry point — bootstraps OpenClaw gateway
+├── plugins/
+│   └── wolverine-integration.js   # 7 wolverine tools for the agent
+├── skills/                        # Custom user skills
+└── workspace/                     # Sandboxed agent working directory
+
+src/claw/
+├── claw-runner.js                 # Process manager with healing pipeline
+└── setup.js                       # Setup wizard (detect, merge, scaffold, validate)
+
+bin/wolverine-claw.js              # CLI entry point
+```
+
+### How It Works
+
+1. `ClawRunner` spawns `wolverine-claw/index.js` as a child process with IPC
+2. `index.js` loads OpenClaw via `require("openclaw")` (SDK mode) or falls back to `npx openclaw gateway` (CLI mode)
+3. The wolverine integration plugin injects 7 tools into the OpenClaw agent
+4. On crash/error, `ClawRunner` catches via IPC or exit event
+5. Wolverine's AI heal pipeline runs: diagnose → backup → fix → verify → restart
+6. Gateway health monitored via TCP probe on WebSocket port every 30s
+
+### Wolverine Tools for the Agent
+
+The integration plugin gives the OpenClaw agent access to wolverine capabilities:
+
+| Tool | What It Does |
+|------|-------------|
+| `wolverine_backup` | Create a workspace snapshot |
+| `wolverine_rollback` | Restore to a previous backup |
+| `wolverine_brain_search` | Search semantic memory for past fixes and patterns |
+| `wolverine_brain_learn` | Store new learnings in the brain |
+| `wolverine_health` | Get system health status (memory, uptime, backups) |
+| `wolverine_list_backups` | List all available snapshots |
+| `wolverine_self_heal` | Trigger the heal pipeline on a specific error |
+
+### Configuration
+
+Edit `wolverine-claw/config/settings.json`:
+
+```json
+{
+  "gateway": { "port": 18789, "host": "127.0.0.1" },
+  "agent": { "model": "claude-sonnet-4-6", "maxTurns": 25 },
+  "channels": {
+    "terminal": { "enabled": true },
+    "discord": { "enabled": false, "token": "" },
+    "slack": { "enabled": false, "botToken": "", "appToken": "" },
+    "telegram": { "enabled": false, "botToken": "" }
+  },
+  "healing": {
+    "enabled": true,
+    "maxHealsPerWindow": 5,
+    "windowMs": 300000,
+    "loopMaxAttempts": 3
+  },
+  "skills": {
+    "codingAgent": { "enabled": true, "sandbox": true },
+    "browserControl": { "enabled": false },
+    "cron": { "enabled": true, "maxJobs": 10 }
+  },
+  "workspace": { "path": "wolverine-claw/workspace" },
+  "security": {
+    "dmPairing": true,
+    "sandbox": true,
+    "blockedCommands": ["rm -rf /", "format", "shutdown"]
+  }
+}
+```
+
+Channel tokens go in `.env.local` (never in settings.json):
+
+```bash
+# wolverine-claw channel tokens
+DISCORD_BOT_TOKEN=your-token
+SLACK_BOT_TOKEN=xoxb-your-token
+SLACK_APP_TOKEN=xapp-your-token
+TELEGRAM_BOT_TOKEN=123456:ABC-your-token
+```
+
+### Self-Healing Pipeline
+
+Same pipeline as server healing, adapted for the claw environment:
+
+```
+Claw crashes or IPC error received
+  → Empty stderr? → Just restart ($0.00)
+  → Rate limit: 5 heals per 5min
+  → Loop guard: 3 failed heals on same error → stop + bug report
+  → AI heal: diagnose → backup → fix → verify → restart
+  → Success: retry count reset, learning stored in brain
+  → Fail: rollback to pre-heal backup, next retry
+  → Max retries: rollback to startup snapshot, stop
+```
+
+### Editable Scope
+
+The claw agent can only modify files in `wolverine-claw/`. Protected paths:
+
+- `src/` — wolverine framework code
+- `bin/` — CLI entry points
+- `server/` — user server code
+- `node_modules/` — dependencies
+- `.env`, `.env.local` — secrets
+- `.wolverine/vault/` — encrypted keys
+
+---
+
 ## License
 
 MIT

package/bin/wolverine-claw.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const dotenv = require("dotenv");
+const chalk = require("chalk");
+
+// Global error handlers — prevent parent process death
+process.on("uncaughtException", (err) => {
+  console.error(chalk.red(`\n  ⚠️  Uncaught exception (wolverine-claw survived): ${err.message}`));
+  console.error(chalk.gray(`  ${err.stack?.split("\n")[1]?.trim() || ""}`));
+});
+process.on("unhandledRejection", (reason) => {
+  const msg = reason instanceof Error ? reason.message : String(reason);
+  console.error(chalk.red(`\n  ⚠️  Unhandled rejection (wolverine-claw survived): ${msg}`));
+});
+
+// Load secrets
+dotenv.config({ path: path.resolve(process.cwd(), ".env.local") });
+dotenv.config({ path: path.resolve(process.cwd(), ".env") });
+
+const args = process.argv.slice(2);
+const fs = require("fs");
+
+// --help
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`
+${chalk.blue("🐾 Wolverine Claw")} — Agentic AI agent with self-healing
+
+${chalk.bold("Usage:")}
+  wolverine-claw [options]
+
+${chalk.bold("Options:")}
+  --help, -h       Show this help
+  --setup          Full guided setup (detects OpenClaw, merges config, validates)
+  --setup --dry    Preview setup without making changes
+  --info           Show claw configuration and status
+  --init           Initialize wolverine-claw/ directory (first run)
+  --direct         Run claw directly without wolverine healing wrapper
+
+${chalk.bold("Configuration:")}
+  wolverine-claw/config/settings.json    Gateway, channels, agent, healing
+  .env.local                             Secrets (API keys)
+
+${chalk.bold("Examples:")}
+  wolverine-claw --setup          Full guided onboarding
+  wolverine-claw                  Start with self-healing
+  wolverine-claw --direct         Start without healing (debugging)
+  wolverine-claw --info           Show configuration
+`);
+  process.exit(0);
+}
+
+// --setup: full guided setup
+if (args.includes("--setup")) {
+  const { setup } = require("../src/claw/setup");
+  const dryRun = args.includes("--dry") || args.includes("--dry-run");
+  const force = args.includes("--force");
+
+  (async () => {
+    const result = await setup(process.cwd(), { dryRun, force });
+    process.exit(result.success ? 0 : 1);
+  })();
+  return;
+}
+
+// --init: scaffold wolverine-claw directory if missing
+if (args.includes("--init")) {
+  const clawDir = path.resolve(process.cwd(), "wolverine-claw");
+
+  if (fs.existsSync(path.join(clawDir, "index.js"))) {
+    console.log(chalk.green("\n  ✅ wolverine-claw/ already exists.\n"));
+    process.exit(0);
+  }
+
+  console.log(chalk.blue("\n  🐾 Initializing wolverine-claw/ ...\n"));
+
+  // Copy from templates if available, otherwise the files should already exist
+  const dirs = ["config", "plugins", "workspace"];
+  for (const d of dirs) {
+    const dirPath = path.join(clawDir, d);
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+      console.log(chalk.gray(`  Created: wolverine-claw/${d}/`));
+    }
+  }
+
+  console.log(chalk.green("\n  ✅ wolverine-claw/ initialized."));
+  console.log(chalk.gray("  Edit wolverine-claw/config/settings.json to configure.\n"));
+  process.exit(0);
+}
+
+// --info: show claw config and status
+if (args.includes("--info")) {
+  const configPath = path.resolve(process.cwd(), "wolverine-claw", "config", "settings.json");
+
+  if (!fs.existsSync(configPath)) {
+    console.log(chalk.yellow("\n  ⚠️  wolverine-claw/ not found. Run: wolverine-claw --init\n"));
+    process.exit(1);
+  }
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    const gw = config.gateway || {};
+    const agent = config.agent || {};
+    const channels = config.channels || {};
+    const healing = config.healing || {};
+
+    console.log(chalk.blue.bold("\n  🐾 Wolverine Claw — Configuration\n"));
+    console.log(chalk.gray(`  Gateway:      ws://${gw.host || "127.0.0.1"}:${gw.port || 18789}`));
+    console.log(chalk.gray(`  Agent model:  ${agent.model || "claude-sonnet-4-6"}`));
+    console.log(chalk.gray(`  Max turns:    ${agent.maxTurns || 25}`));
+    console.log(chalk.gray(`  Healing:      ${healing.enabled !== false ? "enabled" : "disabled"}`));
+    console.log(chalk.gray(`  Max heals:    ${healing.maxHealsPerWindow || 5} per ${Math.round((healing.windowMs || 300000) / 60000)}min`));
+
+    const enabledChannels = Object.entries(channels)
+      .filter(([k, v]) => !k.startsWith("_") && v.enabled)
+      .map(([k]) => k);
+    console.log(chalk.gray(`  Channels:     ${enabledChannels.length > 0 ? enabledChannels.join(", ") : "terminal only"}`));
+
+    // Check for API keys
+    const hasOpenAI = !!process.env.OPENAI_API_KEY;
+    const hasAnthropic = !!process.env.ANTHROPIC_API_KEY;
+    console.log(chalk.gray(`  OpenAI key:   ${hasOpenAI ? "set" : "missing"}`));
+    console.log(chalk.gray(`  Anthropic:    ${hasAnthropic ? "set" : "missing"}`));
+
+    // Check openclaw installation
+    let openclawVersion = "not installed";
+    try {
+      const pkg = require("openclaw/package.json");
+      openclawVersion = pkg.version;
+    } catch {
+      try {
+        const { execSync } = require("child_process");
+        const ver = execSync("npx openclaw --version 2>/dev/null", { encoding: "utf-8" }).trim();
+        openclawVersion = ver || "available via npx";
+      } catch {
+        openclawVersion = "not installed (will use npx)";
+      }
+    }
+    console.log(chalk.gray(`  OpenClaw:     ${openclawVersion}`));
+    console.log("");
+  } catch (err) {
+    console.error(chalk.red(`  Config error: ${err.message}\n`));
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// --direct: run without wolverine healing wrapper
+if (args.includes("--direct")) {
+  console.log(chalk.blue("\n  🐾 Starting Wolverine Claw (direct mode — no healing)\n"));
+  require("../wolverine-claw/index");
+  return;
+}
+
+// Default: start with wolverine self-healing
+const { ClawRunner } = require("../src/claw/claw-runner");
+
+console.log(chalk.blue.bold("\n  🐾 Wolverine Claw — Starting with Self-Healing\n"));
+
+const runner = new ClawRunner({ cwd: process.cwd() });
+
+// Grace period: ignore SIGTERM for 3s after startup
+let startupGrace = true;
+setTimeout(() => { startupGrace = false; }, 3000);
+
+process.on("SIGINT", () => {
+  console.log(chalk.blue("\n\n  👋 Shutting down Wolverine Claw..."));
+  runner.stop();
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  if (startupGrace) {
+    console.log(chalk.yellow("  ⚡ Ignoring SIGTERM during startup grace period (3s)"));
+    return;
+  }
+  runner.stop();
+  process.exit(0);
+});
+
+runner.start();

package/bin/wolverine.js

@@ -39,6 +39,8 @@ ${chalk.bold("Options:")}
   --info           Show system info and exit
   --init           Scan server/ and build context map (routes, DB, config, deps)
   --restart        Full restart (kills parent + children, re-launches fresh)
+  --claw           Launch wolverine-claw (agentic agent mode)
+  --setup-claw     Guided setup for wolverine-claw (detects OpenClaw, merges config)
   --x402-info      Show x402 payment configuration
 
 ${chalk.bold("Configuration:")}
@@ -243,6 +245,31 @@ if (args.includes("--backups")) {
   process.exit(0);
 }
 
+// --setup-claw: run claw setup wizard
+if (args.includes("--setup-claw")) {
+  const { setup } = require("../src/claw/setup");
+  const dryRun = args.includes("--dry-run");
+  (async () => {
+    const result = await setup(process.cwd(), { dryRun });
+    process.exit(result.success ? 0 : 1);
+  })();
+  return;
+}
+
+// --claw: launch wolverine-claw instead of server
+if (args.includes("--claw")) {
+  const clawArgs = args.filter(a => a !== "--claw");
+  const { ClawRunner } = require("../src/claw/claw-runner");
+  console.log(chalk.blue.bold("\n  🐾 Wolverine Claw — Agentic Agent with Self-Healing\n"));
+  const clawRunner = new ClawRunner({ cwd: process.cwd() });
+
+  process.on("SIGINT", () => { clawRunner.stop(); process.exit(0); });
+  process.on("SIGTERM", () => { clawRunner.stop(); process.exit(0); });
+
+  clawRunner.start();
+  return;
+}
+
 const scriptPath = args.find(a => !a.startsWith("--")) || "server/index.js";
 
 // Initialize server/ from template if it doesn't exist (first run)

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "wolverine-ai",
-  "version": "6.1.2",
+  "version": "6.2.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": {
-    "wolverine": "./bin/wolverine.js"
+    "wolverine": "./bin/wolverine.js",
+    "wolverine-claw": "./bin/wolverine-claw.js"
   },
   "scripts": {
     "start": "node bin/wolverine.js server/index.js",
     "dev": "node bin/wolverine.js server/index.js",
     "wolverine": "node bin/wolverine.js",
     "server": "node server/index.js",
+    "claw": "node bin/wolverine-claw.js",
+    "claw:direct": "node bin/wolverine-claw.js --direct",
+    "claw:info": "node bin/wolverine-claw.js --info",
     "demo": "node examples/run-demo.js",
     "demo:list": "node examples/run-demo.js --list",
     "test:pentest": "node tests/pentest-secrets.js"
@@ -47,6 +51,7 @@
   "files": [
     "bin/",
     "src/",
+    "wolverine-claw/",
     "examples/",
     ".env.example"
   ],
@@ -64,6 +69,7 @@
     "viem": "^2.0.0"
   },
   "optionalDependencies": {
+    "openclaw": "^1.0.0",
     "@coinbase/cdp-sdk": "^1.46.1",
     "@privy-io/server-auth": "1.14.0",
     "@x402/core": "^2.9.0",

package/src/brain/brain.js

@@ -277,6 +277,26 @@ const SEED_DOCS = [
     text: "Auto-update: wolverine checks npm registry hourly for new versions. When found, runs npm install wolverine-ai@latest, backs up settings.json/.env.local before update and restores after. Config: autoUpdate.enabled (default true) in settings.json. Disable with WOLVERINE_AUTO_UPDATE=false env var. On successful update, signals runner to restart. Protected files never overwritten: settings.json, .env.local, .env, db.js. Update check runs 30s after startup then every hour (configurable via autoUpdate.intervalMs).",
     metadata: { topic: "auto-update" },
   },
+  {
+    text: "Wolverine Claw: agentic AI agent mode powered by OpenClaw with Wolverine self-healing. Wraps the OpenClaw gateway (WebSocket control plane + Pi agent runtime) in Wolverine's process manager for automatic crash recovery, AI-powered healing, and workspace backup. Architecture: wolverine-claw/index.js bootstraps OpenClaw (tries require('openclaw') SDK first, falls back to npx openclaw CLI). ClawRunner (src/claw/claw-runner.js) spawns the claw process with IPC, monitors for crashes and gateway errors, triggers heal pipeline on failures. Gateway health monitored via TCP probe on WebSocket port (default 18789). Config: wolverine-claw/config/settings.json with gateway, agent, channels, healing, skills, workspace, security sections. CLI: wolverine-claw --setup (guided onboarding), npm run claw (start with healing), wolverine --claw (same via main CLI), wolverine-claw --direct (no healing). Workspace: wolverine-claw/workspace/ is the sandboxed agent working directory.",
+    metadata: { topic: "wolverine-claw" },
+  },
+  {
+    text: "Wolverine Claw setup: guided onboarding for OpenClaw users (wolverine-claw --setup). 8-step flow: (1) Detect environment — Node version, OpenClaw installation (checks local node_modules, global install, package.json dep, ~/.openclaw/config.yml), API keys, wolverine core. (2) Abort if Node < 22. (3) Merge config — reads user's OpenClaw YAML config (gateway port, model, channels, security) and overlays onto wolverine-claw defaults. OpenClaw values win, wolverine fills gaps. (4) Scaffold — creates wolverine-claw/ with config/settings.json, plugins/wolverine-integration.js, workspace/, skills/. Never overwrites existing files. (5) Environment — ensures .env.local has claw-specific key templates (DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN, etc). (6) Install — npm install openclaw --save-optional (falls back to npx). (7) Validate — 7 checks: Node, OpenClaw, API keys, config, entry point, plugin, wolverine core. (8) Next steps. Also available as wolverine --setup-claw from main CLI. Dry run: wolverine-claw --setup --dry.",
+    metadata: { topic: "wolverine-claw-setup" },
+  },
+  {
+    text: "Wolverine Claw integration plugin (wolverine-claw/plugins/wolverine-integration.js): registers 7 wolverine tools into the OpenClaw agent toolkit. Tools: wolverine_backup (create workspace snapshot), wolverine_rollback (restore to previous backup), wolverine_brain_search (semantic search of wolverine's memory for past fixes/patterns), wolverine_brain_learn (store new learnings in brain), wolverine_health (system health status), wolverine_list_backups (list all snapshots), wolverine_self_heal (trigger heal pipeline on a specific error). Plugin hooks into gateway events (error, agent:error, skill:error) to report errors to wolverine parent via IPC for automatic healing. Sends heartbeat every 30s. Registered via gateway.registerTools(), gateway.addTools(), or gateway.skills.register() depending on OpenClaw API version.",
+    metadata: { topic: "wolverine-claw-plugin" },
+  },
+  {
+    text: "Wolverine Claw configuration (wolverine-claw/config/settings.json): gateway (port 18789, host 127.0.0.1), agent (model claude-sonnet-4-6, maxTurns 25, timeoutMs 120000), models (reasoning/coding/chat/embedding per-task), channels (terminal enabled by default, discord/slack/telegram/whatsapp configurable with tokens in .env.local), healing (enabled, healTimeoutMs 300000, maxHealsPerWindow 5, loopMaxAttempts 3), skills (codingAgent with sandbox+allowedPaths, browserControl, cron, canvas), workspace (path wolverine-claw/workspace, maxFileSizeMB 50), security (dmPairing true, sandbox true, blockedCommands, maxConcurrentSessions 5), logging, remoteAccess (disabled, tailscale method), backup (stabilityMs 1800000, retentionDays 7). Editable scope: only wolverine-claw/ files can be modified by the claw agent. src/, bin/, server/ are protected.",
+    metadata: { topic: "wolverine-claw-config" },
+  },
+  {
+    text: "Wolverine Claw channels: OpenClaw supports 20+ messaging platforms. Configure in wolverine-claw/config/settings.json channels section. Terminal: always enabled (local CLI). Discord: set enabled:true, add DISCORD_BOT_TOKEN to .env.local. Slack: set enabled:true, add SLACK_BOT_TOKEN + SLACK_APP_TOKEN to .env.local. Telegram: set enabled:true, add TELEGRAM_BOT_TOKEN to .env.local. WhatsApp: set enabled:true, requires WhatsApp Business API setup. Each channel's tokens go in .env.local (never in settings.json). The claw setup wizard (--setup) detects existing OpenClaw channel config from ~/.openclaw/config.yml and merges it automatically.",
+    metadata: { topic: "wolverine-claw-channels" },
+  },
   {
     text: "Loop guard: detects infinite heal loops and stops burning tokens. Tracks heal attempts by error signature — if 3+ heals fail on same error in 10 minutes, STOPS healing and generates a bug report. Bug report sent to platform backend for human review (security scanned for injection/secrets first). 30-minute cooldown after bug report filed. Process dedup via PID file (.wolverine/wolverine.pid) ensures only one wolverine instance runs — kills old process on startup. Config: WOLVERINE_LOOP_MAX_ATTEMPTS (default 3), WOLVERINE_LOOP_WINDOW_MS (default 600000).",
     metadata: { topic: "loop-guard" },