@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/alkimia/memory/session-analyzer.js

@@ -0,0 +1,400 @@
+/**
+ * Session Analyzer — Meta-agent intelligence module
+ *
+ * Analyzes past sessions from .ai/ debug logs to identify patterns,
+ * recurring failures, skill gaps, and potential learnings. Powers
+ * the Meta-agent (Mira) self-improvement loop.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/alkimia/memory/session-analyzer
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs").promises;
+const fsSync = require("fs");
+const path = require("path");
+
+/**
+ * Pattern types detected in session analysis.
+ * @enum {string}
+ */
+const PatternType = {
+  REPETITIVE_FAILURE: "repetitive-failure",
+  SKILL_GAP: "skill-gap",
+  WORKFLOW_BOTTLENECK: "workflow-bottleneck",
+  UNCAPTURED_LEARNING: "uncaptured-learning",
+  RECURRING_TASK: "recurring-task",
+};
+
+/**
+ * SessionAnalyzer — Analyzes debug logs and session data for patterns.
+ */
+class SessionAnalyzer {
+  /**
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} [options]
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.logsDir = path.join(projectRoot, ".ai");
+    this.thoughtsDir = path.join(
+      projectRoot,
+      ".merlin-core",
+      "thoughts",
+      "shared",
+    );
+    this.options = { debug: false, ...options };
+  }
+
+  /**
+   * Analyze recent sessions for patterns.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.days=7] - How many days back to scan
+   * @param {number} [options.minOccurrences=3] - Minimum occurrences to flag
+   * @returns {Promise<{patterns: Array<{type: string, description: string, frequency: number, examples: string[]}>}>}
+   */
+  async analyzeRecentSessions(options = {}) {
+    const days = options.days || 7;
+    const minOccurrences = options.minOccurrences || 3;
+    const patterns = [];
+
+    const logs = await this._getRecentLogs(days);
+    if (logs.length === 0) {
+      return {
+        patterns: [],
+        summary: "No session logs found in .ai/ directory",
+      };
+    }
+
+    // Analyze error patterns
+    const errors = this._extractErrorPatterns(logs);
+    for (const [pattern, data] of Object.entries(errors)) {
+      if (data.count >= minOccurrences) {
+        patterns.push({
+          type: PatternType.REPETITIVE_FAILURE,
+          description: pattern,
+          frequency: data.count,
+          examples: data.examples.slice(0, 3),
+        });
+      }
+    }
+
+    // Analyze task patterns
+    const tasks = this._extractTaskPatterns(logs);
+    for (const [pattern, data] of Object.entries(tasks)) {
+      if (data.count >= minOccurrences) {
+        patterns.push({
+          type: PatternType.RECURRING_TASK,
+          description: pattern,
+          frequency: data.count,
+          examples: data.examples.slice(0, 3),
+        });
+      }
+    }
+
+    return {
+      patterns,
+      summary: `Analyzed ${logs.length} log files from last ${days} days. Found ${patterns.length} patterns.`,
+    };
+  }
+
+  /**
+   * Identify recurring error patterns that suggest systemic issues.
+   *
+   * @returns {Promise<{failures: Array<{pattern: string, count: number, suggestion: string}>}>}
+   */
+  async identifyRepetitiveFailures() {
+    const logs = await this._getRecentLogs(14); // 2 weeks lookback
+    const failures = [];
+
+    const errors = this._extractErrorPatterns(logs);
+    for (const [pattern, data] of Object.entries(errors)) {
+      if (data.count >= 2) {
+        failures.push({
+          pattern,
+          count: data.count,
+          suggestion: this._suggestFix(pattern),
+          firstSeen: data.firstSeen,
+          lastSeen: data.lastSeen,
+        });
+      }
+    }
+
+    // Sort by frequency
+    failures.sort((a, b) => b.count - a.count);
+
+    return { failures };
+  }
+
+  /**
+   * Identify domains where agents lacked guidance (skill gaps).
+   *
+   * Looks for: escalations, user corrections, repeated clarification requests.
+   *
+   * @returns {Promise<{gaps: Array<{domain: string, description: string, suggestedSkill: string}>}>}
+   */
+  async identifySkillGaps() {
+    const logs = await this._getRecentLogs(14);
+    const gaps = [];
+    const gapIndicators = {};
+
+    for (const log of logs) {
+      // Look for escalation patterns
+      const escalations = log.content.match(/\[ASK:.*?\]|\[escalat/gi);
+      if (escalations) {
+        for (const esc of escalations) {
+          const key = esc.substring(0, 50).toLowerCase();
+          gapIndicators[key] = (gapIndicators[key] || 0) + 1;
+        }
+      }
+
+      // Look for "I don't know" or uncertainty patterns
+      const uncertainty = log.content.match(
+        /(?:not sure|unclear|need guidance|no documentation|can't determine)/gi,
+      );
+      if (uncertainty) {
+        for (const u of uncertainty) {
+          const key = u.toLowerCase();
+          gapIndicators[key] = (gapIndicators[key] || 0) + 1;
+        }
+      }
+    }
+
+    for (const [indicator, count] of Object.entries(gapIndicators)) {
+      if (count >= 2) {
+        gaps.push({
+          domain: indicator,
+          description: `Detected ${count} instances of uncertainty/escalation: "${indicator}"`,
+          suggestedSkill: `Consider creating a skill for: ${indicator}`,
+        });
+      }
+    }
+
+    return { gaps };
+  }
+
+  /**
+   * Extract potential learnings not yet captured.
+   *
+   * Compares session outcomes with existing learnings.
+   *
+   * @returns {Promise<{suggestions: Array<{title: string, content: string, confidence: number}>}>}
+   */
+  async suggestLearnings() {
+    const logs = await this._getRecentLogs(7);
+    const learningsDir = path.join(this.thoughtsDir, "learnings");
+    const suggestions = [];
+
+    // Load existing learnings for dedup
+    const existingLearnings = new Set();
+    try {
+      const entries = await fs.readdir(learningsDir);
+      for (const entry of entries) {
+        if (entry.endsWith(".md")) {
+          const content = await fs.readFile(
+            path.join(learningsDir, entry),
+            "utf8",
+          );
+          // Extract title
+          const titleMatch = content.match(/^#\s+(.+)$/m);
+          if (titleMatch) existingLearnings.add(titleMatch[1].toLowerCase());
+        }
+      }
+    } catch {
+      // Learnings dir may not exist
+    }
+
+    // Look for learning signals in logs
+    const learningPatterns = [
+      { re: /turns out[^.]*\./gi, label: "discovery" },
+      {
+        re: /the (?:root cause|real issue|actual problem) (?:was|is)[^.]*\./gi,
+        label: "root-cause",
+      },
+      { re: /workaround:?[^.]*\./gi, label: "workaround" },
+      { re: /gotcha:?[^.]*\./gi, label: "gotcha" },
+    ];
+
+    for (const log of logs) {
+      for (const { re, label } of learningPatterns) {
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(log.content)) !== null) {
+          const excerpt = match[0].trim();
+          const title = `${label}: ${excerpt.substring(0, 60)}`;
+
+          // Skip if already captured
+          if (existingLearnings.has(title.toLowerCase())) continue;
+
+          suggestions.push({
+            title,
+            content: excerpt,
+            confidence: 0.6,
+            source: log.file,
+          });
+        }
+      }
+    }
+
+    // Deduplicate by title
+    const seen = new Set();
+    const unique = suggestions.filter((s) => {
+      if (seen.has(s.title)) return false;
+      seen.add(s.title);
+      return true;
+    });
+
+    return { suggestions: unique.slice(0, 10) };
+  }
+
+  /**
+   * Get recent log files from .ai/ directory.
+   *
+   * @param {number} days - Days to look back
+   * @returns {Promise<Array<{file: string, content: string, mtime: Date}>>}
+   * @private
+   */
+  async _getRecentLogs(days) {
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+
+    try {
+      if (!fsSync.existsSync(this.logsDir)) return [];
+
+      const entries = await fs.readdir(this.logsDir, { withFileTypes: true });
+      const logs = [];
+
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        if (!entry.name.endsWith(".log") && !entry.name.endsWith(".jsonl"))
+          continue;
+
+        const filePath = path.join(this.logsDir, entry.name);
+        const stat = await fs.stat(filePath);
+
+        if (stat.mtimeMs < cutoff) continue;
+
+        try {
+          const content = await fs.readFile(filePath, "utf8");
+          // Limit to first 50KB per file to avoid memory issues
+          logs.push({
+            file: entry.name,
+            content: content.substring(0, 50000),
+            mtime: stat.mtime,
+          });
+        } catch {
+          // Skip unreadable files
+        }
+      }
+
+      return logs.sort((a, b) => b.mtime - a.mtime);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Extract error patterns from log content.
+   *
+   * @param {Array} logs - Log entries
+   * @returns {Object} Error pattern → {count, examples, firstSeen, lastSeen}
+   * @private
+   */
+  _extractErrorPatterns(logs) {
+    const errors = {};
+    const errorRe =
+      /(?:error|failed|exception|ENOENT|EPERM|TypeError|ReferenceError)[:]\s*[^\n]{10,80}/gi;
+
+    for (const log of logs) {
+      errorRe.lastIndex = 0;
+      let match;
+      while ((match = errorRe.exec(log.content)) !== null) {
+        // Normalize error (remove timestamps, hashes, line numbers)
+        const normalized = match[0]
+          .replace(/\d{4}-\d{2}-\d{2}T[\d:.Z]+/g, "<timestamp>")
+          .replace(/\b[0-9a-f]{6,}\b/g, "<hash>")
+          .replace(/:\d+:\d+/g, ":<line>")
+          .trim();
+
+        if (!errors[normalized]) {
+          errors[normalized] = {
+            count: 0,
+            examples: [],
+            firstSeen: log.mtime,
+            lastSeen: log.mtime,
+          };
+        }
+        errors[normalized].count++;
+        if (errors[normalized].examples.length < 5) {
+          errors[normalized].examples.push(match[0].trim());
+        }
+        // M3 fix: logs sorted newest-first; track both min and max timestamps
+        if (log.mtime < errors[normalized].firstSeen) {
+          errors[normalized].firstSeen = log.mtime;
+        }
+        if (log.mtime > errors[normalized].lastSeen) {
+          errors[normalized].lastSeen = log.mtime;
+        }
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Extract task patterns from log content.
+   *
+   * @param {Array} logs - Log entries
+   * @returns {Object} Task pattern → {count, examples}
+   * @private
+   */
+  _extractTaskPatterns(logs) {
+    const tasks = {};
+    const taskRe = /\[TASK:\s*([^\]]+)\]/gi;
+
+    for (const log of logs) {
+      taskRe.lastIndex = 0;
+      let match;
+      while ((match = taskRe.exec(log.content)) !== null) {
+        const normalized = match[1].trim().toLowerCase();
+        if (!tasks[normalized]) {
+          tasks[normalized] = { count: 0, examples: [] };
+        }
+        tasks[normalized].count++;
+        if (tasks[normalized].examples.length < 3) {
+          tasks[normalized].examples.push(match[1].trim());
+        }
+      }
+    }
+
+    return tasks;
+  }
+
+  /**
+   * Suggest a fix for a known error pattern.
+   *
+   * @param {string} pattern - Error pattern
+   * @returns {string} Suggested fix
+   * @private
+   */
+  _suggestFix(pattern) {
+    const lower = pattern.toLowerCase();
+    if (lower.includes("enoent"))
+      return "File not found — verify path or create missing file";
+    if (lower.includes("eperm"))
+      return "Permission denied — check file permissions";
+    if (lower.includes("typeerror"))
+      return "Type mismatch — add input validation";
+    if (lower.includes("timeout"))
+      return "Operation too slow — increase timeout or optimize";
+    if (lower.includes("referenceerror"))
+      return "Undefined variable — check imports and scope";
+    return "Investigate root cause and create a learning if resolved";
+  }
+}
+
+module.exports = { SessionAnalyzer, PatternType };