atabey 0.0.13 → 0.0.15

package/framework-mcp/dist/framework-mcp/src/utils/license-scanner.js

@@ -0,0 +1,283 @@
+/**
+ * ─── LICENSE / COPYRIGHT SCANNER ──────────────────────────────────
+ *
+ * Detects restrictive license blocks in AI-generated code before
+ * it reaches the developer's project. Prevents GPL, AGPL, and other
+ * copyleft license violations at the MCP middleware layer.
+ *
+ * Features:
+ * - Recognizes SPDX license identifiers
+ * - Detects known open-source license headers (GPL, AGPL, LGPL, MPL)
+ * - Checks against corporate allowlist/blocklist
+ * - Source code similarity detection for known OSS snippets
+ * - Warning vs. blocking based on license severity
+ *
+ * License Severity:
+ *   CRITICAL: GPL-3.0, AGPL-3.0 (copyleft, automatic blocking)
+ *   HIGH:    GPL-2.0, LGPL-3.0, MPL-2.0 (file-level copyleft)
+ *   MEDIUM:  MIT, Apache-2.0, BSD (permissive, allowed with attribution)
+ *   LOW:     CC0, Unlicense (public domain, no restrictions)
+ */
+import path from "path";
+// ─── Configuration ────────────────────────────────────────────────
+const CONFIG = {
+    /** Enable license scanning */
+    ENABLED: process.env.ATABEY_LICENSE_SCAN !== "false",
+    /** Automatically block copyleft licenses */
+    BLOCK_COPYLEFT: process.env.ATABEY_BLOCK_COPYLEFT !== "false",
+    /** SPDX blocklist – these licenses are automatically blocked */
+    BLOCKLIST: (process.env.ATABEY_LICENSE_BLOCKLIST || "GPL-3.0,AGPL-3.0,GPL-2.0").split(",").map(l => l.trim()),
+    /** SPDX allowlist – these licenses are always allowed */
+    ALLOWLIST: (process.env.ATABEY_LICENSE_ALLOWLIST || "MIT,Apache-2.0,BSD-2-Clause,BSD-3-Clause,ISC,CC0-1.0,Unlicense").split(",").map(l => l.trim()),
+    /** Detect known OSS snippets by hash (requires snippet database) */
+    ENABLE_SNIPPET_DETECTION: process.env.ATABEY_LICENSE_SNIPPET_CHECK === "true",
+    /** Path to snippet hash database */
+    SNIPPET_DB_PATH: process.env.ATABEY_SNIPPET_DB_PATH || "",
+};
+const SPDX_LICENSES = {
+    // Critical – Copyleft
+    "GPL-3.0": { name: "GNU General Public License v3.0", severity: "CRITICAL", copyleft: true, requiresAttribution: true },
+    "GPL-3.0-only": { name: "GNU General Public License v3.0 only", severity: "CRITICAL", copyleft: true, requiresAttribution: true },
+    "GPL-3.0-or-later": { name: "GNU General Public License v3.0 or later", severity: "CRITICAL", copyleft: true, requiresAttribution: true },
+    "AGPL-3.0": { name: "GNU Affero General Public License v3.0", severity: "CRITICAL", copyleft: true, requiresAttribution: true },
+    "AGPL-3.0-only": { name: "GNU Affero General Public License v3.0 only", severity: "CRITICAL", copyleft: true, requiresAttribution: true },
+    "SSPL-1.0": { name: "Server Side Public License v1", severity: "CRITICAL", copyleft: true, requiresAttribution: true },
+    // High – File-level copyleft
+    "GPL-2.0": { name: "GNU General Public License v2.0", severity: "HIGH", copyleft: true, requiresAttribution: true },
+    "GPL-2.0-only": { name: "GNU General Public License v2.0 only", severity: "HIGH", copyleft: true, requiresAttribution: true },
+    "LGPL-3.0": { name: "GNU Lesser General Public License v3.0", severity: "HIGH", copyleft: true, requiresAttribution: true },
+    "LGPL-3.0-only": { name: "GNU Lesser General Public License v3.0 only", severity: "HIGH", copyleft: true, requiresAttribution: true },
+    "MPL-2.0": { name: "Mozilla Public License 2.0", severity: "HIGH", copyleft: true, requiresAttribution: true },
+    "EUPL-1.2": { name: "European Union Public License 1.2", severity: "HIGH", copyleft: true, requiresAttribution: true },
+    // Medium – Permissive
+    "MIT": { name: "MIT License", severity: "MEDIUM", copyleft: false, requiresAttribution: true },
+    "Apache-2.0": { name: "Apache License 2.0", severity: "MEDIUM", copyleft: false, requiresAttribution: true },
+    "BSD-2-Clause": { name: "BSD 2-Clause License", severity: "MEDIUM", copyleft: false, requiresAttribution: true },
+    "BSD-3-Clause": { name: "BSD 3-Clause License", severity: "MEDIUM", copyleft: false, requiresAttribution: true },
+    "ISC": { name: "ISC License", severity: "MEDIUM", copyleft: false, requiresAttribution: true },
+    // Low – Public domain
+    "CC0-1.0": { name: "Creative Commons Zero v1.0", severity: "LOW", copyleft: false, requiresAttribution: false },
+    "Unlicense": { name: "The Unlicense", severity: "LOW", copyleft: false, requiresAttribution: false },
+};
+// ─── License Header Patterns ──────────────────────────────────────
+const LICENSE_HEADER_PATTERNS = [
+    {
+        name: "GNU General Public License v3.0",
+        spdxId: "GPL-3.0",
+        patterns: [
+            /GNU GENERAL PUBLIC LICENSE[\s\S]*Version 3/i,
+            /GNU General Public License v3/i,
+            /GPL-3\.0/,
+        ],
+    },
+    {
+        name: "GNU Affero General Public License v3.0",
+        spdxId: "AGPL-3.0",
+        patterns: [
+            /GNU AFFERO GENERAL PUBLIC LICENSE/i,
+            /Affero General Public License/i,
+            /AGPL-3\.0/,
+        ],
+    },
+    {
+        name: "GNU General Public License v2.0",
+        spdxId: "GPL-2.0",
+        patterns: [
+            /GNU GENERAL PUBLIC LICENSE[\s\S]*Version 2/i,
+            /GNU General Public License v2/i,
+            /GPL-2\.0/,
+        ],
+    },
+    {
+        name: "MIT License",
+        spdxId: "MIT",
+        patterns: [
+            /MIT License/i,
+            /Permission is hereby granted, free of charge, to any person obtaining a copy/i,
+        ],
+    },
+    {
+        name: "Apache License 2.0",
+        spdxId: "Apache-2.0",
+        patterns: [
+            /Apache License[\s\S]*Version 2\.0/i,
+            /Licensed under the Apache License, Version 2\.0/i,
+            /Apache-2\.0/,
+        ],
+    },
+    {
+        name: "BSD 2-Clause License",
+        spdxId: "BSD-2-Clause",
+        patterns: [
+            /BSD 2-Clause/i,
+            /Redistributions of source code must retain the above copyright notice/i,
+        ],
+    },
+    {
+        name: "BSD 3-Clause License",
+        spdxId: "BSD-3-Clause",
+        patterns: [
+            /BSD 3-Clause/i,
+            /BSD-3-Clause/,
+            /Neither the name of/i,
+        ],
+    },
+    {
+        name: "Mozilla Public License 2.0",
+        spdxId: "MPL-2.0",
+        patterns: [
+            /Mozilla Public License/i,
+            /MPL-2\.0/,
+        ],
+    },
+];
+// ─── Scanner Implementation ───────────────────────────────────────
+/**
+ * Scan code content for license violations.
+ * Returns array of license matches found in the content.
+ */
+export function scanForLicenses(filePath, content) {
+    if (!CONFIG.ENABLED)
+        return [];
+    const ext = path.extname(filePath).toLowerCase();
+    // Only scan source files
+    if (![".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".java", ".rb", ".php", ".c", ".cpp", ".h", ".hpp", ".rs", ".swift", ".kt"].includes(ext)) {
+        return [];
+    }
+    const matches = [];
+    const lines = content.split("\n");
+    // 1. Check for SPDX identifiers (e.g., `SPDX-License-Identifier: MIT`)
+    const spdxRegex = /SPDX-License-Identifier:\s*([^\s\n]+)/gi;
+    let spdxMatch;
+    while ((spdxMatch = spdxRegex.exec(content)) !== null) {
+        const spdxId = spdxMatch[1].trim();
+        const lineNo = getLineNumber(content, spdxMatch.index);
+        const licenseInfo = SPDX_LICENSES[spdxId];
+        if (licenseInfo) {
+            const blocked = CONFIG.BLOCKLIST.includes(spdxId) && CONFIG.BLOCK_COPYLEFT;
+            matches.push({
+                license: licenseInfo.name,
+                severity: licenseInfo.severity,
+                spdxId,
+                source: "spdx",
+                line: lineNo,
+                snippet: spdxMatch[0].substring(0, 80),
+                blocked,
+                requiresAttribution: licenseInfo.requiresAttribution,
+            });
+        }
+        else {
+            // Unknown SPDX identifier
+            matches.push({
+                license: `Unknown (${spdxId})`,
+                severity: "UNKNOWN",
+                spdxId,
+                source: "spdx",
+                line: lineNo,
+                snippet: spdxMatch[0].substring(0, 80),
+                blocked: CONFIG.BLOCK_COPYLEFT,
+                requiresAttribution: true,
+            });
+        }
+    }
+    // 2. Check for license header patterns in the first 50 lines
+    const headerRegion = lines.slice(0, 50).join("\n");
+    for (const header of LICENSE_HEADER_PATTERNS) {
+        for (const pattern of header.patterns) {
+            const headerMatch = headerRegion.match(pattern);
+            if (headerMatch) {
+                const lineNo = getLineNumber(headerRegion, headerMatch.index);
+                const licenseInfo = SPDX_LICENSES[header.spdxId] || {
+                    name: header.name,
+                    severity: "UNKNOWN",
+                    copyleft: true,
+                    requiresAttribution: true,
+                };
+                const blocked = CONFIG.BLOCKLIST.includes(header.spdxId) && CONFIG.BLOCK_COPYLEFT;
+                // Avoid duplicates from SPDX check
+                if (!matches.some(m => m.spdxId === header.spdxId && m.source === "header")) {
+                    matches.push({
+                        license: header.name,
+                        severity: licenseInfo.severity,
+                        spdxId: header.spdxId,
+                        source: "header",
+                        line: lineNo,
+                        snippet: headerMatch[0].substring(0, 80),
+                        blocked,
+                        requiresAttribution: licenseInfo.requiresAttribution,
+                    });
+                }
+                break;
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * Validate content for license compliance before allowing file write.
+ * Returns error message if blocked, null if allowed.
+ */
+export function validateLicenseCompliance(filePath, content) {
+    const matches = scanForLicenses(filePath, content);
+    if (matches.length === 0)
+        return null;
+    // Check for blocked licenses
+    const blocked = matches.filter(m => m.blocked);
+    if (blocked.length > 0) {
+        const details = blocked.map(m => `  Line ${m.line}: ${m.license} (${m.spdxId}) [${m.severity}]`).join("\n");
+        return [
+            "[LICENSE] ⛔ Copyleft license detected – operation blocked",
+            "",
+            "The generated code contains copyleft-licensed content that",
+            "is incompatible with corporate IP policies:",
+            "",
+            details,
+            "",
+            `Blocked licenses: ${CONFIG.BLOCKLIST.join(", ")}`,
+            `Allowed licenses: ${CONFIG.ALLOWLIST.join(", ")}`,
+            "",
+            "Please rewrite this code without using copyleft-licensed sources.",
+        ].join("\n");
+    }
+    // Check for licenses requiring attribution
+    const needsAttribution = matches.filter(m => m.requiresAttribution);
+    if (needsAttribution.length > 0) {
+        const details = needsAttribution.map(m => `  ${m.license} (${m.spdxId}) – found at line ${m.line}`).join("\n");
+        process.stderr.write(`[LICENSE] ⚠️ Attribution required for:\n${details}\n`);
+        // Don't block, just warn
+    }
+    return null;
+}
+/**
+ * Get the severity summary of a set of license matches.
+ */
+export function getLicenseSeveritySummary(matches) {
+    let highestSeverity = "LOW";
+    const severityOrder = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"];
+    const uniqueLicenses = new Set();
+    for (const match of matches) {
+        uniqueLicenses.add(match.spdxId);
+        const currentIdx = severityOrder.indexOf(match.severity);
+        const highestIdx = severityOrder.indexOf(highestSeverity);
+        if (currentIdx < highestIdx || highestIdx === -1) {
+            highestSeverity = match.severity;
+        }
+    }
+    return {
+        hasBlocked: matches.some(m => m.blocked),
+        highestSeverity,
+        requiresAttribution: matches.some(m => m.requiresAttribution),
+        uniqueLicenses: Array.from(uniqueLicenses),
+    };
+}
+/**
+ * Get scanner config.
+ */
+export function getLicenseScannerConfig() {
+    return { ...CONFIG };
+}
+// ─── Helper ───────────────────────────────────────────────────────
+function getLineNumber(content, index) {
+    return content.substring(0, index).split("\n").length;
+}
+export { CONFIG as LicenseScannerConfig };

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 [agentName] of agentHistories) {
+        stats[agentName] = getLoopStats(agentName);
+    }
+    return stats;
+}
+/**
+ * Reset all agent histories.
+ */
+export function resetLoopDetection() {
+    agentHistories.clear();
+}
+export { CONFIG as LoopDetectorConfig };