wolverine-ai 2.9.0 → 3.0.0

package/README.md

@@ -358,11 +358,12 @@ High-performance vector database that grows without slowing down:
 
 **Search performance** (scales gracefully):
 
-| Entries | Semantic Search | Keyword (BM25) |
-|---------|----------------|----------------|
-| 100 | 0.2ms | 0.005ms |
-| 1,000 | 0.4ms | 0.01ms |
-| 10,000 | 4.4ms | 0.1ms |
+| Entries | Semantic Search | Keyword (BM25) | Clusters |
+|---------|----------------|----------------|----------|
+| 100 | 0.2ms | 0.005ms | 10 |
+| 1,000 | 0.4ms | 0.01ms | 32 |
+| 10,000 | 4.4ms | 0.1ms | 100 |
+| 50,000 | 23.7ms | 0.5ms | 224 |
 
 **4 optimization techniques:**
 1. **Pre-normalized vectors** — cosine similarity = dot product (no sqrt per query)
@@ -445,6 +446,25 @@ Three layers prevent token waste:
 
 ---
 
+## Agent Efficiency (claw-code patterns)
+
+| Technique | What it does | Cost |
+|-----------|-------------|------|
+| **Zero-cost compaction** | Extracts structural signals (tools, files, errors) from history — no LLM call | $0.00 |
+| **Token estimation** | `text.length / 4` approximation — fast budget checks without tokenizer | 0ms |
+| **Error-graceful tools** | Tool errors returned as `[ERROR]` results, not thrown — agent decides next step | More resilient |
+| **Pre/post tool hooks** | Shell commands in `.wolverine/hooks.json` — exit 0=allow, 2=deny | Extensible |
+
+**Hook configuration** (`.wolverine/hooks.json`):
+```json
+{
+  "pre_tool_use": ["bash -c 'if [ \"$HOOK_TOOL_NAME\" = \"bash_exec\" ]; then exit 2; fi'"],
+  "post_tool_use": ["bash -c 'echo \"Tool: $HOOK_TOOL_NAME\" >> /tmp/audit.log'"]
+}
+```
+
+---
+
 ## Cost Optimization
 
 Wolverine minimizes AI spend through 7 techniques:

package/package.json

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

package/src/agent/agent-engine.js

@@ -463,33 +463,24 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
 
       console.log(chalk.gray(`  🤖 Agent turn ${this.turnCount}/${this.maxTurns} (${this.totalTokens} tokens used)`));
 
