atabey 0.0.13 → 0.0.14

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

@@ -0,0 +1,143 @@
+/**
+ * ─── 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
+ */
+declare const CONFIG: {
+    /** Team name for budget grouping */
+    TEAM: string;
+    /** Monthly budget in USD (0 = unlimited) */
+    MONTHLY_BUDGET: number;
+    /** Max spend per agent in USD (0 = unlimited) */
+    AGENT_MAX_BUDGET: number;
+    /** Enterprise server URL for budget policy sync */
+    SYNC_URL: string;
+    /** Sync token */
+    SYNC_TOKEN: string;
+    /** Budget alert thresholds (percentages) */
+    ALERT_THRESHOLDS: number[];
+    /** Cost per 1K tokens (USD) – default: $0.003 for Claude */
+    COST_PER_1K_TOKENS: number;
+    /** Sync interval in ms */
+    SYNC_INTERVAL_MS: number;
+    /** Enable/disable budget enforcement */
+    ENABLED: boolean;
+};
+export interface BudgetState {
+    team: string;
+    /** Total spend this month in USD */
+    monthlySpend: number;
+    /** Per-agent spend this month */
+    agentSpend: Record<string, number>;
+    /** Budget period start (ISO date) */
+    periodStart: string;
+    /** Budget period end (ISO date) */
+    periodEnd: string;
+    /** Whether this team/agent is blocked */
+    blocked: boolean;
+    /** Block reason if blocked */
+    blockReason: string | null;
+    /** Last alert thresholds triggered */
+    triggeredAlerts: number[];
+    /** Last sync timestamp */
+    lastSync: string | null;
+}
+interface BudgetPolicy {
+    team: string;
+    monthlyBudget: number;
+    agentMaxBudget: number;
+    blocked: boolean;
+    blockReason: string | null;
+    updatedAt: string;
+}
+export declare class BudgetManager {
+    private static instance;
+    private state;
+    private syncTimer;
+    private localMetricsPath;
+    private constructor();
+    static getInstance(): BudgetManager;
+    /**
+     * Start the budget manager.
+     * Begins periodic sync with enterprise server.
+     */
+    start(): void;
+    /**
+     * Stop the budget manager.
+     */
+    stop(): void;
+    /**
+     * Record token usage and check budget.
+     * Returns error message if budget exceeded, null if allowed.
+     */
+    recordUsage(agent: string, tokens: number): string | null;
+    /**
+     * Check if an agent is within budget without recording usage.
+     */
+    checkBudget(agent: string): {
+        allowed: boolean;
+        monthlySpend: number;
+        monthlyBudget: number;
+        agentSpend: number;
+        agentMaxBudget: number;
+        usagePercent: number;
+        blocked: boolean;
+        blockReason: string | null;
+    };
+    /**
+     * Get full budget state.
+     */
+    getState(): BudgetState;
+    /**
+     * Reset budget for new period.
+     */
+    resetPeriod(): void;
+    /**
+     * Apply a budget policy from the enterprise server.
+     */
+    applyPolicy(policy: BudgetPolicy): void;
+    /**
+     * Sync budget state with enterprise server.
+     */
+    private syncWithServer;
+    /**
+     * Recalculate spend from local metrics file.
+     */
+    private recalculateFromLocalMetrics;
+    /**
+     * Trigger a budget alert.
+     */
+    private triggerAlert;
+    /**
+     * Save budget state to disk.
+     */
+    private saveState;
+    /**
+     * Reset the singleton instance (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Load budget state from disk.
+     */
+    private loadState;
+}
+export declare const budgetManager: BudgetManager;
+export { CONFIG as FinOpsConfig };

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

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

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

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

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

@@ -0,0 +1,95 @@
+/**
+ * ─── HUMAN-IN-THE-LOOP (In-CLI Approval) ──────────────────────────
+ *
+ * Allows risk-gated approvals without the developer leaving their AI CLI chat.
+ *
+ * Key Innovation: Instead of forcing developers to switch to a web dashboard
+ * or another terminal, approval requests are sent as MCP notifications into
+ * the developer's existing chat interface.
+ *
+ * Flow:
+ * 1. Tool call triggers risk detection
+ * 2. If risk >= threshold, tool is blocked with a structured error
+ * 3. Error message includes the traceId and approval command
+ * 4. Developer types "atabey approve <traceId>" in the same chat
+ * 5. Hermes message status updates → retry succeeds
+ *
+ * Risk Levels:
+ * - LOW (0-30): Silent pass (no approval needed)
+ * - MEDIUM (31-59): Stealth warning to stderr only
+ * - HIGH (60-100): Blocked until approval
+ */
+declare const CONFIG: {
+    /** Risk threshold for blocking (0-100) */
+    HIGH_RISK_THRESHOLD: number;
+    /** Risk threshold for medium warning */
+    MEDIUM_RISK_THRESHOLD: number;
+    /** Auto-approve low risk operations */
+    AUTO_APPROVE_LOW_RISK: boolean;
+    /** Approval timeout in seconds */
+    APPROVAL_TIMEOUT_SECONDS: number;
+};
+export type RiskLevel = "LOW" | "MEDIUM" | "HIGH";
+export interface ApprovalRequest {
+    traceId: string;
+    toolName: string;
+    agent: string;
+    riskScore: number;
+    riskLevel: RiskLevel;
+    reason: string;
+    args: Record<string, unknown>;
+    createdAt: number;
+    expiresAt: number;
+    status: "PENDING" | "APPROVED" | "REJECTED" | "EXPIRED";
+}
+/**
+ * Determine risk level from risk score.
+ */
+export declare function getRiskLevel(score: number): RiskLevel;
+/**
+ * Create an approval request for a high-risk operation.
+ * Returns the approval request and a message for the AI/developer.
+ */
+export declare function createApprovalRequest(traceId: string, toolName: string, agent: string, riskScore: number, reason: string, args: Record<string, unknown>): {
+    request: ApprovalRequest;
+    message: string;
+};
+/**
+ * Check if an operation should be blocked based on risk score.
+ * Returns:
+ * - null if allowed (LOW risk or auto-approved)
+ * - { blocked: true, message } if blocked (HIGH risk)
+ * - { blocked: false, warning } if warning only (MEDIUM risk)
+ */
+export declare function checkRiskGate(traceId: string, toolName: string, agent: string, riskScore: number, reason: string, args: Record<string, unknown>): {
+    blocked: boolean;
+    message: string | null;
+    warning?: string;
+} | null;
+/**
+ * Check if an approval request exists and is still valid.
+ */
+export declare function getApprovalStatus(traceId: string): ApprovalRequest | null;
+/**
+ * Approve a pending operation.
+ */
+export declare function approveOperation(traceId: string): {
+    success: boolean;
+    message: string;
+};
+/**
+ * Reject a pending operation.
+ */
+export declare function rejectOperation(traceId: string): {
+    success: boolean;
+    message: string;
+};
+/**
+ * Get all pending approval requests.
+ */
+export declare function getPendingApprovals(): ApprovalRequest[];
+/**
+ * Get HITL config.
+ */
+export declare function getHumanInLoopConfig(): typeof CONFIG;
+export { CONFIG as HumanInLoopConfig };