wolverine-ai 6.4.1 → 6.4.2

package/README.md

@@ -1623,21 +1623,28 @@ Agentic AI agent mode powered by [OpenClaw](https://github.com/openclaw/openclaw
 
 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:
+### Setup (Existing OpenClaw Users) — One Command
 
 ```bash
-npm install wolverine-ai
-wolverine-claw --setup
+npx wolverine-ai@latest --setup-claw
+```
+
+That's it. One command. Zero code changes. Your existing `npm start` now runs with wolverine.
+
+What it does automatically:
+1. Detects your `.openclaw/config.yml` — merges gateway port, model, channels, security
+2. Installs `wolverine-ai` as a dependency
+3. Scaffolds `wolverine-claw/` with merged config, plugin, and workspace
+4. **Patches your start scripts** — injects `--require ./wolverine-claw/bootstrap.js` so wolverine loads automatically when your gateway starts
+5. Adds `claw`, `claw:info`, `claw:direct` npm scripts
+6. Validates everything (Node, API keys, config, entry point)
+
+```
+Before: "start": "openclaw gateway"
+After:  "start": "NODE_OPTIONS=\"--require ./wolverine-claw/bootstrap.js\" openclaw gateway"
 ```
 
-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
+Your skills, plugins, and gateway code are never modified. The bootstrap preload handles everything at the process level.
 
 Preview without changes: `wolverine-claw --setup --dry`
 
@@ -1676,29 +1683,42 @@ wolverine --rollback-latest    # Restore most recent
 
 ```
 wolverine-claw/
+├── bootstrap.js                   # --require preload (auto-injected into start scripts)
 ├── 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
+│   └── wolverine-integration.js   # 8 tools + 8 Plugin SDK hooks
 ├── 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)
+├── setup.js                       # Setup wizard (detect, merge, scaffold, validate, patch)
+├── standalone-agent.js            # Built-in agent (32 tools) when openclaw not installed
+└── wolverine-api.js               # Unified API — 85 access points across 13 subsystems
 
 bin/wolverine-claw.js              # CLI entry point
 ```
 
-### How It Works
+### How It Works (Zero-Code Integration)
+
+```
+npx wolverine-ai@latest --setup-claw
+  → Detects .openclaw/config.yml, merges settings
+  → Patches "start": "openclaw gateway"
+       into "start": "NODE_OPTIONS=\"--require ./wolverine-claw/bootstrap.js\" openclaw gateway"
+
+npm start (user's existing command)
+  → Node loads bootstrap.js before anything else
+  → global.wolverine = full API (85 access points, lazy-loaded)
+  → Module._load patched → require("openclaw") auto-registers wolverine plugin
+  → Process error handlers → report to wolverine heal pipeline via IPC
+  → Gateway starts with wolverine plugin (8 tools + 8 hooks)
+  → On crash: ClawRunner catches → AI heal → backup → fix → verify → restart
+```
 
-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
+No skills, plugins, or gateway code are ever modified. Everything is injected at the process entry point.
 
 ### Wolverine Tools for the Agent
 
@@ -1713,6 +1733,44 @@ The integration plugin gives the OpenClaw agent access to wolverine capabilities
 | `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 |
+| `wolverine_error_stats` | Error counts from all OpenClaw subsystems |
+
+### Plugin Hooks (Automatic Error Pipeline)
+
+The plugin registers 8 hooks into OpenClaw's Plugin SDK — errors from every subsystem flow to wolverine automatically:
+
+| Hook | What It Catches |
+|------|----------------|
+| `after_tool_call` | Skill and tool execution failures |
+| `agent_end` | Agent crashes, timeouts, completion errors |
+| `before_tool_call` | Tool loop detection (before it burns tokens) |
+| `message_sent` | Channel send failures (Discord, Slack, etc.) |
+| `llm_output` | Provider errors, failovers, billing blocks (402) |
+| `subagent_ended` | Subagent failures and timeouts |
+| `gateway_start/stop` | Lifecycle tracking with error stats |
+| `session_end` | Session-level errors |
+
+### Wolverine API (for Custom Skills)
+
+If you write custom OpenClaw skills that want wolverine features, they're available globally — no imports needed:
+
+```javascript
+// In any OpenClaw skill (after setup, global.wolverine is auto-available):
+
+// Scan user input for prompt injection
+const scan = wolverine.scanText(userMessage);
+if (!scan.safe) return "Blocked: injection detected";
+
+// Search past fixes
+const fixes = await wolverine.brain.search("ECONNREFUSED redis");
+
+// Diagnose an error
+const diag = wolverine.diagnoseError(errorText);
+// → { type: "missing_module", tools: {...}, humanRequired: false }
+
+// Create backup before risky operation
+wolverine.backup.create("before database migration");
+```
 
 ### Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "6.4.1",
+  "version": "6.4.2",
   "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

@@ -282,13 +282,21 @@ const SEED_DOCS = [
     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.",
+    text: "Wolverine Claw setup — one command: npx wolverine-ai@latest --setup-claw. Zero code changes needed. Flow: (1) Detect OpenClaw (node_modules, global, package.json, ~/.openclaw/config.yml). (2) Merge config — reads user's OpenClaw YAML config (gateway port, model, channels, security) and overlays onto wolverine defaults. (3) Scaffold wolverine-claw/ (config, plugins, workspace, skills). (4) Install wolverine-ai as dependency. (5) Auto-patch existing npm scripts: injects NODE_OPTIONS='--require ./wolverine-claw/bootstrap.js' into start/dev commands so wolverine loads automatically. (6) Add claw/claw:info/claw:direct npm scripts. (7) Setup .env.local with channel token templates. (8) Validate (Node, OpenClaw, API keys, config, entry point, plugin). After setup, user runs their existing 'npm start' command — wolverine is already active. No imports needed anywhere.",
     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.",
+    text: "Wolverine Claw bootstrap preload (wolverine-claw/bootstrap.js): loaded via --require, auto-injected into OpenClaw's start command by setup. What it does: (1) Initializes full wolverine API as global.wolverine — 85 access points across 13 subsystems, accessible from any skill/plugin without imports. (2) Patches Module._load to intercept require('openclaw') and auto-register the wolverine plugin when the gateway starts. (3) Installs process-level uncaughtException/unhandledRejection handlers that report errors to wolverine heal pipeline via IPC. (4) Provides wolverine.middleware.injectionGuard for route protection. The bootstrap makes wolverine completely transparent — the user's skills, plugins, and gateway code are never modified. Everything happens at the Node process entry point.",
+    metadata: { topic: "wolverine-claw-bootstrap" },
+  },
+  {
+    text: "Wolverine Claw integration plugin (wolverine-claw/plugins/wolverine-integration.js): two layers. Layer 1 — 8 tools injected into agent: wolverine_backup, wolverine_rollback, wolverine_brain_search, wolverine_brain_learn, wolverine_health, wolverine_list_backups, wolverine_self_heal, wolverine_error_stats. Layer 2 — 8 OpenClaw Plugin SDK hooks for deep error observability: after_tool_call (skill/tool failures), agent_end (agent crashes/timeouts), before_tool_call (tool loop detection), message_sent (channel send failures), llm_output (provider errors/failovers/billing), subagent_ended (subagent failures), gateway_start/stop (lifecycle). Error tracking state: per-category counts (tool/agent/channel/llm/subagent) + rolling 50-error buffer. Supports both Plugin SDK (api.registerPluginHook) and EventEmitter (gateway.on) registration.",
     metadata: { topic: "wolverine-claw-plugin" },
   },
+  {
+    text: "Wolverine API (src/claw/wolverine-api.js): unified entry point for any OpenClaw process. const api = require('wolverine-ai/src/claw/wolverine-api').init(projectRoot). 13 lazy-loaded subsystem categories, 85 verified access points: security (injection 50+ patterns, redaction, sandbox, rate limiter), brain (vector search, learn, embed, function map, tool router with 25+ error-to-tool mappings), ai (call, callWithHistory, dual-provider, model config, token tracking), errors (parse, classify, route tools, human-required detection, loop guard), backup (create, rollback, undo, list, promote, prune), skills (registry, SQL guard, deps analysis, migrations), monitor (ErrorMonitor, PerfMonitor, ProcessMonitor, AdaptiveLimiter), logger (EventLogger, TokenTracker, RepairHistory), config, agent (AgentEngine with 32 tools), context (server scanner), verify (syntax check, boot probe), mcp (McpRegistry). Convenience: api.scanText() for fast sync security scan, api.diagnoseError() for parse+classify+route+human-check. Everything lazy-loaded — requiring the module costs nothing until first use.",
+    metadata: { topic: "wolverine-api" },
+  },
   {
     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" },