atabey 0.0.13 → 0.0.15

package/dist/framework-mcp/src/utils/license-scanner.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ─── 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)
+ */
+declare const CONFIG: {
+    /** Enable license scanning */
+    ENABLED: boolean;
+    /** Automatically block copyleft licenses */
+    BLOCK_COPYLEFT: boolean;
+    /** SPDX blocklist – these licenses are automatically blocked */
+    BLOCKLIST: string[];
+    /** SPDX allowlist – these licenses are always allowed */
+    ALLOWLIST: string[];
+    /** Detect known OSS snippets by hash (requires snippet database) */
+    ENABLE_SNIPPET_DETECTION: boolean;
+    /** Path to snippet hash database */
+    SNIPPET_DB_PATH: string;
+};
+export type LicenseSeverity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "UNKNOWN";
+export interface LicenseMatch {
+    license: string;
+    severity: LicenseSeverity;
+    spdxId: string;
+    source: "header" | "spdx" | "snippet" | "comment";
+    line: number;
+    snippet: string;
+    /** Whether this license requires blocking */
+    blocked: boolean;
+    /** Whether attribution is required */
+    requiresAttribution: boolean;
+}
+/**
+ * Scan code content for license violations.
+ * Returns array of license matches found in the content.
+ */
+export declare function scanForLicenses(filePath: string, content: string): LicenseMatch[];
+/**
+ * Validate content for license compliance before allowing file write.
+ * Returns error message if blocked, null if allowed.
+ */
+export declare function validateLicenseCompliance(filePath: string, content: string): string | null;
+/**
+ * Get the severity summary of a set of license matches.
+ */
+export declare function getLicenseSeveritySummary(matches: LicenseMatch[]): {
+    hasBlocked: boolean;
+    highestSeverity: LicenseSeverity;
+    requiresAttribution: boolean;
+    uniqueLicenses: string[];
+};
+/**
+ * Get scanner config.
+ */
+export declare function getLicenseScannerConfig(): typeof CONFIG;
+export { CONFIG as LicenseScannerConfig };

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

