@salimassili/ai-costguard 1.1.3

package/dist/core/ExecutionInterceptor.d.ts

@@ -0,0 +1,135 @@
+/**
+ * ExecutionInterceptor.ts - DEPRECATED
+ *
+ * This module has been superseded by ExecutionOS.
+ * Please use the new AI Execution Operating System from src/os/
+ *
+ * Migration:
+ *   Old: const interceptor = new ExecutionInterceptor(config);
+ *   New: const os = new ExecutionOS(config);
+ *        const client = wrapOpenAI(os, openai, agentId);
+ */
+import { EventEmitter } from 'events';
+export interface ExecutionRequest {
+    id: string;
+    type: string;
+    provider: string;
+    action: string;
+    input: any;
+    estimatedCost: number;
+    context: {
+        tenantId: string;
+        sessionId: string;
+        agentId: string;
+    };
+}
+export type ExecutionDecision = 'allow' | 'block' | 'throttle';
+export type InterceptionMode = 'sync' | 'async' | 'non-blocking';
+export interface ExecutionExplanation {
+    summary: string;
+    details: string[];
+    policyRules: string[];
+    behaviorGraph?: {
+        workflowStep: number;
+        loopDetected: boolean;
+        redundancyScore: number;
+    };
+    costBreakdown?: {
+        currentCost: number;
+        predictedRemaining: number;
+        totalBudget: number;
+    };
+}
+export interface ExecutionDecisionResult {
+    decision: ExecutionDecision;
+    reason: string;
+    confidence: number;
+    latencyMs?: number;
+    policyRulesTriggered: string[];
+    explanation?: ExecutionExplanation;
+    costPrediction?: any;
+    throttleParams?: {
+        delayMs: number;
+        rateLimit: number;
+    };
+}
+export interface InterceptorOptions {
+    mode: string;
+    tenantId: string;
+    failOpen: boolean;
+    maxLatencyMs: number;
+    localCacheSize: number;
+}
+/**
+ * ExecutionInterceptor
+ * Main execution control entry point
+ * @deprecated Use ExecutionOS from src/os/ instead
+ */
+export declare class ExecutionInterceptor extends EventEmitter {
+    private metrics;
+    private options;
+    private localCache;
+    private isHealthy;
+    constructor(options?: Partial<InterceptorOptions>);
+    /**
+     * Intercept execution request
+     * Main entry point - must complete in <10ms
+     */
+    intercept(request: ExecutionRequest): Promise<ExecutionDecisionResult>;
+    /**
+     * Evaluate policy rules (hierarchical)
+     * Tenant → Team → User → Workflow
+     */
+    private evaluatePolicy;
+    /**
+     * Analyze agent behavior graph
+     * Detect loops, redundancy, runaway branching
+     */
+    private analyzeBehaviorGraph;
+    /**
+     * Predict cost-to-go
+     * Estimate remaining tokens, tool calls, worst-case
+     */
+    private predictCostToGo;
+    /**
+     * Synthesize final decision from all analyses
+     */
+    private synthesizeDecision;
+    /**
+     * Build human-readable explanation
+     */
+    private buildExplanation;
+    /**
+     * Check local cache for quick decisions
+     */
+    private checkLocalCache;
+    /**
+     * Cache decision result
+     */
+    private cacheResult;
+    /**
+     * Generate cache key for request
+     */
+    private cacheKey;
+    /**
+     * Update performance metrics
+     */
+    private updateMetrics;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): {
+        totalRequests: number;
+        blockedRequests: number;
+        avgLatencyMs: number;
+    };
+    /**
+     * Health check
+     */
+    health(): {
+        healthy: boolean;
+        latencyMs: number;
+    };
+}
+export declare const executionInterceptor: ExecutionInterceptor;
+//# sourceMappingURL=ExecutionInterceptor.d.ts.map

package/dist/core/ExecutionInterceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionInterceptor.d.ts","sourceRoot":"","sources":["../../src/core/ExecutionInterceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAItC,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,GAAG,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,cAAc,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,OAAO,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,aAAa,CAAC,EAAE;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC,cAAc,CAAC,EAAE,GAAG,CAAC;IACrB,cAAc,CAAC,EAAE;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,OAAO,CAAC,OAAO,CAIb;IAEF,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,UAAU,CAAuC;IACzD,OAAO,CAAC,SAAS,CAAQ;gBAEb,OAAO,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAarD;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAgF5E;;;OAGG;YACW,cAAc;IAU5B;;;OAGG;YACW,oBAAoB;IAWlC;;;OAGG;YACW,eAAe;IAU7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAuD1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA2BxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;OAEG;IACH,UAAU;;;;;IAIV;;OAEG;IACH,MAAM,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CAMlD;AAGD,eAAO,MAAM,oBAAoB,sBAM/B,CAAC"}