-      // Compact context every 3 turns to prevent token blowup
-      // Turn 6 without compacting: ~95K tokens. With compacting: ~20K tokens.
-      if (this.turnCount > 1 && this.turnCount % 3 === 0 && this.messages.length > 4) {
-        try {
-          const { aiCall } = require("./ai-client") || require("../core/ai-client");
-          const { getModel: _gm } = require("./models") || require("../core/models");
-          const historyToCompact = this.messages.slice(1, -2); // keep system + last exchange
-          if (historyToCompact.length > 2) {
-            const historyText = historyToCompact.map(m => `${m.role}: ${(m.content || "").slice(0, 500)}`).join("\n");
-            const compactResult = await aiCall({
-              model: _gm("compacting"),
-              systemPrompt: "Summarize this agent conversation history into a concise status report. Keep: files read, changes made, errors found, what was tried. Remove: full file contents, redundant tool results.",
-              userPrompt: historyText.slice(0, 8000),
-              maxTokens: 512,
-              category: "brain",
-            });
-            if (compactResult.content) {
-              this.messages = [
-                this.messages[0], // system prompt
-                { role: "assistant", content: `[Prior work summary]\n${compactResult.content}` },
-                { role: "user", content: "Continue from where you left off." },
-                ...this.messages.slice(-2), // last exchange
-              ];
-              console.log(chalk.gray(`  📦 Compacted ${historyToCompact.length} messages → summary (${compactResult.content.length} chars)`));
-            }
-          }
-        } catch { /* compacting failed — continue with full context */ }
+      // Zero-cost structural compaction (claw-code pattern)
+      // Extracts signals from message history WITHOUT an LLM call.
+      // Preserves last 4 messages verbatim, summarizes older ones structurally.
+      // Triggers when estimated tokens > 10K (text.length / 4 approximation).
+      const estimatedTokens = this.messages.reduce((s, m) => s + _estimateTokens(m), 0);
+      if (this.messages.length > 6 && estimatedTokens > 10000) {
+        const preserveCount = 4; // keep system + last 3 exchanges
+        const toCompact = this.messages.slice(1, -preserveCount);
+        if (toCompact.length > 2) {
+          const summary = _structuralSummary(toCompact, this.filesRead, this.filesModified, this.toolCalls);
+          this.messages = [
+            this.messages[0], // system prompt
+            { role: "assistant", content: summary },
+            { role: "user", content: "Continue from where you left off." },
+            ...this.messages.slice(-preserveCount),
+          ];
+          console.log(chalk.gray(`  📦 Compacted ${toCompact.length} messages (${estimatedTokens} → ~${_estimateTokens({ content: summary })} tokens) — $0.00`));
+        }
       }
 
       let response;
@@ -533,11 +524,34 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
       }
 
       for (const toolCall of assistantMessage.tool_calls) {
-        const result = await this._executeTool(toolCall);
+        // Error-graceful tool execution (claw-code pattern)
+        // Tool errors are returned as is_error results, not thrown.
+        // This lets the model see the error and decide how to proceed.
+        let result;
+        let isError = false;
+        try {
+          // Pre-hook: check if tool should be blocked
+          const hookResult = _runPreHook(toolCall.function?.name, toolCall.function?.arguments, this.cwd);
+          if (hookResult.denied) {
+            result = { content: `Blocked by hook: ${hookResult.message}` };
+            isError = true;
+          } else {
+            result = await this._executeTool(toolCall);
+          }
+        } catch (err) {
+          // Error-graceful: return error as tool result, don't break the loop
+          result = { content: `Tool error: ${err.message?.slice(0, 200)}` };
+          isError = true;
+          console.log(chalk.yellow(`    ⚠️ Tool error (${toolCall.function?.name}): ${err.message?.slice(0, 80)}`));
+        }
+
+        // Post-hook: audit/modify result
+        _runPostHook(toolCall.function?.name, toolCall.function?.arguments, result.content, isError, this.cwd);
+
         this.messages.push({
           role: "tool",
           tool_call_id: toolCall.id,
-          content: result.content,
+          content: isError ? `[ERROR] ${result.content}` : result.content,
         });
 
         if (result.done) {
@@ -547,6 +561,7 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
             filesModified: result.filesModified || this.filesModified,
             turnCount: this.turnCount,
             totalTokens: this.totalTokens,
+            toolCalls: this.toolCalls,
           };
         }
       }
@@ -1090,4 +1105,130 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
   }
 }
 
