atabey 0.0.13 → 0.0.14

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

@@ -0,0 +1,217 @@
+/**
+ * ─── AI DISCIPLINE ENGINE ─────────────────────────────────────────
+ *
+ * Enforces strict rules on AI behavior at the MCP middleware layer.
+ * Unlike agent instructions (which AI can ignore), these are enforced
+ * at the tool level - AI cannot bypass them.
+ *
+ * Features:
+ * - Tool call rate limiting (prevents abuse)
+ * - File size limits (prevents reading/writing huge files)
+ * - Call frequency tracking (detects loops)
+ * - Tool blacklist per agent
+ * - Agent-based tool whitelist
+ * - Response content validation
+ * - Max concurrent operations
+ */
+import fs from "fs";
+import path from "path";
+// Per-agent discipline tracking
+const agentDiscipline = new Map();
+// ─── Configuration (from env or defaults) ─────────────────────────
+const CONFIG = {
+    MAX_CALLS_PER_MINUTE: parseInt(process.env.MCP_MAX_CALLS_PER_MINUTE || "60", 10),
+    MAX_TOTAL_CALLS: parseInt(process.env.MCP_MAX_TOTAL_CALLS || "500", 10),
+    MAX_FILE_SIZE: parseInt(process.env.MCP_MAX_FILE_SIZE || "1048576", 10),
+    MAX_ARGS_SIZE: parseInt(process.env.MCP_MAX_ARGS_SIZE || "102400", 10),
+    COOLDOWN_MS: parseInt(process.env.MCP_COOLDOWN_MS || "30000", 10),
+    MAX_RESPONSE_SIZE: parseInt(process.env.MCP_MAX_RESPONSE_SIZE || "512000", 10), // 500KB max response
+    MAX_CONSECUTIVE_SAME_TOOL: parseInt(process.env.MCP_MAX_CONSECUTIVE_SAME_TOOL || "10", 10),
+    RESTRICTED_TOOLS: (process.env.MCP_RESTRICTED_TOOLS || "")
+        .split(",").map(t => t.trim()).filter(Boolean),
+    // Agent-based tool whitelist (format: agent1:tool1,tool2;agent2:tool3,tool4)
+    AGENT_TOOL_WHITELIST: parseAgentWhitelist(process.env.MCP_AGENT_TOOL_WHITELIST || ""),
+};
+function parseAgentWhitelist(input) {
+    const map = new Map();
+    if (!input)
+        return map;
+    input.split(";").forEach(pair => {
+        const [agent, tools] = pair.split(":");
+        if (agent && tools) {
+            map.set(agent.trim(), new Set(tools.split(",").map(t => t.trim())));
+        }
+    });
+    return map;
+}
+const cooldowns = new Map();
+function getOrCreateAgent(agent) {
+    if (!agentDiscipline.has(agent)) {
+        const whitelist = CONFIG.AGENT_TOOL_WHITELIST.get(agent) || null;
+        agentDiscipline.set(agent, {
+            totalCalls: 0,
+            calls: [],
+            lastReset: Date.now(),
+            blacklistedTools: new Set(),
+            whitelistedTools: whitelist,
+            violations: 0,
+            lastViolation: null,
+        });
+    }
+    return agentDiscipline.get(agent);
+}
+function pruneOldCalls(agent, windowMs = 60000) {
+    const cutoff = Date.now() - windowMs;
+    agent.calls = agent.calls.filter(c => c.timestamp > cutoff);
+}
+function isInCooldown(agent) {
+    const until = cooldowns.get(agent);
+    if (!until)
+        return false;
+    if (Date.now() > until) {
+        cooldowns.delete(agent);
+        return false;
+    }
+    return true;
+}
+function recordViolation(agent, reason) {
+    const discipline = agentDiscipline.get(agent);
+    if (discipline) {
+        discipline.violations++;
+        discipline.lastViolation = reason;
+    }
+}
+/**
+ * Enforce discipline on a tool call before execution.
+ * Returns error message if blocked, null if allowed.
+ */
+export async function enforceDiscipline(agent, toolName, args) {
+    const discipline = getOrCreateAgent(agent);
+    // 1. Check cooldown
+    if (isInCooldown(agent)) {
+        const until = cooldowns.get(agent);
+        const remaining = Math.ceil((until - Date.now()) / 1000);
+        return `[DISCIPLINE] Agent ${agent} is in cooldown for ${remaining}s. Too many requests.`;
+    }
+    // 2. Check restricted tools (global blacklist)
+    if (CONFIG.RESTRICTED_TOOLS.includes(toolName)) {
+        recordViolation(agent, `Attempted to use restricted tool: ${toolName}`);
+        return `[DISCIPLINE] Tool "${toolName}" is restricted. Agent ${agent} cannot use it.`;
+    }
+    // 3. Check agent-specific whitelist
+    if (discipline.whitelistedTools && !discipline.whitelistedTools.has(toolName)) {
+        recordViolation(agent, `Attempted to use non-whitelisted tool: ${toolName}`);
+        const allowed = Array.from(discipline.whitelistedTools).join(", ");
+        return `[DISCIPLINE] Agent ${agent} is not allowed to use "${toolName}". Allowed tools: ${allowed}`;
+    }
+    // 4. Check total call limit
+    if (discipline.totalCalls >= CONFIG.MAX_TOTAL_CALLS) {
+        cooldowns.set(agent, Date.now() + CONFIG.COOLDOWN_MS);
+        recordViolation(agent, `Exceeded max total calls (${CONFIG.MAX_TOTAL_CALLS})`);
+        return `[DISCIPLINE] Agent ${agent} exceeded max total calls (${CONFIG.MAX_TOTAL_CALLS}). Cooldown ${CONFIG.COOLDOWN_MS / 1000}s.`;
+    }
+    // 5. Check rate limit (calls per minute)
+    pruneOldCalls(discipline);
+    if (discipline.calls.length >= CONFIG.MAX_CALLS_PER_MINUTE) {
+        cooldowns.set(agent, Date.now() + CONFIG.COOLDOWN_MS);
+        recordViolation(agent, `Rate limit exceeded (${CONFIG.MAX_CALLS_PER_MINUTE}/min)`);
+        return `[DISCIPLINE] Agent ${agent} exceeded rate limit (${CONFIG.MAX_CALLS_PER_MINUTE}/min). Cooldown ${CONFIG.COOLDOWN_MS / 1000}s.`;
+    }
+    // 6. Check consecutive same tool (prevents loops)
+    if (discipline.calls.length >= CONFIG.MAX_CONSECUTIVE_SAME_TOOL) {
+        const lastCalls = discipline.calls.slice(-CONFIG.MAX_CONSECUTIVE_SAME_TOOL);
+        const allSame = lastCalls.every(c => c.tool === toolName);
+        if (allSame) {
+            cooldowns.set(agent, Date.now() + CONFIG.COOLDOWN_MS);
+            recordViolation(agent, `Consecutive same tool limit: ${toolName} x${CONFIG.MAX_CONSECUTIVE_SAME_TOOL}`);
+            return `[DISCIPLINE] Agent ${agent} called "${toolName}" ${CONFIG.MAX_CONSECUTIVE_SAME_TOOL} times in a row. Possible loop. Cooldown.`;
+        }
+    }
+    // 7. Check args size
+    const argsStr = JSON.stringify(args);
+    if (argsStr.length > CONFIG.MAX_ARGS_SIZE) {
+        recordViolation(agent, `Args too large: ${argsStr.length} bytes`);
+        return `[DISCIPLINE] Tool call args too large (${argsStr.length} bytes, max: ${CONFIG.MAX_ARGS_SIZE}).`;
+    }
+    // 8. Check file size for read/write operations
+    if ((toolName === "read_file" || toolName === "write_file") && args.path) {
+        try {
+            const projectRoot = process.env.ATABEY_PROJECT_ROOT || process.cwd();
+            const filePath = path.resolve(projectRoot, args.path);
+            if (fs.existsSync(filePath)) {
+                const stat = fs.statSync(filePath);
+                if (stat.size > CONFIG.MAX_FILE_SIZE) {
+                    return `[DISCIPLINE] File too large (${(stat.size / 1024 / 1024).toFixed(1)}MB, max: ${(CONFIG.MAX_FILE_SIZE / 1024 / 1024).toFixed(1)}MB). Use grep_search instead.`;
+                }
+            }
+        }
+        catch { /* ignore */ }
+    }
+    // Record the call
+    discipline.totalCalls++;
+    discipline.calls.push({
+        tool: toolName,
+        timestamp: Date.now(),
+        argsSize: argsStr.length,
+    });
+    return null;
+}
+/**
+ * Validate tool response content before returning to AI.
+ * Returns error message if blocked, null if allowed.
+ */
+export function validateResponse(toolName, result) {
+    if (!result || !result.content)
+        return null;
+    for (const block of result.content) {
+        if (block.type !== "text" || !block.text)
+            continue;
+        // Check response size
+        if (block.text.length > CONFIG.MAX_RESPONSE_SIZE) {
+            return `[DISCIPLINE] Response too large (${(block.text.length / 1024).toFixed(1)}KB, max: ${(CONFIG.MAX_RESPONSE_SIZE / 1024).toFixed(1)}KB).`;
+        }
+        // Block binary/gibberish content in text responses
+        const nonPrintable = (block.text.match(/[^\x20-\x7E\n\r\t]/g) || []).length;
+        if (nonPrintable > block.text.length * 0.3) {
+            return `[DISCIPLINE] Response contains too much binary data (${nonPrintable} non-printable chars). Blocked.`;
+        }
+    }
+    return null;
+}
+/**
+ * Get discipline stats for an agent.
+ */
+export function getDisciplineStats(agent) {
+    const discipline = agentDiscipline.get(agent);
+    if (!discipline) {
+        return { totalCalls: 0, recentCalls: 0, inCooldown: false, cooldownRemaining: 0, violations: 0, lastViolation: null };
+    }
+    pruneOldCalls(discipline);
+    const cooldownUntil = cooldowns.get(agent);
+    return {
+        totalCalls: discipline.totalCalls,
+        recentCalls: discipline.calls.length,
+        inCooldown: isInCooldown(agent),
+        cooldownRemaining: cooldownUntil ? Math.max(0, cooldownUntil - Date.now()) : 0,
+        violations: discipline.violations,
+        lastViolation: discipline.lastViolation,
+    };
+}
+/**
+ * Get all agents' discipline stats.
+ */
+export function getAllDisciplineStats() {
+    const stats = {};
+    for (const [agent, _discipline] of agentDiscipline) {
+        stats[agent] = getDisciplineStats(agent);
+    }
+    return stats;
+}
+/**
+ * Reset discipline for all agents.
+ */
+export function resetDiscipline() {
+    agentDiscipline.clear();
+    cooldowns.clear();
+}
+export { CONFIG as DisciplineConfig };

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