package/dist/core/ExecutionInterceptor.js

@@ -0,0 +1,285 @@
+"use strict";
+/**
+ * ExecutionInterceptor.ts - DEPRECATED
+ *
+ * This module has been superseded by ExecutionOS.
+ * Please use the new AI Execution Operating System from src/os/
+ *
+ * Migration:
+ *   Old: const interceptor = new ExecutionInterceptor(config);
+ *   New: const os = new ExecutionOS(config);
+ *        const client = wrapOpenAI(os, openai, agentId);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executionInterceptor = exports.ExecutionInterceptor = void 0;
+const events_1 = require("events");
+const perf_hooks_1 = require("perf_hooks");
+/**
+ * ExecutionInterceptor
+ * Main execution control entry point
+ * @deprecated Use ExecutionOS from src/os/ instead
+ */
+class ExecutionInterceptor extends events_1.EventEmitter {
+    constructor(options = {}) {
+        super();
+        this.metrics = {
+            totalRequests: 0,
+            blockedRequests: 0,
+            avgLatencyMs: 0,
+        };
+        this.isHealthy = true;
+        this.options = {
+            mode: 'local',
+            tenantId: 'default',
+            failOpen: true,
+            maxLatencyMs: 10,
+            localCacheSize: 10000,
+            ...options,
+        };
+        this.localCache = new Map();
+    }
+    /**
+     * Intercept execution request
+     * Main entry point - must complete in <10ms
+     */
+    async intercept(request) {
+        const startTime = perf_hooks_1.performance.now();
+        try {
+            // Fast path: local cache lookup (<1ms)
+            const cached = this.checkLocalCache(request);
+            if (cached) {
+                const latency = perf_hooks_1.performance.now() - startTime;
+                return { ...cached, latencyMs: latency };
+            }
+            // Parallel execution of checks (async but bounded)
+            const [policyResult, graphResult, costResult] = await Promise.all([
+                this.evaluatePolicy(request),
+                this.analyzeBehaviorGraph(request),
+                this.predictCostToGo(request),
+            ]);
+            // Synthesize decision
+            const decision = this.synthesizeDecision(policyResult, graphResult, costResult);
+            // Build explanation
+            const explanation = this.buildExplanation(request, policyResult, graphResult, costResult);
+            const latency = perf_hooks_1.performance.now() - startTime;
+            // Update metrics
+            this.updateMetrics(latency, decision.decision);
+            // Cache result
+            this.cacheResult(request, { ...decision, explanation, latencyMs: latency });
+            // Emit event for async processing
+            this.emit('execution:decided', {
+                request,
+                decision,
+                latency,
+                timestamp: Date.now(),
+            });
+            return {
+                ...decision,
+                explanation,
+                latencyMs: latency,
+            };
+        }
+        catch (error) {
+            // Fail-open: log error but allow execution
+            if (this.options.failOpen) {
+                this.emit('execution:error', { request, error, timestamp: Date.now() });
+                return {
+                    decision: 'allow',
+                    reason: 'Fail-open mode: interceptor error',
+                    confidence: 0,
+                    latencyMs: perf_hooks_1.performance.now() - startTime,
+                    policyRulesTriggered: [],
+                    explanation: {
+                        summary: 'Execution allowed due to interceptor error (fail-open mode)',
+                        details: ['Interceptor encountered an error', 'Request allowed to prevent disruption'],
+                        policyRules: [],
+                    },
+                };
+            }
+            // Fail-closed: block execution
+            return {
+                decision: 'block',
+                reason: 'Interceptor error',
+                confidence: 1,
+                latencyMs: perf_hooks_1.performance.now() - startTime,
+                policyRulesTriggered: ['error-safety'],
+                explanation: {
+                    summary: 'Execution blocked due to interceptor error',
+                    details: ['Interceptor encountered an error', 'Request blocked for safety'],
+                    policyRules: [],
+                },
+            };
+        }
+    }
+    /**
+     * Evaluate policy rules (hierarchical)
+     * Tenant → Team → User → Workflow
+     */
+    async evaluatePolicy(request) {
+        // Stub for policy engine integration
+        // In production: call policy engine with context
+        return {
+            allowed: true,
+            rulesChecked: [],
+            violations: [],
+        };
+    }
+    /**
+     * Analyze agent behavior graph
+     * Detect loops, redundancy, runaway branching
+     */
+    async analyzeBehaviorGraph(request) {
+        // Stub for behavior graph engine
+        // In production: query graph state for this session
+        return {
+            workflowStep: 1,
+            loopDetected: false,
+            redundancyScore: 0,
+            branchDepth: 0,
+        };
+    }
+    /**
+     * Predict cost-to-go
+     * Estimate remaining tokens, tool calls, worst-case
+     */
+    async predictCostToGo(request) {
+        // Stub for cost prediction engine
+        return {
+            currentCost: request.estimatedCost,
+            predictedTotal: request.estimatedCost * 2,
+            worstCase: request.estimatedCost * 5,
+            confidence: 0.7,
+        };
+    }
+    /**
+     * Synthesize final decision from all analyses
+     */
+    synthesizeDecision(policyResult, graphResult, costResult) {
+        // Priority: Block > Throttle > Allow
+        // Check for critical violations
+        if (policyResult.violations?.some((v) => v.severity === 'critical')) {
+            return {
+                decision: 'block',
+                reason: 'Critical policy violation',
+                confidence: 0.95,
+                policyRulesTriggered: policyResult.violations.map((v) => v.rule),
+                costPrediction: costResult,
+            };
+        }
+        // Check for loops or runaway patterns
+        if (graphResult.loopDetected || graphResult.redundancyScore > 0.8) {
+            return {
+                decision: 'block',
+                reason: 'Behavioral anomaly detected',
+                confidence: 0.9,
+                policyRulesTriggered: ['behavioral-check'],
+                costPrediction: costResult,
+            };
+        }
+        // Check for cost warnings
+        if (costResult.worstCase > 10) {
+            // $10 threshold
+            return {
+                decision: 'throttle',
+                reason: 'High cost prediction',
+                confidence: 0.8,
+                policyRulesTriggered: ['cost-threshold'],
+                costPrediction: costResult,
+                throttleParams: {
+                    delayMs: 1000,
+                    rateLimit: 10,
+                },
+            };
+        }
+        // Default: allow
+        return {
+            decision: 'allow',
+            reason: 'All checks passed',
+            confidence: 0.95,
+            policyRulesTriggered: [],
+            costPrediction: costResult,
+        };
+    }
+    /**
+     * Build human-readable explanation
+     */
+    buildExplanation(request, policyResult, graphResult, costResult) {
+        return {
+            summary: 'Execution decision explanation',
+            details: [
+                `Request type: ${request.type}`,
+                `Provider: ${request.provider}`,
+                `Estimated cost: $${request.estimatedCost.toFixed(4)}`,
+            ],
+            policyRules: policyResult.rulesChecked || [],
+            behaviorGraph: {
+                workflowStep: graphResult.workflowStep,
+                loopDetected: graphResult.loopDetected,
+                redundancyScore: graphResult.redundancyScore,
+            },
+            costBreakdown: {
+                currentCost: costResult.currentCost,
+                predictedRemaining: costResult.predictedTotal - costResult.currentCost,
+                totalBudget: 50, // Default budget
+            },
+        };
+    }
+    /**
+     * Check local cache for quick decisions
+     */
+    checkLocalCache(request) {
+        const key = this.cacheKey(request);
+        return this.localCache.get(key) || null;
+    }
+    /**
+     * Cache decision result
+     */
+    cacheResult(request, result) {
+        const key = this.cacheKey(request);
+        this.localCache.set(key, result);
+    }
+    /**
+     * Generate cache key for request
+     */
+    cacheKey(request) {
+        return `${request.context.tenantId}:${request.context.sessionId}:${request.id}`;
+    }
+    /**
+     * Update performance metrics
+     */
+    updateMetrics(latencyMs, decision) {
+        this.metrics.totalRequests++;
+        if (decision === 'block') {
+            this.metrics.blockedRequests++;
+        }
+        // Simple moving average
+        this.metrics.avgLatencyMs =
+            (this.metrics.avgLatencyMs * (this.metrics.totalRequests - 1) + latencyMs) /
+                this.metrics.totalRequests;
+    }
+    /**
+     * Get current metrics
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Health check
+     */
+    health() {
+        return {
+            healthy: this.isHealthy && this.metrics.avgLatencyMs < this.options.maxLatencyMs,
+            latencyMs: this.metrics.avgLatencyMs,
+        };
+    }
+}
+exports.ExecutionInterceptor = ExecutionInterceptor;
+// Export singleton for global use
+exports.executionInterceptor = new ExecutionInterceptor({
+    mode: 'local',
+    tenantId: 'default',
+    failOpen: true,
+    maxLatencyMs: 10,
+    localCacheSize: 10000,
+});
+//# sourceMappingURL=ExecutionInterceptor.js.map

