wolverine-ai 5.3.4 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "5.3.4",
+  "version": "5.4.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": {
@@ -60,7 +60,8 @@
     "dotenv": "^16.4.7",
     "fastify": "^5.8.4",
     "openai": "^4.73.0",
-    "x402": "^1.1.0"
+    "x402": "^1.1.0",
+    "viem": "^2.0.0"
   },
   "optionalDependencies": {
     "@coinbase/cdp-sdk": "^1.46.1",
@@ -71,8 +72,7 @@
     "ethers": "^6.0.0",
     "ioredis": "^5.0.0",
     "pg": "^8.0.0",
-    "stripe": "^18.0.0",
-    "viem": "^2.0.0"
+    "stripe": "^18.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/brain/brain.js

@@ -190,13 +190,17 @@ const SEED_DOCS = [
     metadata: { topic: "notifications" },
   },
   {
-    text: "x402 paid APIs — turn any route into a paid API with one flag. Register the plugin once: fastify.register(require('wolverine-ai/src/middleware/x402-fastify')). Then add { config: { x402: { price: '$0.10' } } } to any route definition. That's it — the route now requires USDC payment on Base. Routes WITHOUT x402 config are completely unaffected (zero overhead). Two modes: (1) Fixed price: { x402: { price: '$0.10' } } — every call costs exactly $0.10. (2) Variable price: { x402: { variable: true, min: '$1', max: '$10000', priceField: 'dollars' } } — caller specifies amount in request body. Settlement flow: no Payment-Signature header → 402 + Payment-Required header with price/network/payTo. Client SDK (@x402/fetch or wallet signing) handles payment → retries with Payment-Signature → middleware sends to x402 facilitator (CDP production: api.cdp.coinbase.com/platform/v2/x402, testnet: x402.org/facilitator) → facilitator verifies signature AND executes on-chain transferWithAuthorization() → USDC moves on Base → req.x402 = { paid: true, amount: '$5.00', from: '0x...', txHash } → handler runs. Fallback: if facilitator is down, server self-settles using vault wallet to call transferWithAuthorization() directly (server pays gas). Facilitator auto-selected by network: eip155:8453 (Base mainnet) → production, eip155:84532 (Base Sepolia) → testnet. Bazaar compatible — services auto-cataloged on first facilitator-settled payment. Vault wallet auto-detected as payTo address. Dashboard tracks x402 payments, revenue by route, USDC/ETH balances. CLI: wolverine --x402-info.",
+    text: "x402 paid APIs — turn any route into a paid API with one flag. Register the plugin: fastify.register(require('wolverine-ai/src/middleware/x402-fastify')). Add { config: { x402: { price: '$0.10' } } } to any route. Routes WITHOUT x402 config are unaffected. Two modes: (1) Fixed price: { x402: { price: '$0.10' } }. (2) Variable price: { x402: { variable: true, min: '$1', max: '$10000', priceField: 'dollars' } }. Uses @coinbase/x402 facilitator (built-in, no auth config needed) + x402/verify for payment verification and on-chain settlement. Protocol is x402 v1 — network must be 'base' (NOT 'eip155:8453'). Payment header: X-PAYMENT or payment-signature (base64 JSON). Verify happens in preHandler hook, settle happens in onSend hook (after handler succeeds). Vault wallet auto-detected as payTo. Requires: Node 22+, CDP_API_KEY_ID + CDP_API_KEY_SECRET in .env.local (get free at cdp.coinbase.com), npm packages @coinbase/x402 + x402 + viem. CRITICAL SETUP NOTES: (1) network MUST be 'base' not 'eip155:8453' — the v1 SDK uses human-readable names. (2) Do NOT set a facilitator URL in settings.json — the @coinbase/x402 package has it built-in. (3) paymentRequirements.resource must be a full URL (https://host/path) not 'POST /path'. (4) paymentRequirements.asset must be checksummed via viem's getAddress(). (5) paymentRequirements.extra must be { name: 'USD Coin', version: '2' } for USDC EIP-712 domain. (6) maxAmountRequired must match the user's payment value for variable pricing. (7) Frontend payment payload format: { x402Version: 1, scheme: 'exact', network: 'base', payload: { authorization: { from, to, value (decimal string), validAfter (string), validBefore (string), nonce (0x hex) }, signature } }. Dashboard tracks x402 payments, revenue by route, USDC/ETH balances.",
     metadata: { topic: "x402-paid-apis" },
   },
   {
-    text: "x402 examples — making a paid API is as simple as adding a route. FREE route (normal): fastify.get('/api/data', async (req) => { return getData(); }). PAID route (just add x402 flag): fastify.get('/api/premium-data', { config: { x402: { price: '$0.01' } } }, async (req) => { return getPremiumData(); }). CREDIT PURCHASE route (variable): fastify.post('/buy-credits', { config: { x402: { variable: true, min: '$1', max: '$10000', priceField: 'dollars' } } }, async (req) => { const credits = parseFloat(req.x402.amount.replace('$','')) * 100; await addCredits(req.body.accountId, credits); return { credits }; }). Payment settlement is automatic — the facilitator verifies and settles on-chain before the handler runs. No blockchain code needed in route handlers. Compatible with @x402/fetch, @x402/axios client SDKs and x402 Bazaar API discovery.",
+    text: "x402 examples — making a paid API is as simple as adding a route. FREE route: fastify.get('/api/data', async (req) => { return getData(); }). PAID route: fastify.get('/api/premium', { config: { x402: { price: '$0.01' } } }, async (req) => { return { data: 'premium', paid: req.x402?.amount }; }). CREDIT PURCHASE: fastify.post('/buy', { config: { x402: { variable: true, min: '$1', max: '$10000', priceField: 'dollars' } } }, async (req) => { const credits = parseFloat(req.x402.amount.replace('$','')) * 100; return { credits }; }). Frontend integration: sign EIP-3009 TransferWithAuthorization with eth_signTypedData_v4, build payload as { x402Version: 1, scheme: 'exact', network: 'base', payload: { authorization: {...}, signature } }, base64 encode, send as X-PAYMENT header. Values MUST be decimal strings ('1000000' for $1) NOT hex ('0xf4240'). validAfter = String(now - 600), validBefore = String(now + 300). The facilitator verifies signature then settles on-chain (calls transferWithAuthorization on USDC contract). Handler only runs after verification passes. Settlement happens after handler returns success (onSend hook). req.x402 = { paid: true, amount: '$5.00', from: '0x...', txHash, settled: true }.",
     metadata: { topic: "x402-examples" },
   },
+  {
+    text: "x402 troubleshooting — common issues and fixes. (1) 'Invalid network': using 'eip155:8453' instead of 'base' — the @coinbase/x402 v1 SDK uses human-readable network names. (2) 'Unauthorized' from facilitator: either wrong CDP_API_KEY_ID/SECRET, or a facilitator URL override in settings.json pointing to api.cdp.coinbase.com (remove it, let the built-in handle auth). (3) '400 Bad Request': payload format mismatch — ensure x402Version:1, scheme:'exact', network:'base'. Don't use exact.evm.decodePayment() on the server, parse the base64 JSON directly. (4) 'invalid_exact_evm_payload_signature': the EIP-712 signature is wrong — check that the frontend signs with the correct domain (name:'USD Coin', version:'2', chainId:8453, verifyingContract:USDC address). (5) USDC not moving: the old middleware only verified signatures without calling the facilitator settle — must use @coinbase/x402 facilitator which handles verify+settle. (6) Frontend value showing as hex (0xf4240): must use decimal strings. (7) SDK not loading: @coinbase/x402 + x402 are ESM packages, need Node 22+. On Node 18 they fail with ERR_REQUIRE_ESM. (8) Packages disappearing after --update: add @coinbase/x402, x402, viem to package.json dependencies so npm install preserves them.",
+    metadata: { topic: "x402-troubleshooting" },
+  },
   {
     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/middleware/x402-fastify.js

@@ -167,8 +167,10 @@ async function x402Plugin(fastify, opts) {
         return;
       }
     } catch (err) {
-      console.log(`  ⚠️ x402 verify error: ${err.message}`);
-      reply.code(402).send({ error: "Payment verification failed: " + err.message, accepts: [paymentRequirements] });
+      // Extract detailed error from the x402 SDK
+      const detail = err.invalidReason || err.invalidMessage || err.cause?.message || "";
+      console.log(`  ⚠️ x402 verify error: ${err.message} | ${detail}`);
+      reply.code(402).send({ error: err.invalidReason || err.message, message: err.invalidMessage || detail, accepts: [paymentRequirements] });
       return;
     }
 

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

@@ -5,9 +5,7 @@
     "env": "development"
   },
 
