@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/attempt-journal.js

@@ -0,0 +1,380 @@
+/**
+ * Attempt Journal -- Per-task attempt log with diversity enforcement
+ *
+ * Tracks what was tried, what failed, and what was learned across retries.
+ * BLOCKS identical approaches from being retried. Forces agents to try
+ * something different or escalate.
+ *
+ * This module exists because of the "7-attempt hell" pattern where agents
+ * blindly retry the same failing approach without learning from failures.
+ *
+ * Merlin Framework -- Gestao Merlin v3.0.0
+ *
+ * @module core/execution/attempt-journal
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+
+/**
+ * Similarity threshold above which an approach is considered "same as before".
+ * 0.8 = 80% similar token overlap.
+ */
+const DEFAULT_SIMILARITY_THRESHOLD = 0.8;
+
+/**
+ * Maximum attempts before forced escalation.
+ */
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+class AttemptJournal {
+  /**
+   * @param {Object} [config]
+   * @param {number} [config.similarityThreshold=0.8] - Jaccard similarity threshold for blocking
+   * @param {number} [config.maxAttempts=3] - Max attempts before forced escalation
+   * @param {boolean} [config.debug=false]
+   */
+  constructor(config = {}) {
+    this.similarityThreshold =
+      config.similarityThreshold ?? DEFAULT_SIMILARITY_THRESHOLD;
+    this.maxAttempts = config.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    this.debug = config.debug ?? false;
+
+    /**
+     * Map of taskId -> Array of attempt records.
+     * @type {Map<string, Array<AttemptRecord>>}
+     */
+    this._journals = new Map();
+  }
+
+  /**
+   * Record a completed attempt (success or failure).
+   *
+   * @param {string} taskId - Unique task identifier
+   * @param {Object} attempt
+   * @param {string} attempt.approach - Description of what was tried
+   * @param {string} [attempt.error] - Error message if failed
+   * @param {string} [attempt.rootCause] - Diagnosed root cause
+   * @param {string} [attempt.learning] - What was learned from this attempt
+   * @param {boolean} [attempt.success=false] - Whether the attempt succeeded
+   * @param {Object} [attempt.context] - Additional context (tools used, files touched, etc.)
+   * @returns {Object} The recorded attempt with metadata
+   */
+  record(taskId, attempt) {
+    if (!this._journals.has(taskId)) {
+      this._journals.set(taskId, []);
+    }
+
+    const journal = this._journals.get(taskId);
+    const record = {
+      attemptNumber: journal.length + 1,
+      timestamp: new Date().toISOString(),
+      approach: attempt.approach || "",
+      approachHash: this._hashApproach(attempt.approach || ""),
+      error: attempt.error || null,
+      rootCause: attempt.rootCause || null,
+      learning: attempt.learning || null,
+      success: attempt.success || false,
+      context: attempt.context || {},
+    };
+
+    journal.push(record);
+
+    if (this.debug) {
+      console.log(
+        `[AttemptJournal] Task ${taskId}: recorded attempt #${record.attemptNumber}` +
+          ` (${record.success ? "SUCCESS" : "FAILED"})`,
+      );
+    }
+
+    return record;
+  }
+
+  /**
+   * Check whether a proposed approach should be allowed.
+   *
+   * Returns a verdict with:
+   * - `allowed`: boolean -- can the agent proceed?
+   * - `reason`: string -- why it was blocked (if blocked)
+   * - `similarAttempt`: object -- the previous attempt this is too similar to
+   * - `suggestions`: string[] -- what the agent should do instead
+   *
+   * @param {string} taskId - Task identifier
+   * @param {string} proposedApproach - Description of what the agent wants to try
+   * @returns {{allowed: boolean, reason: string, similarAttempt?: Object, suggestions: string[]}}
+   */
+  checkApproach(taskId, proposedApproach) {
+    const journal = this._journals.get(taskId) || [];
+    const failedAttempts = journal.filter((a) => !a.success);
+
+    // Check 1: Max attempts exceeded
+    if (failedAttempts.length >= this.maxAttempts) {
+      return {
+        allowed: false,
+        reason: `Max attempts (${this.maxAttempts}) exceeded for task ${taskId}. Must escalate to human.`,
+        suggestions: [
+          "Escalate to human with a summary of all failed attempts",
+          "Create a handoff document with root cause analysis",
+          `Failed approaches: ${failedAttempts.map((a) => a.approach).join("; ")}`,
+        ],
+      };
+    }
+
+    // Check 2: Approach too similar to a previous failure
+    for (const prev of failedAttempts) {
+      const similarity = this._calculateSimilarity(
+        proposedApproach,
+        prev.approach,
+      );
+
+      if (similarity >= this.similarityThreshold) {
+        const prevLearning = prev.learning
+          ? ` Learning from that attempt: "${prev.learning}"`
+          : "";
+        const prevRootCause = prev.rootCause
+          ? ` Root cause identified: "${prev.rootCause}"`
+          : "";
+
+        return {
+          allowed: false,
+          reason:
+            `Proposed approach is ${Math.round(similarity * 100)}% similar to failed attempt #${prev.attemptNumber}. ` +
+            `That attempt failed with: "${prev.error}".${prevRootCause}${prevLearning} ` +
+            `You MUST try a fundamentally different approach.`,
+          similarAttempt: prev,
+          suggestions: this._generateSuggestions(prev, failedAttempts),
+        };
+      }
+    }
+
+    // Check 3: Require different_approach explanation after first failure
+    if (failedAttempts.length > 0) {
+      return {
+        allowed: true,
+        reason: "Approach is sufficiently different from previous failures",
+        suggestions: [],
+        previousFailures: failedAttempts.map((a) => ({
+          attempt: a.attemptNumber,
+          approach: a.approach,
+          error: a.error,
+          rootCause: a.rootCause,
+        })),
+      };
+    }
+
+    return {
+      allowed: true,
+      reason: "First attempt -- no prior failures",
+      suggestions: [],
+    };
+  }
+
+  /**
+   * Get the full journal for a task.
+   *
+   * @param {string} taskId
+   * @returns {Array} Attempt records
+   */
+  getJournal(taskId) {
+    return [...(this._journals.get(taskId) || [])];
+  }
+
+  /**
+   * Get a summary suitable for injection into agent context.
+   *
+   * @param {string} taskId
+   * @returns {string} Markdown-formatted attempt history
+   */
+  getSummary(taskId) {
+    const journal = this._journals.get(taskId) || [];
+    if (journal.length === 0) return "";
+
+    const lines = [
+      "## Attempt Journal",
+      "",
+      `**Total attempts:** ${journal.length}`,
+      `**Failures:** ${journal.filter((a) => !a.success).length}`,
+      "",
+    ];
+
+    for (const attempt of journal) {
+      const status = attempt.success ? "SUCCESS" : "FAILED";
+      lines.push(`### Attempt #${attempt.attemptNumber} [${status}]`);
+      lines.push(`- **Approach:** ${attempt.approach}`);
+      if (attempt.error) lines.push(`- **Error:** ${attempt.error}`);
+      if (attempt.rootCause)
+        lines.push(`- **Root cause:** ${attempt.rootCause}`);
+      if (attempt.learning) lines.push(`- **Learning:** ${attempt.learning}`);
+      lines.push("");
+    }
+
+    lines.push(
+      "**RULE:** Your next approach MUST be fundamentally different from all failed approaches above.",
+    );
+    return lines.join("\n");
+  }
+
+  /**
+   * Check if a task has reached maximum attempts and must escalate.
+   *
+   * @param {string} taskId
+   * @returns {boolean}
+   */
+  mustEscalate(taskId) {
+    const journal = this._journals.get(taskId) || [];
+    const failures = journal.filter((a) => !a.success);
+    return failures.length >= this.maxAttempts;
+  }
+
+  /**
+   * Clear the journal for a task (e.g. after successful completion).
+   *
+   * @param {string} taskId
+   */
+  clear(taskId) {
+    this._journals.delete(taskId);
+  }
+
+  /**
+   * Clear all journals.
+   */
+  clearAll() {
+    this._journals.clear();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Hash an approach description for quick exact-match detection.
+   *
+   * @param {string} approach
+   * @returns {string} SHA-256 hash (first 16 chars)
+   * @private
+   */
+  _hashApproach(approach) {
+    const normalized = approach.toLowerCase().trim().replace(/\s+/g, " ");
+    return crypto
+      .createHash("sha256")
+      .update(normalized)
+      .digest("hex")
+      .slice(0, 16);
+  }
+
+  /**
+   * Calculate Jaccard similarity between two approach descriptions.
+   *
+   * Tokenizes both strings and computes intersection/union ratio.
+   * Returns 0.0 (completely different) to 1.0 (identical).
+   *
+   * @param {string} a
+   * @param {string} b
+   * @returns {number}
+   * @private
+   */
+  _calculateSimilarity(a, b) {
+    const tokensA = this._tokenize(a);
+    const tokensB = this._tokenize(b);
+
+    if (tokensA.size === 0 && tokensB.size === 0) return 1.0;
+    if (tokensA.size === 0 || tokensB.size === 0) return 0.0;
+
+    let intersection = 0;
+    for (const token of tokensA) {
+      if (tokensB.has(token)) intersection++;
+    }
+
+    const union = tokensA.size + tokensB.size - intersection;
+    return union === 0 ? 0.0 : intersection / union;
+  }
+
+  /**
+   * Tokenize an approach description into a Set of normalized tokens.
+   * Uses bigrams for better semantic matching.
+   *
+   * @param {string} text
+   * @returns {Set<string>}
+   * @private
+   */
+  _tokenize(text) {
+    const words = text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, " ")
+      .split(/\s+/)
+      .filter((w) => w.length > 2);
+
+    const tokens = new Set(words);
+
+    // Add bigrams for better semantic matching
+    for (let i = 0; i < words.length - 1; i++) {
+      tokens.add(`${words[i]}_${words[i + 1]}`);
+    }
+
+    return tokens;
+  }
+
+  /**
+   * Generate actionable suggestions based on previous failures.
+   *
+   * @param {Object} mostSimilar - The most similar previous failed attempt
+   * @param {Array} allFailures - All failed attempts
+   * @returns {string[]}
+   * @private
+   */
+  _generateSuggestions(mostSimilar, allFailures) {
+    const suggestions = [];
+
+    // Suggest based on error patterns
+    const error = (mostSimilar.error || "").toLowerCase();
+
+    if (
+      error.includes("enospc") ||
+      error.includes("disk") ||
+      error.includes("space")
+    ) {
+      suggestions.push(
+        "Try using a different drive/partition with more space",
+        "Clean up temporary files before retrying",
+        "Use a different output directory on a drive with space",
+      );
+    } else if (error.includes("enoent") || error.includes("not found")) {
+      suggestions.push(
+        "Verify the path exists before using it",
+        "Check for typos in file paths",
+        "Use absolute paths instead of relative paths",
+      );
+    } else if (error.includes("timeout") || error.includes("timed out")) {
+      suggestions.push(
+        "Try a different API or service endpoint",
+        "Break the operation into smaller chunks",
+        "Check if the service is actually running",
+      );
+    } else if (error.includes("permission") || error.includes("eacces")) {
+      suggestions.push(
+        "Check file/directory permissions",
+        "Try a different output location",
+        "Run with appropriate privileges",
+      );
+    } else {
+      suggestions.push(
+        "Diagnose the ROOT CAUSE before retrying",
+        "Try a completely different tool or method",
+        "Verify all preconditions before attempting",
+      );
+    }
+
+    // If multiple failures, suggest escalation
+    if (allFailures.length >= 2) {
+      suggestions.push(
+        `${allFailures.length} approaches have failed -- seriously consider escalating to human`,
+      );
+    }
+
+    return suggestions;
+  }
+}
+
+module.exports = { AttemptJournal };