atabey 0.0.13 → 0.0.14

package/framework-mcp/dist/framework-mcp/src/utils/loop-detector.js

@@ -0,0 +1,361 @@
+/**
+ * ─── LOOP DETECTOR ─────────────────────────────────────────────────
+ *
+ * Detects and prevents AI agents from entering infinite loops.
+ * Monitors call patterns across time, file paths, and tools.
+ *
+ * Detection Patterns:
+ * 1. **Consecutive Same Tool** – Same tool called N times in a row
+ * 2. **File Churn** – Same file written/read repeatedly
+ * 3. **Oscillation** – A → B → A → B alternating pattern
+ * 4. **Time-based Throttle** – Too many calls in a short window
+ * 5. **Semantic Similarity** – Similar arguments repeated (e.g., same error fix loop)
+ * 6. **Content Identity** – Same content being written repeatedly
+ *
+ * Action:
+ * - Cooldown: Block agent for N seconds
+ * - Escalate: Notify dashboard/human if loop persists
+ * - Kill: Force-stop the agent session
+ *
+ * Environment Variables:
+ *   MCP_LOOP_MAX_CONSECUTIVE   - Max same tool calls (default: 10)
+ *   MCP_LOOP_MAX_FILE_CHURN     - Max writes to same file (default: 5)
+ *   MCP_LOOP_COOLDOWN_MS        - Cooldown duration (default: 30000)
+ *   MCP_LOOP_OSCILLATION_WINDOW - Oscillation detection window (default: 6)
+ */
+import path from "path";
+// ─── Configuration ────────────────────────────────────────────────
+const CONFIG = {
+    /** Max consecutive same tool calls before action */
+    MAX_CONSECUTIVE: parseInt(process.env.MCP_LOOP_MAX_CONSECUTIVE || "10", 10),
+    /** Max writes to the same file before action */
+    MAX_FILE_CHURN: parseInt(process.env.MCP_LOOP_MAX_FILE_CHURN || "5", 10),
+    /** Max reads of the same file before action */
+    MAX_FILE_READ_CHURN: parseInt(process.env.MCP_LOOP_MAX_FILE_READ_CHURN || "10", 10),
+    /** Oscillation pattern window (min calls to detect A→B→A→B) */
+    OSCILLATION_WINDOW: parseInt(process.env.MCP_LOOP_OSCILLATION_WINDOW || "6", 10),
+    /** Cooldown duration in ms */
+    COOLDOWN_MS: parseInt(process.env.MCP_LOOP_COOLDOWN_MS || "30000", 10),
+    /** Max calls to any tool in sliding window */
+    MAX_CALLS_IN_WINDOW: parseInt(process.env.MCP_LOOP_MAX_CALLS_IN_WINDOW || "50", 10),
+    /** Sliding window size in ms */
+    WINDOW_SIZE_MS: parseInt(process.env.MCP_LOOP_WINDOW_MS || "60000", 10),
+    /** Enable/disable loop detector */
+    ENABLED: process.env.MCP_LOOP_DETECTION !== "false",
+};
+const agentHistories = new Map();
+// ─── Loop Detector ────────────────────────────────────────────────
+/**
+ * Get or create agent history.
+ */
+function getOrCreateHistory(agent) {
+    if (!agentHistories.has(agent)) {
+        agentHistories.set(agent, {
+            calls: [],
+            consecutiveToolCalls: new Map(),
+            fileWriteCount: new Map(),
+            fileReadCount: new Map(),
+            lastContentHashes: [],
+            inCooldown: false,
+            cooldownUntil: 0,
+            cooldownCount: 0,
+            lastAlert: null,
+        });
+    }
+    return agentHistories.get(agent);
+}
+/**
+ * Prune old calls from history.
+ */
+function pruneOldCalls(history) {
+    const cutoff = Date.now() - CONFIG.WINDOW_SIZE_MS;
+    history.calls = history.calls.filter(c => c.timestamp > cutoff);
+}
+/**
+ * Extract file path from tool args if applicable.
+ */
+function extractFilePath(toolName, args) {
+    if (["write_file", "read_file", "replace_text", "patch_file", "batch_surgical_edit"].includes(toolName)) {
+        return args.path || args.filePath || undefined;
+    }
+    return undefined;
+}
+/**
+ * Compute a simple content hash for identity detection.
+ */
+function computeContentHash(args) {
+    if (args.content && typeof args.content === "string") {
+        // Use first 100 chars as hash (fast, good enough for identity)
+        return args.content.substring(0, 100);
+    }
+    return undefined;
+}
+/**
+ * Check for oscillation pattern (A → B → A → B).
+ */
+function detectOscillation(history, currentTool) {
+    const recent = history.calls.slice(-CONFIG.OSCILLATION_WINDOW);
+    if (recent.length < 4)
+        return false;
+    const recentToolNames = [...recent.map(c => c.toolName), currentTool];
+    // Check alternating pattern: tool[0] === tool[2] === tool[4] && tool[1] === tool[3] === tool[5]
+    if (recentToolNames.length >= 4) {
+        if (recentToolNames[0] === recentToolNames[2] &&
+            recentToolNames[1] === recentToolNames[3] &&
+            recentToolNames[0] !== recentToolNames[1]) {
+            // Check if pattern extends to 6
+            if (recentToolNames.length >= 6) {
+                return recentToolNames[0] === recentToolNames[4] && recentToolNames[1] === recentToolNames[5];
+            }
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Detect if same content is being written repeatedly.
+ */
+function detectContentIdentity(history, contentHash) {
+    if (!contentHash)
+        return false;
+    const recentHashes = history.lastContentHashes.slice(-5);
+    if (recentHashes.length < 3)
+        return false;
+    // Check if this hash appears 3+ times in last 5
+    const hashCount = recentHashes.filter(h => h === contentHash).length;
+    if (contentHash === recentHashes[recentHashes.length - 1]) {
+        // Count including current
+        return hashCount + 1 >= 3;
+    }
+    return false;
+}
+/**
+ * Record a tool call and check for loop patterns.
+ * Returns LoopAlert if a loop pattern is detected, null otherwise.
+ */
+export function recordAndCheck(agent, toolName, args) {
+    if (!CONFIG.ENABLED)
+        return null;
+    const history = getOrCreateHistory(agent);
+    // Check cooldown
+    if (history.inCooldown) {
+        if (Date.now() < history.cooldownUntil) {
+            return {
+                type: "rate_limit",
+                severity: "critical",
+                agent,
+                detail: `Agent "${agent}" is in cooldown for ${Math.ceil((history.cooldownUntil - Date.now()) / 1000)}s. Loop detected earlier.`,
+                timestamp: Date.now(),
+                cooldownUntil: history.cooldownUntil,
+            };
+        }
+        else {
+            history.inCooldown = false;
+        }
+    }
+    const filePath = extractFilePath(toolName, args);
+    const contentHash = computeContentHash(args);
+    const record = {
+        agent,
+        toolName,
+        args,
+        timestamp: Date.now(),
+        filePath,
+        contentHash,
+    };
+    // Prune old calls
+    pruneOldCalls(history);
+    // Check 1: Consecutive same tool
+    const currentConsecutive = (history.consecutiveToolCalls.get(toolName) || 0) + 1;
+    history.consecutiveToolCalls.set(toolName, currentConsecutive);
+    // Reset other tools
+    for (const [tool] of history.consecutiveToolCalls) {
+        if (tool !== toolName) {
+            history.consecutiveToolCalls.set(tool, 0);
+        }
+    }
+    if (currentConsecutive >= CONFIG.MAX_CONSECUTIVE) {
+        const alert = {
+            type: "consecutive_same_tool",
+            severity: "critical",
+            agent,
+            detail: `Agent "${agent}" called "${toolName}" ${currentConsecutive} times consecutively. Possible infinite loop.`,
+            timestamp: Date.now(),
+            cooldownUntil: Date.now() + CONFIG.COOLDOWN_MS,
+        };
+        applyCooldown(history, alert, agent);
+        return alert;
+    }
+    // Check 2: File churn (for write operations)
+    if (filePath) {
+        if (["write_file", "replace_text", "patch_file", "batch_surgical_edit"].includes(toolName)) {
+            const writeCount = (history.fileWriteCount.get(filePath) || 0) + 1;
+            history.fileWriteCount.set(filePath, writeCount);
+            if (writeCount >= CONFIG.MAX_FILE_CHURN) {
+                const alert = {
+                    type: "file_churn",
+                    severity: "critical",
+                    agent,
+                    detail: `Agent "${agent}" wrote to "${path.relative(process.cwd(), filePath)}" ${writeCount} times. Possible file churn loop.`,
+                    timestamp: Date.now(),
+                    cooldownUntil: Date.now() + CONFIG.COOLDOWN_MS,
+                };
+                applyCooldown(history, alert, agent);
+                return alert;
+            }
+        }
+        if (toolName === "read_file") {
+            const readCount = (history.fileReadCount.get(filePath) || 0) + 1;
+            history.fileReadCount.set(filePath, readCount);
+            if (readCount >= CONFIG.MAX_FILE_READ_CHURN) {
+                const alert = {
+                    type: "file_churn",
+                    severity: "warning",
+                    agent,
+                    detail: `Agent "${agent}" read "${path.relative(process.cwd(), filePath)}" ${readCount} times. Possible read loop.`,
+                    timestamp: Date.now(),
+                    cooldownUntil: null,
+                };
+                history.lastAlert = alert;
+                return alert;
+            }
+        }
+    }
+    // Check 3: Oscillation pattern
+    if (detectOscillation(history, toolName)) {
+        const alert = {
+            type: "oscillation",
+            severity: "critical",
+            agent,
+            detail: `Agent "${agent}" is oscillating between tools. Pattern detected in last ${CONFIG.OSCILLATION_WINDOW} calls.`,
+            timestamp: Date.now(),
+            cooldownUntil: Date.now() + CONFIG.COOLDOWN_MS,
+        };
+        applyCooldown(history, alert, agent);
+        return alert;
+    }
+    // Check 4: Rate limit (calls in sliding window)
+    if (history.calls.length >= CONFIG.MAX_CALLS_IN_WINDOW) {
+        const alert = {
+            type: "rate_limit",
+            severity: "critical",
+            agent,
+            detail: `Agent "${agent}" made ${history.calls.length} calls in ${CONFIG.WINDOW_SIZE_MS / 1000}s window. Rate limit exceeded.`,
+            timestamp: Date.now(),
+            cooldownUntil: Date.now() + CONFIG.COOLDOWN_MS,
+        };
+        applyCooldown(history, alert, agent);
+        return alert;
+    }
+    // Check 5: Content identity (writing same content)
+    if (contentHash && detectContentIdentity(history, contentHash)) {
+        const alert = {
+            type: "content_identity",
+            severity: "critical",
+            agent,
+            detail: `Agent "${agent}" is writing the same content repeatedly. Possible fix-attempt loop.`,
+            timestamp: Date.now(),
+            cooldownUntil: Date.now() + CONFIG.COOLDOWN_MS,
+        };
+        applyCooldown(history, alert, agent);
+        return alert;
+    }
+    // If no detection, record the call
+    history.calls.push(record);
+    // Track content hashes for identity detection
+    if (contentHash) {
+        history.lastContentHashes.push(contentHash);
+        if (history.lastContentHashes.length > 10) {
+            history.lastContentHashes.shift();
+        }
+    }
+    return null;
+}
+/**
+ * Apply cooldown to an agent.
+ */
+function applyCooldown(history, alert, agent) {
+    history.inCooldown = true;
+    history.cooldownUntil = alert.cooldownUntil || Date.now() + CONFIG.COOLDOWN_MS;
+    history.cooldownCount++;
+    history.lastAlert = alert;
+    process.stderr.write(`[LOOP DETECT] ${alert.type}: ${alert.detail}\n`);
+}
+/**
+ * Check if an agent is currently in cooldown.
+ */
+export function isInCooldown(agent) {
+    const history = agentHistories.get(agent);
+    if (!history || !history.inCooldown) {
+        return { inCooldown: false, remainingMs: 0, reason: null };
+    }
+    const remaining = history.cooldownUntil - Date.now();
+    if (remaining <= 0) {
+        history.inCooldown = false;
+        return { inCooldown: false, remainingMs: 0, reason: null };
+    }
+    return {
+        inCooldown: true,
+        remainingMs: remaining,
+        reason: history.lastAlert?.detail || null,
+    };
+}
+/**
+ * Manually clear cooldown for an agent.
+ */
+export function clearCooldown(agent) {
+    const history = agentHistories.get(agent);
+    if (history) {
+        history.inCooldown = false;
+        history.cooldownUntil = 0;
+        history.consecutiveToolCalls.clear();
+        return true;
+    }
+    return false;
+}
+/**
+ * Get loop detection stats for an agent.
+ */
+export function getLoopStats(agent) {
+    const history = agentHistories.get(agent);
+    if (!history) {
+        return {
+            totalCalls: 0,
+            recentCalls: 0,
+            inCooldown: false,
+            cooldownCount: 0,
+            consecutiveTools: {},
+            fileWrites: {},
+            fileReads: {},
+            lastAlert: null,
+        };
+    }
+    pruneOldCalls(history);
+    return {
+        totalCalls: history.calls.length + history.cooldownCount * CONFIG.MAX_CALLS_IN_WINDOW,
+        recentCalls: history.calls.length,
+        inCooldown: history.inCooldown && Date.now() < history.cooldownUntil,
+        cooldownCount: history.cooldownCount,
+        consecutiveTools: Object.fromEntries(history.consecutiveToolCalls),
+        fileWrites: Object.fromEntries(history.fileWriteCount),
+        fileReads: Object.fromEntries(history.fileReadCount),
+        lastAlert: history.lastAlert,
+    };
+}
+/**
+ * Get all agents' loop stats.
+ */
+export function getAllLoopStats() {
+    const stats = {};
+    for (const [agent] of agentHistories) {
+        stats[agent] = getLoopStats(agent);
+    }
+    return stats;
+}
+/**
+ * Reset all agent histories.
+ */
+export function resetLoopDetection() {
+    agentHistories.clear();
+}
+export { CONFIG as LoopDetectorConfig };

package/framework-mcp/dist/framework-mcp/src/utils/quality.js

@@ -0,0 +1,123 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Shared Code Quality Heuristic Scanner
+ * Evaluates functions lengths, nesting depth, and usage of the forbidden 'any' type.
+ */
+export function analyzePathQuality(projectRoot, targetPath) {
+    const absolutePath = path.resolve(projectRoot, targetPath);
+    const files = [];
+    function collectFilesSync(dir, exts) {
+        if (!fs.existsSync(dir))
+            return;
+        try {
+            const stat = fs.statSync(dir);
+            if (stat.isFile()) {
+                if (exts.some(ext => dir.endsWith(ext))) {
+                    files.push(dir);
+                }
+                return;
+            }
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory() && !entry.name.startsWith("node_modules") && !entry.name.startsWith(".")) {
+                    collectFilesSync(fullPath, exts);
+                }
+                else if (entry.isFile() && exts.some(ext => entry.name.endsWith(ext))) {
+                    files.push(fullPath);
+                }
+            }
+        }
+        catch {
+            // Ignore errors reading files/dirs
+        }
+    }
+    collectFilesSync(absolutePath, [".ts", ".tsx"]);
+    const issues = [];
+    let longFunctions = 0;
+    let deepNesting = 0;
+    let anyTypes = 0;
+    files.forEach((f) => {
+        try {
+            const content = fs.readFileSync(f, "utf8");
+            const lines = content.split("\n");
+            const relativePath = path.relative(projectRoot, f);
+            // Check for `any` type
+            lines.forEach((line, idx) => {
+                if (line.trim().startsWith("//") || line.trim().startsWith("/*"))
+                    return;
+                if (line.match(/\bany\b/) && !line.includes("// eslint-disable") && !line.includes("as any")) {
+                    anyTypes++;
+                    issues.push({
+                        file: relativePath,
+                        line: idx + 1,
+                        type: "any-type",
+                        message: `Line ${idx + 1}: Usage of 'any' type`
+                    });
+                }
+            });
+            // Check for long functions
+            let inFunction = false;
+            let funcLines = 0;
+            let startLine = 0;
+            let funcName = "anonymous";
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                // Detect function/method starts using regex
+                const funcMatch = line.match(/(?:public|private|protected|static\s+)?(?:async\s+)?(?:function\s+)?(\w+)\s*\([^)]*\)\s*{/);
+                const methodMatch = !funcMatch ? line.match(/^\s*(?:public|private|protected|static\s+)?(\w+)\s*\([^)]*\)\s*{/) : null;
+                const arrowMatch = !funcMatch && !methodMatch ? line.match(/(?:const|let|var)?\s*(\w+)?\s*=\s*(?:async\s*)?\([^)]*\)\s*=>\s*{/) : null;
+                if (funcMatch || methodMatch || arrowMatch) {
+                    inFunction = true;
+                    funcLines = 1;
+                    startLine = i + 1;
+                    funcName = (funcMatch?.[1] || methodMatch?.[1] || arrowMatch?.[1] || "anonymous").trim();
+                    continue;
+                }
+                if (inFunction) {
+                    funcLines++;
+                    if (line.includes("}")) {
+                        if (funcLines > 50) {
+                            longFunctions++;
+                            issues.push({
+                                file: relativePath,
+                                line: startLine,
+                                type: "complexity",
+                                message: `Function '${funcName}' is ${funcLines} lines long (max: 50)`
+                            });
+                        }
+                        inFunction = false;
+                    }
+                }
+            }
+            // Check nesting depth
+            lines.forEach((line, idx) => {
+                const indentMatch = line.match(/^(?:\s{2}){5,}/);
+                if (indentMatch && !line.trim().startsWith("//") && !line.trim().startsWith("*")) {
+                    const depth = Math.floor(indentMatch[0].length / 2);
+                    if (depth > 4) {
+                        deepNesting++;
+                        issues.push({
+                            file: relativePath,
+                            line: idx + 1,
+                            type: "complexity",
+                            message: `Line ${idx + 1}: Nesting depth ${depth}`
+                        });
+                    }
+                }
+            });
+        }
+        catch {
+            // Ignore files that can't be read
+        }
+    });
+    return {
+        totalFiles: files.length,
+        totalIssues: issues.length,
+        longFunctions,
+        deepNesting,
+        anyTypes,
+        issues
+    };
+}