-  "_docs_models": "Each task wolverine performs uses a specific model role. You can mix providers freely — provider is auto-detected from the model name (claude-* → Anthropic, gpt-* → OpenAI). Using the same model across roles maximizes prompt cache hits and reduces cost. View per-role cost, speed, and token analytics on the wolverine dashboard at localhost:3001/analytics",
   "models": {
-    "_docs": "reasoning: deep error analysis & root cause diagnosis | coding: generates code fixes (fast path, no tools) | chat: summaries & brain compression | tool: agent tool-calling during complex heals | classifier: error type classification | audit: security & injection scanning | compacting: context window compression | research: deep investigation & web research",
     "reasoning": "claude-sonnet-4-6",
     "coding": "claude-sonnet-4-6",
     "chat": "claude-sonnet-4-6",
@@ -18,23 +16,19 @@
     "research": "claude-sonnet-4-6"
   },
 
-  "_docs_embedding": "Vector embedding model for the brain's memory system. Used to store and recall past fixes. text-embedding-3-small is the default (requires OPENAI_API_KEY). wolverine-embedding-1 routes through wolverine credits at 2x markup.",
   "embedding": "text-embedding-3-small",
 
-  "_docs_server": "port: server listen port (must be 3000 for wolverine) | maxRetries: consecutive crash restarts before giving up | maxMemoryMB: OOM threshold — process killed and healed if exceeded",
   "server": {
     "port": 3000,
     "maxRetries": 3,
     "maxMemoryMB": 512
   },
 