@@ -0,0 +1,325 @@
+/**
+ * ─── FINOPS / BUDGET ENFORCEMENT ──────────────────────────────────
+ *
+ * Enterprise budget management for AI token consumption.
+ * Enforces strict cost limits per team, agent, or project.
+ *
+ * Features:
+ * - Team-based budget allocation (monthly/quarterly)
+ * - Per-agent spending limits
+ * - Automatic shutdown when budget exceeded
+ * - Central server sync for budget policies
+ * - Real-time cost tracking
+ * - Budget alerts at configurable thresholds (50%, 80%, 90%, 100%)
+ *
+ * Architecture:
+ *   [Local MCP] → Budget Check → [Enterprise Server] → Shutdown Signal
+ *
+ * Environment Variables:
+ *   ATABEY_BUDGET_TEAM       - Team name for budget grouping
+ *   ATABEY_BUDGET_MONTHLY    - Monthly budget in USD (local override)
+ *   ATABEY_BUDGET_AGENT_MAX  - Max spend per agent in USD
+ *   ATABEY_BUDGET_SYNC_URL   - Enterprise server URL for budget sync
+ */
+import fs from "fs";
+import path from "path";
+// ─── Configuration ────────────────────────────────────────────────
+const CONFIG = {
+    /** Team name for budget grouping */
+    TEAM: process.env.ATABEY_BUDGET_TEAM || "default",
+    /** Monthly budget in USD (0 = unlimited) */
+    MONTHLY_BUDGET: parseFloat(process.env.ATABEY_BUDGET_MONTHLY || "0"),
+    /** Max spend per agent in USD (0 = unlimited) */
+    AGENT_MAX_BUDGET: parseFloat(process.env.ATABEY_BUDGET_AGENT_MAX || "0"),
+    /** Enterprise server URL for budget policy sync */
+    SYNC_URL: process.env.ATABEY_BUDGET_SYNC_URL || "",
+    /** Sync token */
+    SYNC_TOKEN: process.env.ATABEY_BUDGET_SYNC_TOKEN || "",
+    /** Budget alert thresholds (percentages) */
+    ALERT_THRESHOLDS: (process.env.ATABEY_BUDGET_ALERT_THRESHOLDS || "50,80,90,100")
+        .split(",").map(t => parseInt(t.trim(), 10)).filter(t => !isNaN(t)),
+    /** Cost per 1K tokens (USD) – default: $0.003 for Claude */
+    COST_PER_1K_TOKENS: parseFloat(process.env.ATABEY_COST_PER_1K_TOKENS || "0.003"),
+    /** Sync interval in ms */
+    SYNC_INTERVAL_MS: parseInt(process.env.ATABEY_BUDGET_SYNC_INTERVAL || "60000", 10),
+    /** Enable/disable budget enforcement */
+    ENABLED: process.env.ATABEY_BUDGET_ENABLED === "true",
+};
+// ─── Budget Manager ───────────────────────────────────────────────
+export class BudgetManager {
+    static instance;
+    state;
+    syncTimer = null;
+    localMetricsPath;
+    constructor() {
+        const now = new Date();
+        const periodStart = new Date(now.getFullYear(), now.getMonth(), 1).toISOString();
+        const periodEnd = new Date(now.getFullYear(), now.getMonth() + 1, 0).toISOString();
+        this.state = {
+            team: CONFIG.TEAM,
+            monthlySpend: 0,
+            agentSpend: {},
+            periodStart,
+            periodEnd,
+            blocked: false,
+            blockReason: null,
+            triggeredAlerts: [],
+            lastSync: null,
+        };
+        const frameworkDir = process.env.ATABEY_FRAMEWORK_DIR || path.join(process.cwd(), ".atabey");
+        this.localMetricsPath = path.join(frameworkDir, "observability", "metrics.json");
+        // Load existing state
+        this.loadState();
+    }
+    static getInstance() {
+        if (!BudgetManager.instance) {
+            BudgetManager.instance = new BudgetManager();
+        }
+        return BudgetManager.instance;
+    }
+    /**
+     * Start the budget manager.
+     * Begins periodic sync with enterprise server.
+     */
+    start() {
+        if (!CONFIG.ENABLED) {
+            process.stderr.write("[FINOPS] Budget enforcement disabled.\n");
+            return;
+        }
+        process.stderr.write(`[FINOPS] Starting budget manager for team "${CONFIG.TEAM}"\n`);
+        if (CONFIG.MONTHLY_BUDGET > 0) {
+            process.stderr.write(`[FINOPS] Monthly budget: $${CONFIG.MONTHLY_BUDGET.toFixed(2)}\n`);
+        }
+        // Periodic sync with enterprise server
+        if (CONFIG.SYNC_URL) {
+            this.syncTimer = setInterval(() => this.syncWithServer(), CONFIG.SYNC_INTERVAL_MS);
+            this.syncWithServer(); // Initial sync
+        }
+        // Recalculate from local metrics
+        this.recalculateFromLocalMetrics();
+    }
+    /**
+     * Stop the budget manager.
+     */
+    stop() {
+        if (this.syncTimer) {
+            clearInterval(this.syncTimer);
+            this.syncTimer = null;
+        }
+        this.saveState();
+    }
+    /**
+     * Record token usage and check budget.
+     * Returns error message if budget exceeded, null if allowed.
+     */
+    recordUsage(agent, tokens) {
+        if (!CONFIG.ENABLED)
+            return null;
+        const cost = (tokens / 1000) * CONFIG.COST_PER_1K_TOKENS;
+        // Check if team is blocked
+        if (this.state.blocked) {
+            return `[FINOPS] ⛔ Budget exceeded: ${this.state.blockReason}`;
+        }
+        // Update spend
+        this.state.monthlySpend += cost;
+        this.state.agentSpend[agent] = (this.state.agentSpend[agent] || 0) + cost;
+        // Check team budget
+        if (CONFIG.MONTHLY_BUDGET > 0 && this.state.monthlySpend > CONFIG.MONTHLY_BUDGET) {
+            this.state.blocked = true;
+            this.state.blockReason = `Team "${CONFIG.TEAM}" exceeded monthly budget of $${CONFIG.MONTHLY_BUDGET.toFixed(2)}`;
+            this.saveState();
+            this.triggerAlert(100);
+            return `[FINOPS] ⛔ ${this.state.blockReason}`;
+        }
+        // Check agent budget
+        if (CONFIG.AGENT_MAX_BUDGET > 0 && (this.state.agentSpend[agent] || 0) > CONFIG.AGENT_MAX_BUDGET) {
+            this.state.blocked = true;
+            this.state.blockReason = `Agent "${agent}" exceeded max budget of $${CONFIG.AGENT_MAX_BUDGET.toFixed(2)}`;
+            this.saveState();
+            this.triggerAlert(100);
+            return `[FINOPS] ⛔ ${this.state.blockReason}`;
+        }
+        // Check alert thresholds
+        if (CONFIG.MONTHLY_BUDGET > 0) {
+            const usagePercent = (this.state.monthlySpend / CONFIG.MONTHLY_BUDGET) * 100;
+            for (const threshold of CONFIG.ALERT_THRESHOLDS) {
+                if (usagePercent >= threshold && !this.state.triggeredAlerts.includes(threshold)) {
+                    this.triggerAlert(threshold);
+                    process.stderr.write(`[FINOPS] ⚠️ Budget alert: ${Math.round(usagePercent)}% used ($${this.state.monthlySpend.toFixed(2)} / $${CONFIG.MONTHLY_BUDGET.toFixed(2)})\n`);
+                }
+            }
+        }
+        this.saveState();
+        return null;
+    }
+    /**
+     * Check if an agent is within budget without recording usage.
+     */
+    checkBudget(agent) {
+        const agentSpend = this.state.agentSpend[agent] || 0;
+        const usagePercent = CONFIG.MONTHLY_BUDGET > 0
+            ? (this.state.monthlySpend / CONFIG.MONTHLY_BUDGET) * 100
+            : 0;
+        return {
+            allowed: !this.state.blocked,
+            monthlySpend: this.state.monthlySpend,
+            monthlyBudget: CONFIG.MONTHLY_BUDGET,
+            agentSpend,
+            agentMaxBudget: CONFIG.AGENT_MAX_BUDGET,
+            usagePercent: Math.round(usagePercent * 100) / 100,
+            blocked: this.state.blocked,
+            blockReason: this.state.blockReason,
+        };
+    }
+    /**
+     * Get full budget state.
+     */
+    getState() {
+        return { ...this.state };
+    }
+    /**
+     * Reset budget for new period.
+     */
+    resetPeriod() {
+        const now = new Date();
+        this.state.monthlySpend = 0;
+        this.state.agentSpend = {};
+        this.state.periodStart = new Date(now.getFullYear(), now.getMonth(), 1).toISOString();
+        this.state.periodEnd = new Date(now.getFullYear(), now.getMonth() + 1, 0).toISOString();
+        this.state.blocked = false;
+        this.state.blockReason = null;
+        this.state.triggeredAlerts = [];
+        this.saveState();
+        process.stderr.write("[FINOPS] Budget period reset.\n");
+    }
+    /**
+     * Apply a budget policy from the enterprise server.
+     */
+    applyPolicy(policy) {
+        if (policy.team !== CONFIG.TEAM)
+            return;
+        if (policy.blocked) {
+            this.state.blocked = true;
+            this.state.blockReason = policy.blockReason || "Blocked by enterprise policy";
+            process.stderr.write(`[FINOPS] 🛑 Team "${CONFIG.TEAM}" blocked by enterprise policy: ${this.state.blockReason}\n`);
+        }
+        this.saveState();
+    }
+    // ─── Private Methods ───────────────────────────────────────
+    /**
+     * Sync budget state with enterprise server.
+     */
+    async syncWithServer() {
+        if (!CONFIG.SYNC_URL)
+            return;
+        try {
+            // Send local state to server
+            const url = `${CONFIG.SYNC_URL.replace(/\/$/, "")}/api/finops/sync`;
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${CONFIG.SYNC_TOKEN}`,
+                    "X-Team": CONFIG.TEAM,
+                },
+                body: JSON.stringify({
+                    team: this.state.team,
+                    monthlySpend: this.state.monthlySpend,
+                    agentSpend: this.state.agentSpend,
+                    periodStart: this.state.periodStart,
+                    periodEnd: this.state.periodEnd,
+                }),
+            });
+            if (response.ok) {
+                const policy = (await response.json());
+                this.applyPolicy(policy);
+                this.state.lastSync = new Date().toISOString();
+            }
+            else if (response.status === 402) {
+                // Payment required – budget exceeded on server side
+                const data = (await response.json());
+                this.state.blocked = true;
+                this.state.blockReason = data.reason || "Budget exceeded on enterprise server";
+                process.stderr.write(`[FINOPS] 🛑 Enterprise budget exceeded: ${this.state.blockReason}\n`);
+            }
+        }
+        catch (error) {
+            // Server unreachable – continue with local budget
+            process.stderr.write(`[FINOPS] Sync failed (server unreachable): ${error}\n`);
+        }
+    }
+    /**
+     * Recalculate spend from local metrics file.
+     */
+    recalculateFromLocalMetrics() {
+        try {
+            if (!fs.existsSync(this.localMetricsPath))
+                return;
+            const metrics = JSON.parse(fs.readFileSync(this.localMetricsPath, "utf8"));
+            const periodStart = new Date(this.state.periodStart);
+            const periodEnd = new Date(this.state.periodEnd);
+            let totalSpend = 0;
+            const agentSpend = {};
+            for (const entry of metrics) {
+                const entryDate = new Date(entry.timestamp);
+                if (entryDate >= periodStart && entryDate <= periodEnd) {
+                    const cost = (entry.estimatedTokens / 1000) * CONFIG.COST_PER_1K_TOKENS;
+                    totalSpend += cost;
+                    agentSpend[entry.agent] = (agentSpend[entry.agent] || 0) + cost;
+                }
+            }
+            this.state.monthlySpend = totalSpend;
+            this.state.agentSpend = agentSpend;
+        }
+        catch { /* ignore */ }
+    }
+    /**
+     * Trigger a budget alert.
+     */
+    triggerAlert(threshold) {
+        if (!this.state.triggeredAlerts.includes(threshold)) {
+            this.state.triggeredAlerts.push(threshold);
+        }
+    }
+    /**
+     * Save budget state to disk.
+     */
+    saveState() {
+        try {
+            const frameworkDir = process.env.ATABEY_FRAMEWORK_DIR || path.join(process.cwd(), ".atabey");
+            const finopsDir = path.join(frameworkDir, "finops");
+            if (!fs.existsSync(finopsDir)) {
+                fs.mkdirSync(finopsDir, { recursive: true });
+            }
+            const statePath = path.join(finopsDir, "budget-state.json");
+            fs.writeFileSync(statePath, JSON.stringify(this.state, null, 2));
+        }
+        catch { /* ignore */ }
+    }
+    /**
+     * Reset the singleton instance (for testing).
+     */
+    static resetInstance() {
+        BudgetManager.instance = undefined;
+    }
+    /**
+     * Load budget state from disk.
+     */
+    loadState() {
+        try {
+            const frameworkDir = process.env.ATABEY_FRAMEWORK_DIR || path.join(process.cwd(), ".atabey");
+            const statePath = path.join(frameworkDir, "finops", "budget-state.json");
+            if (fs.existsSync(statePath)) {
+                const saved = JSON.parse(fs.readFileSync(statePath, "utf8"));
+                // Only load if same period
+                if (saved.periodStart === this.state.periodStart) {
+                    this.state = saved;
+                }
+            }
+        }
+        catch { /* ignore */ }
+    }
+}
+// ─── Singleton Export ─────────────────────────────────────────────
+export const budgetManager = BudgetManager.getInstance();
+export { CONFIG as FinOpsConfig };