+// ── Zero-Cost Compaction Helpers (claw-code pattern) ──
+
+/**
+ * Estimate tokens without a tokenizer. Fast approximation: text.length / 4 + 1.
+ * Good enough for budget decisions — off by ~10% which is fine.
+ */
+function _estimateTokens(message) {
+  if (!message) return 0;
+  const content = message.content || "";
+  const toolArgs = message.tool_calls?.reduce((s, tc) => s + (tc.function?.arguments?.length || 0), 0) || 0;
+  return Math.ceil((content.length + toolArgs) / 4) + 1;
+}
+
+/**
+ * Extract structural signals from message history WITHOUT an LLM call.
+ * Returns a concise summary preserving: tools used, files touched, errors found,
+ * what was tried, and pending work. Costs $0.00.
+ */
+function _structuralSummary(messages, filesRead, filesModified, toolCalls) {
+  const toolsUsed = new Set();
+  const filesReferenced = new Set();
+  const errors = [];
+  const userRequests = [];
+  const actions = [];
+
+  for (const msg of messages) {
+    if (msg.role === "user") {
+      const text = (msg.content || "").slice(0, 160);
+      if (text) userRequests.push(text);
+    }
+    if (msg.role === "assistant" && msg.tool_calls) {
+      for (const tc of msg.tool_calls) {
+        toolsUsed.add(tc.function?.name);
+        // Extract file paths from tool args
+        try {
+          const args = JSON.parse(tc.function?.arguments || "{}");
+          if (args.path) filesReferenced.add(args.path);
+          if (args.pattern) filesReferenced.add(args.pattern);
+        } catch {}
+      }
+    }
+    if (msg.role === "tool") {
+      const content = msg.content || "";
+      if (content.startsWith("[ERROR]") || content.includes("Error:")) {
+        errors.push(content.slice(0, 100));
+      }
+      // Extract file paths from tool results
+      const pathMatches = content.match(/(?:server|src)\/[^\s"']+/g);
+      if (pathMatches) pathMatches.forEach(p => filesReferenced.add(p));
+    }
+    if (msg.role === "assistant" && msg.content) {
+      const text = msg.content.slice(0, 100);
+      if (text && !text.startsWith("[")) actions.push(text);
+    }
+  }
+
+  const lines = [
+    "[Compacted conversation summary — $0.00, no LLM call]",
+    `Messages compacted: ${messages.length}`,
+    `Tools used: ${[...toolsUsed].join(", ") || "none"}`,
+    `Files read: ${[...filesRead].slice(0, 10).join(", ") || "none"}`,
+    `Files modified: ${[...filesModified].join(", ") || "none"}`,
+    `Files referenced: ${[...filesReferenced].slice(0, 10).join(", ") || "none"}`,
+    errors.length > 0 ? `Errors encountered: ${errors.slice(0, 3).join("; ")}` : null,
+    userRequests.length > 0 ? `User requests: ${userRequests.slice(-2).join(" | ")}` : null,
+    actions.length > 0 ? `Actions taken: ${actions.slice(-3).join(" | ")}` : null,
+  ].filter(Boolean);
+
+  return lines.join("\n");
+}
+
+// ── Pre/Post Tool Hooks (claw-code pattern) ──
+
+/**
+ * Pre-tool hook: check if tool execution should be blocked.
+ * Reads hooks from .wolverine/hooks.json if it exists.
+ * Exit code 0 = allow, 2 = deny.
+ */
+function _runPreHook(toolName, toolInput, cwd) {
+  try {
+    const hooksPath = path.join(cwd, ".wolverine", "hooks.json");
+    if (!fs.existsSync(hooksPath)) return { denied: false };
+    const hooks = JSON.parse(fs.readFileSync(hooksPath, "utf-8"));
+    if (!hooks.pre_tool_use || hooks.pre_tool_use.length === 0) return { denied: false };
+
+    for (const cmd of hooks.pre_tool_use) {
+      try {
+        const { execSync } = require("child_process");
+        execSync(cmd, {
+          input: JSON.stringify({ event: "PreToolUse", tool_name: toolName, tool_input: toolInput }),
+          env: { ...process.env, HOOK_TOOL_NAME: toolName || "", HOOK_TOOL_INPUT: (toolInput || "").slice(0, 1000) },
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 5000,
+        });
+      } catch (e) {
+        if (e.status === 2) return { denied: true, message: (e.stdout?.toString() || "Hook denied").trim() };
+      }
+    }
+  } catch {}
+  return { denied: false };
+}
+
+/**
+ * Post-tool hook: audit/log tool execution.
+ */
+function _runPostHook(toolName, toolInput, toolOutput, isError, cwd) {
+  try {
+    const hooksPath = path.join(cwd, ".wolverine", "hooks.json");
+    if (!fs.existsSync(hooksPath)) return;
+    const hooks = JSON.parse(fs.readFileSync(hooksPath, "utf-8"));
+    if (!hooks.post_tool_use || hooks.post_tool_use.length === 0) return;
+
+    for (const cmd of hooks.post_tool_use) {
+      try {
+        const { execSync } = require("child_process");
+        execSync(cmd, {
+          input: JSON.stringify({ event: "PostToolUse", tool_name: toolName, tool_input: toolInput, tool_output: (toolOutput || "").slice(0, 500), is_error: isError }),
+          env: { ...process.env, HOOK_TOOL_NAME: toolName || "", HOOK_TOOL_IS_ERROR: isError ? "1" : "0" },
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 5000,
+        });
+      } catch {}
+    }
+  } catch {}
+}
+
 module.exports = { AgentEngine, TOOL_DEFINITIONS, BLOCKED_COMMANDS };

package/src/brain/brain.js

@@ -54,7 +54,7 @@ const SEED_DOCS = [
     metadata: { topic: "perf-monitoring" },
   },
   {
-    text: "Wolverine brain: high-performance vector database for long-term memory. 4 search optimizations: (1) Pre-normalized vectors — cosine similarity = dot product (no sqrt), 7x faster. (2) IVF index — vectors clustered into √N buckets via k-means++, search probes nearest 20% of clusters only. 10K entries: 4ms instead of 31ms. (3) BM25 keyword search — proper inverted index with TF-IDF scoring, O(query_tokens) not O(N). (4) Binary persistence — Float32Array buffers, 10x faster load than JSON. Grows gracefully: 100=0.2ms, 1K=0.4ms, 5K=2ms, 10K=4ms. Stores: function maps, errors, fixes, learnings, seed docs. Persisted to .wolverine/brain/.",
+    text: "Wolverine brain: high-performance vector database for long-term memory. 4 search optimizations: (1) Pre-normalized vectors — cosine similarity = dot product (no sqrt), 7x faster. (2) IVF index — k-means++ clustering into √N buckets (10 at 100 entries, 100 at 10K, 224 at 50K), search probes nearest 20% of clusters. (3) BM25 keyword search — inverted index with TF-IDF scoring, O(query_tokens) not O(N). (4) Binary persistence — Float32Array buffers, 10x faster load. Benchmarks: 100=0.2ms, 1K=0.4ms, 5K=2ms, 10K=4.4ms, 50K=23.7ms (was 160ms brute force). Stores: function maps, errors, fixes, learnings, seed docs. New seeds merged on framework update without erasing existing memories.",
     metadata: { topic: "brain" },
   },
   {
@@ -257,6 +257,10 @@ const SEED_DOCS = [
     text: "Token waste prevention: 3 layers. (1) Empty stderr guard — signal kills with no error output just restart, no AI ($0.00). (2) Loop guard — 3 failed heals on same error → stop and file bug report, no more AI calls. (3) Global rate limit — max 5 heals per 5 minutes regardless of error signature. Idle server burns exactly $0.00 in tokens.",
     metadata: { topic: "token-protection" },
   },
+  {
+    text: "Agent efficiency (claw-code patterns): (1) Zero-cost structural compaction — extracts signals (tools used, files touched, errors found, actions taken) from message history WITHOUT an LLM call. Costs $0.00 vs old method that burned tokens on a compacting model. Triggers when estimated tokens > 10K (text.length/4 approximation). Preserves last 4 messages verbatim. (2) Token estimation — text.length/4+1, fast approximation without tokenizer, ~10% accurate. Used for budget decisions before API calls. (3) Error-graceful tools — tool errors returned as [ERROR] prefixed results, not thrown. Model sees the error and decides how to proceed. (4) Pre/post tool hooks — shell commands in .wolverine/hooks.json, exit 0=allow, 2=deny. Enables audit logging and policy enforcement without hard-coding.",
+    metadata: { topic: "agent-efficiency" },
+  },
   {
     text: "Cost optimization: 7 techniques reduce heal cost from $0.31 to $0.02 for simple errors. (1) Verifier skips route probe for simple errors (TypeError/ReferenceError/SyntaxError) — trusts syntax+boot, ErrorMonitor is safety net. Prevents false-rejection cascades. (2) Sub-agents use Haiku (classifier model) for explore/plan/verify/research — only fixer uses Sonnet/Opus. 6 Haiku calls=$0.006 vs 6 Sonnet calls=$0.12. (3) Agent context compacted every 3 turns using compacting model — prevents 15K→95K token blowup. (4) Brain checked for cached fix patterns before AI — repeat errors cost $0. (5) Token budgets capped by error complexity: simple=20K agent budget, moderate=50K, complex=100K. Simple errors get 4 agent turns max. (6) Prior attempt summaries (not full context) passed between iterations — concise 'do NOT repeat' directives. (7) Fast path includes last known good backup code so AI can revert broken additions instead of patching around them.",
     metadata: { topic: "cost-optimization" },