atabey 0.0.13 → 0.0.15

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"loop-detector.js","sourceRoot":"","sources":["../../../../framework-mcp/src/utils/loop-detector.ts"],"names":[],"mappings":"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"}

package/dist/framework-mcp/src/utils/quality.d.ts

@@ -0,0 +1,19 @@
+export interface QualityIssue {
+    file: string;
+    line: number;
+    type: "any-type" | "complexity";
+    message: string;
+}
+export interface QualityAnalysisResult {
+    totalFiles: number;
+    totalIssues: number;
+    longFunctions: number;
+    deepNesting: number;
+    anyTypes: number;
+    issues: QualityIssue[];
+}
+/**
+ * Shared Code Quality Heuristic Scanner
+ * Evaluates functions lengths, nesting depth, and usage of the forbidden 'any' type.
+ */
+export declare function analyzePathQuality(projectRoot: string, targetPath: string): QualityAnalysisResult;

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

@@ -0,0 +1,125 @@
+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 leadingSpaces = line.match(/^(\s*)/)?.[0].length || 0;
+                if (leadingSpaces >= 10 && !line.trim().startsWith("//") && !line.trim().startsWith("*")) {
+                    const indentSize = (leadingSpaces % 4 === 0) ? 4 : 2;
+                    const depth = Math.floor(leadingSpaces / indentSize);
+                    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
+    };
+}
+//# sourceMappingURL=quality.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quality.js","sourceRoot":"","sources":["../../../../framework-mcp/src/utils/quality.ts"],"names":[],"mappings":"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"}

package/dist/framework-mcp/src/utils/rules-engine.d.ts

@@ -0,0 +1,78 @@
+/**
+ * ─── RULES ENGINE (Prompt Conflict Resolution) ────────────────────
+ *
+ * Resolves conflicts between AI CLI built-in prompts and Atabey governance rules.
+ * Ensures Atabey's critical rules ALWAYS override CLI-level instructions.
+ *
+ * Priority System:
+ * - CRITICAL (P0): Non-bypassable rules (zero any, no console.log, PII masking)
+ * - HIGH (P1): Important rules that should not be violated
+ * - MEDIUM (P2): Standard best practices
+ * - LOW (P3): Recommendations only
+ *
+ * Enforcement Mechanisms:
+ * 1. Pre-execution: Rule validation BEFORE tool runs
+ * 2. Post-execution: Scan changed files for violations → auto-rollback
+ * 3. CLI System Prompt Override: Inject critical rules at MCP initialization
+ */
+export type RulePriority = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+export interface GovernanceRule {
+    id: string;
+    name: string;
+    description: string;
+    priority: RulePriority;
+    /** Regex pattern to detect violations in file content */
+    detectPattern?: RegExp;
+    /** Tool names this rule applies to */
+    appliesToTools?: string[];
+    /** File extensions this rule applies to (e.g., .ts, .tsx) */
+    appliesToExtensions?: string[];
+    /** Error message when violated */
+    errorMessage: string;
+    /** Auto-fix expression (optional) */
+    autoFix?: string;
+    /** Whether this rule can be bypassed */
+    bypassable: boolean;
+}
+declare const GOVERNANCE_RULES: GovernanceRule[];
+/**
+ * Get all governance rules.
+ */
+export declare function getAllRules(): GovernanceRule[];
+/**
+ * Get rules by priority level.
+ */
+export declare function getRulesByPriority(priority: RulePriority): GovernanceRule[];
+/**
+ * Get non-bypassable rules (CRITICAL + HIGH non-bypassable).
+ */
+export declare function getNonBypassableRules(): GovernanceRule[];
+/**
+ * Scan file content for rule violations.
+ * Returns array of violations found.
+ */
+export declare function scanFileForViolations(filePath: string, content: string): Array<{
+    rule: GovernanceRule;
+    match: string;
+    line: number;
+}>;
+/**
+ * Validate tool arguments against governance rules.
+ * Returns violation messages if any critical rule is violated.
+ */
+export declare function validateArgsAgainstRules(toolName: string, args: Record<string, unknown>): string | null;
+/**
+ * Validate tool response for governance violations.
+ * Returns violation messages if found.
+ */
+export declare function validateResponseAgainstRules(toolName: string, responseText: string): string | null;
+/**
+ * Build system prompt override block for CLI initialization.
+ * This is injected into the AI's system prompt at MCP connect time.
+ */
+export declare function buildSystemPromptOverride(): string;
+/**
+ * Add a custom governance rule at runtime.
+ */
+export declare function addRule(rule: GovernanceRule): void;
+export { GOVERNANCE_RULES as DefaultGovernanceRules };