-  "_docs_telemetry": "Heartbeat reports server health (memory, CPU, routes, repair stats) to the dashboard every heartbeatIntervalMs. Disable if running fully offline.",
   "telemetry": {
     "enabled": true,
     "heartbeatIntervalMs": 60000
   },
 
-  "_docs_rateLimiting": "AI call budget to prevent runaway costs. maxCallsPerWindow: total AI calls allowed in windowMs. minGapMs: minimum delay between calls. maxTokensPerHour: hard token ceiling across all models.",
   "rateLimiting": {
     "maxCallsPerWindow": 32,
     "windowMs": 100000,
@@ -42,7 +36,6 @@
     "maxTokensPerHour": 1000000
   },
 
-  "_docs_healthCheck": "Probes server liveness. intervalMs: check frequency. timeoutMs: max wait for response. failThreshold: consecutive failures before triggering heal. startDelayMs: grace period after boot before first check.",
   "healthCheck": {
     "intervalMs": 15000,
     "timeoutMs": 5000,
@@ -50,14 +43,12 @@
     "startDelayMs": 10000
   },
 
-  "_docs_errorMonitor": "Tracks caught 500 errors per route. defaultThreshold: how many 500s on one route before triggering a heal. windowMs: error counting window. cooldownMs: minimum time between heals on the same route.",
   "errorMonitor": {
     "defaultThreshold": 1,
     "windowMs": 30000,
     "cooldownMs": 60000
   },
 
-  "_docs_autoUpdate": "Auto-updates wolverine framework from git. Only updates src/ and bin/ — never touches your server/ code. Checks every intervalMs.",
   "autoUpdate": {
     "enabled": false,
     "intervalMs": 300000
@@ -68,7 +59,6 @@
     "cors": ["http://localhost:3000"]
   },
 
-  "_docs_dashboard": "Dashboard serves on port+1 (default 3001). Configure WOLVERINE_ADMIN_KEY in .env.local for the agent command interface.",
   "dashboard": {},
 
   "cors": {