atabey 0.0.37 → 0.1.0

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

@@ -0,0 +1,274 @@
+/**
+ * [FINOPS] Enterprise Token Cost & Budget Management Engine
+ * Real SQLite-backed token and monetary expenditure tracker.
+ * Enforces per-agent and team-wide budget limits with zero mock data.
+ */
+import { AtabeyStorage } from "../../shared/storage.js";
+import { logger } from "../../shared/logger.js";
+const DEFAULT_MONTHLY_BUDGET = parseFloat(process.env.ATABEY_BUDGET_MONTHLY || "100.0");
+const DEFAULT_AGENT_MAX_BUDGET = parseFloat(process.env.ATABEY_BUDGET_AGENT_MAX || "25.0");
+// Standard blended cost heuristic: $0.002 per 1,000 tokens ($2.00 per 1M tokens)
+const COST_PER_TOKEN = 0.002 / 1000;
+export class FinOpsManager {
+    /**
+     * Records token usage and monetary cost into SQLite costs table.
+     */
+    static recordUsage(params) {
+        const { agent, tokens, provider = "openai", model = "gpt-4o", traceId } = params;
+        const cost = Math.max(0, tokens * COST_PER_TOKEN);
+        const timestamp = new Date().toISOString();
+        try {
+            AtabeyStorage.saveCost({
+                provider,
+                model,
+                inputTokens: Math.round(tokens * 0.7),
+                outputTokens: Math.round(tokens * 0.3),
+                cost: parseFloat(cost.toFixed(6)),
+                timestamp,
+                traceId,
+            });
+            // Update agent's cumulative spend in metadata
+            const cleanAgent = agent.replace("@", "");
+            const metaKey = `finops_agent_spend_${cleanAgent}`;
+            const currentSpend = parseFloat(AtabeyStorage.getMetadata(metaKey) || "0");
+            AtabeyStorage.setMetadata(metaKey, (currentSpend + cost).toFixed(6));
+        }
+        catch (e) {
+            logger.error(`[FINOPS] Failed to record usage: ${e.message}`);
+        }
+        const state = this.getBudgetState();
+        return { cost, blocked: state.blocked };
+    }
+    /**
+     * Computes the live budget state from SQLite. Zero mock data.
+     */
+    static getBudgetState() {
+        const now = new Date();
+        const year = now.getFullYear();
+        const firstDay = new Date(year, now.getMonth(), 1).toISOString();
+        const lastDay = new Date(year, now.getMonth() + 1, 0, 23, 59, 59, 999).toISOString();
+        const db = AtabeyStorage.getDB();
+        // Sum total costs for current month
+        let monthlySpend;
+        try {
+            const row = db.prepare(`
+                SELECT COALESCE(SUM(cost), 0) as total
+                FROM costs
+                WHERE timestamp >= ? AND timestamp <= ?
+            `).get(firstDay, lastDay);
+            monthlySpend = row?.total ? parseFloat(row.total.toFixed(4)) : 0;
+        }
+        catch {
+            monthlySpend = 0;
+        }
+        // Aggregate agent spend
+        const agentSpend = {};
+        try {
+            const agents = AtabeyStorage.getAllAgents();
+            for (const ag of agents) {
+                const cleanName = ag.name.replace("@", "");
+                const metaKey = `finops_agent_spend_${cleanName}`;
+                const val = parseFloat(AtabeyStorage.getMetadata(metaKey) || "0");
+                agentSpend[cleanName] = parseFloat(val.toFixed(4));
+            }
+        }
+        catch { /* non-fatal */ }
+        const monthlyBudget = parseFloat(AtabeyStorage.getMetadata("finops_monthly_budget") || String(DEFAULT_MONTHLY_BUDGET));
+        const blocked = monthlySpend >= monthlyBudget;
+        const blockReason = blocked ? `Monthly spend ($${monthlySpend.toFixed(2)}) exceeded budget limit ($${monthlyBudget.toFixed(2)})` : null;
+        const usageRatio = monthlyBudget > 0 ? (monthlySpend / monthlyBudget) : 0;
+        const triggeredAlerts = [];
+        if (usageRatio >= 0.5)
+            triggeredAlerts.push(50);
+        if (usageRatio >= 0.75)
+            triggeredAlerts.push(75);
+        if (usageRatio >= 0.9)
+            triggeredAlerts.push(90);
+        if (usageRatio >= 1.0)
+            triggeredAlerts.push(100);
+        return {
+            team: "Core Platform",
+            monthlySpend,
+            monthlyBudget,
+            budgetLimit: monthlyBudget,
+            agentSpend,
+            periodStart: firstDay,
+            periodEnd: lastDay,
+            blocked,
+            blockReason,
+            triggeredAlerts,
+            lastSync: new Date().toISOString(),
+        };
+    }
+    /**
+     * Checks if a specific agent is within its individual budget limit.
+     */
+    static checkAgentBudget(agent) {
+        const state = this.getBudgetState();
+        const cleanName = agent.replace("@", "");
+        const agentSpend = state.agentSpend[cleanName] || 0;
+        const agentMaxBudget = parseFloat(AtabeyStorage.getMetadata(`finops_agent_max_${cleanName}`) || String(DEFAULT_AGENT_MAX_BUDGET));
+        const agentBlocked = agentSpend >= agentMaxBudget;
+        const blocked = state.blocked || agentBlocked;
+        const blockReason = state.blocked
+            ? state.blockReason
+            : agentBlocked
+                ? `Agent @${cleanName} reached individual limit ($${agentSpend.toFixed(2)} / $${agentMaxBudget.toFixed(2)})`
+                : null;
+        const usagePercent = agentMaxBudget > 0 ? Math.min(100, Math.round((agentSpend / agentMaxBudget) * 100)) : 0;
+        return {
+            allowed: !blocked,
+            monthlySpend: state.monthlySpend,
+            monthlyBudget: state.monthlyBudget,
+            agentSpend,
+            agentMaxBudget,
+            usagePercent,
+            blocked,
+            blockReason,
+        };
+    }
+    /**
+     * Resets the budget period (clears current spend metadata and logs reset).
+     */
+    static resetBudgetPeriod() {
+        const db = AtabeyStorage.getDB();
+        try {
+            db.prepare("DELETE FROM metadata WHERE key LIKE 'finops_agent_spend_%'").run();
+            AtabeyStorage.setMetadata("finops_last_reset", new Date().toISOString());
+            logger.info("[FINOPS] Budget period has been reset.");
+        }
+        catch (e) {
+            logger.error(`[FINOPS] Failed to reset budget period: ${e.message}`);
+        }
+    }
+    /**
+     * Returns real daily token and cost data for the last N days.
+     * Guaranteed zero mock data: if no usage, returns 0 values for each day.
+     */
+    static getDailyTokenHistory(days = 7) {
+        const db = AtabeyStorage.getDB();
+        const dayNames = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+        const history = [];
+        // Build list of days from (days - 1) days ago to today
+        for (let i = days - 1; i >= 0; i--) {
+            const d = new Date();
+            d.setDate(d.getDate() - i);
+            const dateStr = d.toISOString().split("T")[0]; // YYYY-MM-DD
+            const dayName = dayNames[d.getDay()];
+            let tokens = 0;
+            let cost = 0;
+            try {
+                const row = db.prepare(`
+                    SELECT 
+                        COALESCE(SUM(input_tokens + output_tokens), 0) as totalTokens,
+                        COALESCE(SUM(cost), 0) as totalCost
+                    FROM costs
+                    WHERE timestamp LIKE ?
+                `).get(`${dateStr}%`);
+                if (row) {
+                    tokens = row.totalTokens || 0;
+                    cost = row.totalCost ? parseFloat(row.totalCost.toFixed(4)) : 0;
+                }
+            }
+            catch {
+                tokens = 0;
+                cost = 0;
+            }
+            const formattedTokens = tokens >= 1_000_000
+                ? `${(tokens / 1_000_000).toFixed(1)}M`
+                : tokens >= 1_000
+                    ? `${(tokens / 1_000).toFixed(0)}K`
+                    : `${tokens}`;
+            const formattedCost = `$${cost.toFixed(2)}`;
+            history.push({
+                day: dayName,
+                date: dateStr,
+                tokens,
+                cost,
+                formattedTokens,
+                formattedCost,
+            });
+        }
+        return history;
+    }
+    // ─── Budget configuration (per-agent + webhook) ───────────────────
+    static setMonthlyBudget(usd) {
+        AtabeyStorage.setMetadata("finops_monthly_budget", String(usd));
+    }
+    static setAgentBudget(agent, usd) {
+        AtabeyStorage.setMetadata(`finops_agent_max_${agent.replace("@", "")}`, String(usd));
+    }
+    /** Per-agent ceilings (falls back to the default when unset). */
+    static getAgentBudgets() {
+        const out = {};
+        try {
+            for (const ag of AtabeyStorage.getAllAgents()) {
+                const clean = ag.name.replace("@", "");
+                out[clean] = parseFloat(AtabeyStorage.getMetadata(`finops_agent_max_${clean}`) || String(DEFAULT_AGENT_MAX_BUDGET));
+            }
+        }
+        catch { /* non-fatal */ }
+        return out;
+    }
+    static getWebhookUrl() {
+        return process.env.ATABEY_BUDGET_WEBHOOK || AtabeyStorage.getMetadata("finops_webhook_url") || null;
+    }
+    static setWebhookUrl(url) {
+        if (url && url.trim()) {
+            AtabeyStorage.setMetadata("finops_webhook_url", url.trim());
+        }
+        else {
+            try {
+                AtabeyStorage.getDB().prepare("DELETE FROM metadata WHERE key = 'finops_webhook_url'").run();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /** POST a JSON payload to the configured webhook (best-effort, never throws). */
+    static async notifyBudgetWebhook(payload) {
+        const url = this.getWebhookUrl();
+        if (!url)
+            return false;
+        try {
+            const { outboundRequest } = await import("atabey-shared/outbound-http.js");
+            const res = await outboundRequest({
+                url,
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(payload),
+                timeoutMs: 5000,
+            });
+            return res.status >= 200 && res.status < 300;
+        }
+        catch (e) {
+            logger.warn(`[FINOPS] webhook notify failed: ${e.message}`);
+            return false;
+        }
+    }
+    /**
+     * Fire webhook alerts for thresholds crossed this month (once per threshold).
+     * Returns the thresholds that fired.
+     */
+    static async checkAndNotifyBudgets(agent) {
+        const state = this.getBudgetState();
+        const month = state.periodStart.slice(0, 7);
+        const fired = [];
+        for (const threshold of state.triggeredAlerts) {
+            const key = `finops_alert_${threshold}_${month}`;
+            if (AtabeyStorage.getMetadata(key))
+                continue;
+            AtabeyStorage.setMetadata(key, "1");
+            fired.push(threshold);
+            await this.notifyBudgetWebhook({
+                type: "budget_alert",
+                threshold,
+                monthlySpend: state.monthlySpend,
+                monthlyBudget: state.monthlyBudget,
+                agent: agent ?? null,
+                at: new Date().toISOString(),
+            });
+        }
+        return fired;
+    }
+}
+//# sourceMappingURL=finops.js.map

package/dist/atabey-mcp/src/mcp/utils/finops.js.map

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

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

@@ -0,0 +1,106 @@
+/**
+ * ─── 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.
+ * Also clears persisted cooldowns from DB (important for test isolation and clean restarts).
+ */
+export declare function resetLoopDetection(): void;
+export { CONFIG as LoopDetectorConfig };