package/dist/core/ExecutionInterceptor.js.map

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

package/dist/core/ExplainabilityLayer.d.ts

@@ -0,0 +1,109 @@
+/**
+ * ExplainabilityLayer.ts - Trust Through Transparency
+ *
+ * Every blocked request MUST show:
+ * - Why it was blocked
+ * - Cost prediction breakdown
+ * - Policy rule triggered
+ * - Confidence score
+ *
+ * No black-box decisions allowed.
+ */
+import { ExecutionDecisionResult } from './ExecutionInterceptor';
+import { BehaviorAnalysis } from './AgentBehaviorGraph';
+import { CostPrediction, BudgetAnalysis } from './CostPredictionEngine';
+export interface ExplanationRequest {
+    decision: 'allow' | 'throttle' | 'block';
+    requestId: string;
+    workflowId: string;
+    sessionId: string;
+    timestamp: number;
+    input: string;
+    provider: string;
+    model?: string;
+}
+export interface ExplanationOutput {
+    summary: string;
+    decision: 'allow' | 'throttle' | 'block';
+    confidence: number;
+    sections: ExplanationSection[];
+    recommendations: string[];
+    documentationLinks: string[];
+    appealProcess?: {
+        available: boolean;
+        reason: string;
+        contact?: string;
+    };
+}
+export interface ExplanationSection {
+    title: string;
+    icon: string;
+    content: string;
+    details?: string[];
+    data?: Record<string, any>;
+    visual?: 'progress' | 'gauge' | 'timeline' | 'list';
+}
+export interface CostBreakdownExplanation {
+    currentSpend: number;
+    predictedTotal: number;
+    worstCase: number;
+    budgetLimit: number;
+    percentageUsed: number;
+    items: Array<{
+        name: string;
+        cost: number;
+        percentage: number;
+        description: string;
+    }>;
+}
+export interface PolicyExplanation {
+    ruleName: string;
+    ruleDescription: string;
+    threshold: any;
+    actualValue: any;
+    triggered: boolean;
+    severity: 'info' | 'warning' | 'critical';
+    policyLevel: string;
+}
+export interface BehaviorExplanation {
+    pattern: string;
+    detected: boolean;
+    confidence: number;
+    details: string;
+    similarCases: number;
+    historicalAccuracy: number;
+}
+/**
+ * Explainability Layer
+ *
+ * Generates human-readable explanations for all decisions.
+ * Critical for trust and adoption in enterprise settings.
+ */
+export declare class ExplainabilityLayer {
+    private documentationBaseUrl;
+    /**
+     * Generate comprehensive explanation for a decision
+     */
+    explain(request: ExplanationRequest, executionResult: ExecutionDecisionResult, behaviorAnalysis?: BehaviorAnalysis, costPrediction?: CostPrediction, budgetAnalysis?: BudgetAnalysis): ExplanationOutput;
+    /**
+     * Format explanation for CLI output
+     */
+    formatForCLI(output: ExplanationOutput): string;
+    /**
+     * Format explanation for JSON/API response
+     */
+    formatForAPI(output: ExplanationOutput): Record<string, any>;
+    /**
+     * Format for dashboard/web UI
+     */
+    formatForDashboard(output: ExplanationOutput): ExplanationOutput;
+    private createDecisionSection;
+    private createCostSection;
+    private createPolicySection;
+    private createBehaviorSection;
+    private createConfidenceSection;
+    private buildSummary;
+    private getDocumentationLinks;
+}
+export declare const explainabilityLayer: ExplainabilityLayer;
+//# sourceMappingURL=ExplainabilityLayer.d.ts.map

package/dist/core/ExplainabilityLayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExplainabilityLayer.d.ts","sourceRoot":"","sources":["../../src/core/ExplainabilityLayer.ts"],"names":[],"mappings":"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"}