@@ -0,0 +1,284 @@
+/**
+ * ─── 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 };
+//# sourceMappingURL=license-scanner.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"license-scanner.js","sourceRoot":"","sources":["../../../../framework-mcp/src/utils/license-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,qEAAqE;AAErE,MAAM,MAAM,GAAG;IACX,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,OAAO;IACpD,4CAA4C;IAC5C,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,OAAO;IAC7D,gEAAgE;IAChE,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,0BAA0B,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7G,yDAAyD;IACzD,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,gEAAgE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnJ,oEAAoE;IACpE,wBAAwB,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B,KAAK,MAAM;IAC7E,oCAAoC;IACpC,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE;CAC5D,CAAC;AA4BF,MAAM,aAAa,GAAgC;IAC/C,sBAAsB;IACtB,SAAS,EAAE,EAAE,IAAI,EAAE,iCAAiC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IACvH,cAAc,EAAE,EAAE,IAAI,EAAE,sCAAsC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IACjI,kBAAkB,EAAE,EAAE,IAAI,EAAE,0CAA0C,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IACzI,UAAU,EAAE,EAAE,IAAI,EAAE,wCAAwC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAC/H,eAAe,EAAE,EAAE,IAAI,EAAE,6CAA6C,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IACzI,UAAU,EAAE,EAAE,IAAI,EAAE,+BAA+B,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAEtH,6BAA6B;IAC7B,SAAS,EAAE,EAAE,IAAI,EAAE,iCAAiC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IACnH,cAAc,EAAE,EAAE,IAAI,EAAE,sCAAsC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAC7H,UAAU,EAAE,EAAE,IAAI,EAAE,wCAAwC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAC3H,eAAe,EAAE,EAAE,IAAI,EAAE,6CAA6C,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IACrI,SAAS,EAAE,EAAE,IAAI,EAAE,4BAA4B,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAC9G,UAAU,EAAE,EAAE,IAAI,EAAE,mCAAmC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAEtH,sBAAsB;IACtB,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAC9F,YAAY,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAC5G,cAAc,EAAE,EAAE,IAAI,EAAE,sBAAsB,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAChH,cAAc,EAAE,EAAE,IAAI,EAAE,sBAAsB,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAChH,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE;IAE9F,sBAAsB;IACtB,SAAS,EAAE,EAAE,IAAI,EAAE,4BAA4B,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE;IAC/G,WAAW,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE;CACvG,CAAC;AAEF,qEAAqE;AAErE,MAAM,uBAAuB,GAIxB;IACD;QACI,IAAI,EAAE,iCAAiC;QACvC,MAAM,EAAE,SAAS;QACjB,QAAQ,EAAE;YACN,6CAA6C;YAC7C,gCAAgC;YAChC,UAAU;SACb;KACJ;IACD;QACI,IAAI,EAAE,wCAAwC;QAC9C,MAAM,EAAE,UAAU;QAClB,QAAQ,EAAE;YACN,oCAAoC;YACpC,gCAAgC;YAChC,WAAW;SACd;KACJ;IACD;QACI,IAAI,EAAE,iCAAiC;QACvC,MAAM,EAAE,SAAS;QACjB,QAAQ,EAAE;YACN,6CAA6C;YAC7C,gCAAgC;YAChC,UAAU;SACb;KACJ;IACD;QACI,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,KAAK;QACb,QAAQ,EAAE;YACN,cAAc;YACd,+EAA+E;SAClF;KACJ;IACD;QACI,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,YAAY;QACpB,QAAQ,EAAE;YACN,oCAAoC;YACpC,kDAAkD;YAClD,aAAa;SAChB;KACJ;IACD;QACI,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,cAAc;QACtB,QAAQ,EAAE;YACN,eAAe;YACf,wEAAwE;SAC3E;KACJ;IACD;QACI,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,cAAc;QACtB,QAAQ,EAAE;YACN,eAAe;YACf,cAAc;YACd,sBAAsB;SACzB;KACJ;IACD;QACI,IAAI,EAAE,4BAA4B;QAClC,MAAM,EAAE,SAAS;QACjB,QAAQ,EAAE;YACN,yBAAyB;YACzB,UAAU;SACb;KACJ;CACJ,CAAC;AAEF,qEAAqE;AAErE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC3B,QAAgB,EAChB,OAAe;IAEf,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IACjD,yBAAyB;IACzB,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1I,OAAO,EAAE,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAElC,uEAAuE;IACvE,MAAM,SAAS,GAAG,yCAAyC,CAAC;IAC5D,IAAI,SAAiC,CAAC;IACtC,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;QACvD,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAE1C,IAAI,WAAW,EAAE,CAAC;YACd,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,cAAc,CAAC;YAC3E,OAAO,CAAC,IAAI,CAAC;gBACT,OAAO,EAAE,WAAW,CAAC,IAAI;gBACzB,QAAQ,EAAE,WAAW,CAAC,QAAQ;gBAC9B,MAAM;gBACN,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;gBACtC,OAAO;gBACP,mBAAmB,EAAE,WAAW,CAAC,mBAAmB;aACvD,CAAC,CAAC;QACP,CAAC;aAAM,CAAC;YACJ,0BAA0B;YAC1B,OAAO,CAAC,IAAI,CAAC;gBACT,OAAO,EAAE,YAAY,MAAM,GAAG;gBAC9B,QAAQ,EAAE,SAAS;gBACnB,MAAM;gBACN,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;gBACtC,OAAO,EAAE,MAAM,CAAC,cAAc;gBAC9B,mBAAmB,EAAE,IAAI;aAC5B,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,6DAA6D;IAC7D,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnD,KAAK,MAAM,MAAM,IAAI,uBAAuB,EAAE,CAAC;QAC3C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAChD,IAAI,WAAW,EAAE,CAAC;gBACd,MAAM,MAAM,GAAG,aAAa,CAAC,YAAY,EAAE,WAAW,CAAC,KAAM,CAAC,CAAC;gBAC/D,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI;oBAChD,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,QAAQ,EAAE,SAA4B;oBACtC,QAAQ,EAAE,IAAI;oBACd,mBAAmB,EAAE,IAAI;iBAC5B,CAAC;gBAEF,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,cAAc,CAAC;gBAElF,mCAAmC;gBACnC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;oBAC1E,OAAO,CAAC,IAAI,CAAC;wBACT,OAAO,EAAE,MAAM,CAAC,IAAI;wBACpB,QAAQ,EAAE,WAAW,CAAC,QAAQ;wBAC9B,MAAM,EAAE,MAAM,CAAC,MAAM;wBACrB,MAAM,EAAE,QAAQ;wBAChB,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC;wBACxC,OAAO;wBACP,mBAAmB,EAAE,WAAW,CAAC,mBAAmB;qBACvD,CAAC,CAAC;gBACP,CAAC;gBACD,MAAM;YACV,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACrC,QAAgB,EAChB,OAAe;IAEf,MAAM,OAAO,GAAG,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAEnD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,6BAA6B;IAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAC5B,UAAU,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,QAAQ,GAAG,CACjE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,OAAO;YACH,2DAA2D;YAC3D,EAAE;YACF,4DAA4D;YAC5D,6CAA6C;YAC7C,EAAE;YACF,OAAO;YACP,EAAE;YACF,qBAAqB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAClD,qBAAqB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAClD,EAAE;YACF,mEAAmE;SACtE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,2CAA2C;IAC3C,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACpE,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CACrC,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,qBAAqB,CAAC,CAAC,IAAI,EAAE,CAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,OAAO,IAAI,CAAC,CAAC;QAC7E,yBAAyB;IAC7B,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAuB;IAM7D,IAAI,eAAe,GAAoB,KAAK,CAAC;IAC7C,MAAM,aAAa,GAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IAC1F,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IAEzC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC1B,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACzD,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QAC1D,IAAI,UAAU,GAAG,UAAU,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;YAC/C,eAAe,GAAG,KAAK,CAAC,QAAQ,CAAC;QACrC,CAAC;IACL,CAAC;IAED,OAAO;QACH,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACxC,eAAe;QACf,mBAAmB,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC;QAC7D,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC;KAC7C,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACnC,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;AACzB,CAAC;AAED,qEAAqE;AAErE,SAAS,aAAa,CAAC,OAAe,EAAE,KAAa;IACjD,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AAC1D,CAAC;AAED,OAAO,EAAE,MAAM,IAAI,oBAAoB,EAAE,CAAC"}

package/dist/framework-mcp/src/utils/loop-detector.d.ts

@@ -0,0 +1,105 @@
+/**
+ * ─── 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)
+ */
+declare const CONFIG: {
+    /** Max consecutive same tool calls before action */
+    MAX_CONSECUTIVE: number;
+    /** Max writes to the same file before action */
+    MAX_FILE_CHURN: number;
+    /** Max reads of the same file before action */
+    MAX_FILE_READ_CHURN: number;
+    /** Oscillation pattern window (min calls to detect A→B→A→B) */
+    OSCILLATION_WINDOW: number;
+    /** Cooldown duration in ms */
+    COOLDOWN_MS: number;
+    /** Max calls to any tool in sliding window */
+    MAX_CALLS_IN_WINDOW: number;
+    /** Sliding window size in ms */
+    WINDOW_SIZE_MS: number;
+    /** Enable/disable loop detector */
+    ENABLED: boolean;
+};
+export interface ToolCallRecord {
+    agent: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    timestamp: number;
+    /** File path involved (if applicable) */
+    filePath?: string;
+    /** Content hash for content identity detection */
+    contentHash?: string;
+}
+export interface LoopAlert {
+    type: "consecutive_same_tool" | "file_churn" | "oscillation" | "rate_limit" | "content_identity";
+    severity: "warning" | "critical";
+    agent: string;
+    detail: string;
+    timestamp: number;
+    cooldownUntil: number | null;
+}
+/**
+ * Record a tool call and check for loop patterns.
+ * Returns LoopAlert if a loop pattern is detected, null otherwise.
+ */
+export declare function recordAndCheck(agent: string, toolName: string, args: Record<string, unknown>): LoopAlert | null;
+/**
+ * Check if an agent is currently in cooldown.
+ */
+export declare function isInCooldown(agent: string): {
+    inCooldown: boolean;
+    remainingMs: number;
+    reason: string | null;
+};
+/**
+ * Manually clear cooldown for an agent.
+ */
+export declare function clearCooldown(agent: string): boolean;
+/**
+ * Get loop detection stats for an agent.
+ */
+export declare function getLoopStats(agent: string): {
+    totalCalls: number;
+    recentCalls: number;
+    inCooldown: boolean;
+    cooldownCount: number;
+    consecutiveTools: Record<string, number>;
+    fileWrites: Record<string, number>;
+    fileReads: Record<string, number>;
+    lastAlert: LoopAlert | null;
+};
+/**
+ * Get all agents' loop stats.
+ */
+export declare function getAllLoopStats(): Record<string, {
+    totalCalls: number;
+    inCooldown: boolean;
+    cooldownCount: number;
+    lastAlert: LoopAlert | null;
+}>;
+/**
+ * Reset all agent histories.
+ */
+export declare function resetLoopDetection(): void;
+export { CONFIG as LoopDetectorConfig };