@salimassili/ai-costguard 1.1.3

package/dist/middleware/withFirewall.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * AI Execution Firewall - Middleware Layer
+ *
+ * This is not a framework.
+ * It is a pre-execution cost + safety enforcement layer for AI systems.
+ * Provides automatic request interception for OpenAI-compatible SDK calls.
+ *
+ * Usage:
+ *   const openai = withFirewall(new OpenAI({ apiKey: '...' }));
+ *   const response = await openai.chat.completions.create({...});
+ *   const response = await openai.responses.create({...});  // Also intercepted!
+ *
+ *   // Or wrap fetch:
+ *   const safeFetch = withFirewall(fetch);
+ *
+ *   // Or wrap axios:
+ *   const safeAxios = withFirewall(axios);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFirewall = withFirewall;
+exports.wrapFunction = wrapFunction;
+const executionGuard_1 = require("../firewall/executionGuard");
+/**
+ * Extract prompt text from request arguments
+ */
+function extractPrompt(args) {
+    const request = args[0];
+    if (!request) {
+        return { model: 'unknown', prompt: '', maxTokens: 1000 };
+    }
+    const model = request.model || 'gpt-4';
+    const maxTokens = request.max_tokens || 512;
+    let prompt = '';
+    if (request.prompt) {
+        prompt = request.prompt;
+    }
+    else if (request.messages && Array.isArray(request.messages)) {
+        prompt = JSON.stringify(request.messages);
+    }
+    else if (request.input) {
+        prompt = typeof request.input === 'string' ? request.input : JSON.stringify(request.input);
+    }
+    else {
+        prompt = JSON.stringify(request);
+    }
+    return { model, prompt, maxTokens };
+}
+/**
+ * Check if this is an AI API call that should be analyzed
+ */
+function isAICall(path) {
+    const pathStr = path.join('.');
+    // Intercept common OpenAI SDK methods
+    const aiPatterns = [
+        'chat.completions.create',
+        'completions.create',
+        'responses.create',
+        'embeddings.create',
+        'images.generate',
+        'audio.transcriptions.create',
+        'audio.translations.create',
+        'moderations.create',
+        'beta.chat.completions.create',
+        'beta.assistants.create',
+        'beta.threads.messages.create',
+    ];
+    return aiPatterns.some(pattern => pathStr.includes(pattern));
+}
+/**
+ * Deep recursive proxy that wraps all nested objects and intercepts method calls
+ */
+function wrap(target, path = [], options) {
+    const guard = new executionGuard_1.ExecutionGuard(options.policy);
+    return new Proxy(target, {
+        get(obj, prop) {
+            const value = obj[prop];
+            const newPath = [...path, String(prop)];
+            // If it's a function, wrap it to intercept calls
+            if (typeof value === 'function') {
+                return async function (...args) {
+                    if (isAICall(newPath)) {
+                        const { model, prompt, maxTokens } = extractPrompt(args);
+                        const result = guard.evaluate({
+                            model,
+                            prompt,
+                            maxOutputTokens: maxTokens,
+                        });
+                        if (result.decision === 'block') {
+                            if (options.onBlock) {
+                                options.onBlock(result.reason, result.estimatedCostUsd);
+                            }
+                            return Promise.reject({
+                                error: {
+                                    message: `Request blocked by AI waste firewall: ${result.reason}`,
+                                    type: 'firewall_blocked',
+                                    estimatedCostUsd: result.estimatedCostUsd,
+                                },
+                                blocked: true,
+                            });
+                        }
+                        if (result.decision === 'throttle' && result.throttleMs) {
+                            if (options.onThrottle) {
+                                options.onThrottle(result.reason, result.estimatedCostUsd, result.throttleMs);
+                            }
+                            await new Promise(resolve => setTimeout(resolve, result.throttleMs));
+                        }
+                    }
+                    // Call the original function
+                    return value.apply(obj, args);
+                };
+            }
+            // If it's an object (and not null), recursively wrap it
+            if (typeof value === 'object' && value !== null) {
+                return wrap(value, newPath, options);
+            }
+            // Return primitive values as-is
+            return value;
+        },
+    });
+}
+/**
+ * Wrap an OpenAI SDK client with firewall protection using deep recursive proxy
+ */
+function withFirewall(client, options = {}) {
+    return wrap(client, [], options);
+}
+/**
+ * Wrap a generic async function with firewall protection
+ */
+function wrapFunction(fn, requestExtractor, options = {}) {
+    const guard = new executionGuard_1.ExecutionGuard(options.policy);
+    return (async (...args) => {
+        const requestData = requestExtractor(...args);
+        const result = guard.evaluate({
+            model: requestData.model,
+            prompt: requestData.prompt,
+            maxOutputTokens: requestData.maxOutputTokens,
+        });
+        if (result.decision === 'block') {
+            if (options.onBlock) {
+                options.onBlock(result.reason, result.estimatedCostUsd);
+            }
+            throw new Error(`Request blocked by AI waste firewall: ${result.reason}`);
+        }
+        if (result.decision === 'throttle' && result.throttleMs) {
+            if (options.onThrottle) {
+                options.onThrottle(result.reason, result.estimatedCostUsd, result.throttleMs);
+            }
+            await new Promise(resolve => setTimeout(resolve, result.throttleMs));
+        }
+        return fn(...args);
+    });
+}
+//# sourceMappingURL=withFirewall.js.map

package/dist/middleware/withFirewall.js.map

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

package/dist/observability/logger.d.ts

@@ -0,0 +1,14 @@
+export interface StructuredLog {
+    timestamp: string;
+    requestId: string;
+    decision: string;
+    estimatedCostUsd: number;
+    latencyMs: number;
+    reason: string;
+}
+export declare class AuditLogger {
+    private readonly streamPath;
+    constructor(streamPath?: string);
+    log(entry: StructuredLog): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/observability/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,SAA6B;IAOpE,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;CAKhC"}

package/dist/observability/logger.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditLogger = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+class AuditLogger {
+    constructor(streamPath = 'audit/firewall-audit.log') {
+        this.streamPath = streamPath;
+        const folder = (0, path_1.dirname)(streamPath);
+        if (!(0, fs_1.existsSync)(folder)) {
+            (0, fs_1.mkdirSync)(folder, { recursive: true });
+        }
+    }
+    log(entry) {
+        const line = JSON.stringify(entry);
+        // Append-only audit stream for enterprise traceability.
+        (0, fs_1.appendFileSync)(this.streamPath, `${line}\n`, { encoding: 'utf8' });
+    }
+}
+exports.AuditLogger = AuditLogger;
+//# sourceMappingURL=logger.js.map

package/dist/observability/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":";;;AAAA,2BAA2D;AAC3D,+BAA+B;AAW/B,MAAa,WAAW;IACtB,YAA6B,aAAa,0BAA0B;QAAvC,eAAU,GAAV,UAAU,CAA6B;QAClE,MAAM,MAAM,GAAG,IAAA,cAAO,EAAC,UAAU,CAAC,CAAC;QACnC,IAAI,CAAC,IAAA,eAAU,EAAC,MAAM,CAAC,EAAE,CAAC;YACxB,IAAA,cAAS,EAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,GAAG,CAAC,KAAoB;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,wDAAwD;QACxD,IAAA,mBAAc,EAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;CACF;AAbD,kCAaC"}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,17 @@
+import { TelemetryStore } from '../saas/telemetry';
+export declare class MetricsExporter {
+    private readonly telemetry;
+    constructor(telemetry: TelemetryStore);
+    toJson(): {
+        totalDecisions: number;
+        blocked: number;
+        allowed: number;
+        throttled: number;
+        blockedVsAllowedRatio: number;
+        costSavedEstimateUsd: number;
+        avgLatencyImpactMs: number;
+    };
+    toPrometheus(): string;
+    metricsHandler(): string;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,cAAc;IAEtD,MAAM;;;;;;;;;IAIN,YAAY,IAAI,MAAM;IAqBtB,cAAc;CAGf"}

package/dist/observability/metrics.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsExporter = void 0;
+class MetricsExporter {
+    constructor(telemetry) {
+        this.telemetry = telemetry;
+    }
+    toJson() {
+        return this.telemetry.getSummary();
+    }
+    toPrometheus() {
+        const summary = this.telemetry.getSummary();
+        return [
+            '# HELP firewall_decisions_total Total decision count',
+            '# TYPE firewall_decisions_total counter',
+            `firewall_decisions_total ${summary.totalDecisions}`,
+            '# HELP firewall_blocked_total Blocked request count',
+            '# TYPE firewall_blocked_total counter',
+            `firewall_blocked_total ${summary.blocked}`,
+            '# HELP firewall_allowed_total Allowed request count',
+            '# TYPE firewall_allowed_total counter',
+            `firewall_allowed_total ${summary.allowed}`,
+            '# HELP firewall_cost_saved_usd Estimated USD saved',
+            '# TYPE firewall_cost_saved_usd gauge',
+            `firewall_cost_saved_usd ${summary.costSavedEstimateUsd}`,
+            '# HELP firewall_latency_ms Average decision latency in ms',
+            '# TYPE firewall_latency_ms gauge',
+            `firewall_latency_ms ${summary.avgLatencyImpactMs}`,
+        ].join('\n');
+    }
+    metricsHandler() {
+        return this.toPrometheus();
+    }
+}
+exports.MetricsExporter = MetricsExporter;
+//# sourceMappingURL=metrics.js.map

package/dist/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":";;;AAEA,MAAa,eAAe;IAC1B,YAA6B,SAAyB;QAAzB,cAAS,GAAT,SAAS,CAAgB;IAAG,CAAC;IAE1D,MAAM;QACJ,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;IACrC,CAAC;IAED,YAAY;QACV,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;QAC5C,OAAO;YACL,sDAAsD;YACtD,yCAAyC;YACzC,4BAA4B,OAAO,CAAC,cAAc,EAAE;YACpD,qDAAqD;YACrD,uCAAuC;YACvC,0BAA0B,OAAO,CAAC,OAAO,EAAE;YAC3C,qDAAqD;YACrD,uCAAuC;YACvC,0BAA0B,OAAO,CAAC,OAAO,EAAE;YAC3C,oDAAoD;YACpD,sCAAsC;YACtC,2BAA2B,OAAO,CAAC,oBAAoB,EAAE;YACzD,2DAA2D;YAC3D,kCAAkC;YAClC,uBAAuB,OAAO,CAAC,kBAAkB,EAAE;SACpD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,cAAc;QACZ,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC;IAC7B,CAAC;CACF;AA/BD,0CA+BC"}

package/dist/os/ExecutionOS.d.ts

@@ -0,0 +1,220 @@
+/**
+ * ExecutionOS.ts - AI Execution Operating System
+ *
+ * The mandatory runtime layer for all autonomous AI agents.
+ * NOT a tool. NOT optional. The execution layer itself.
+ *
+ * Design Philosophy:
+ * - Agents CANNOT execute safely without this system
+ * - Replaces direct LLM SDK calls at the source level
+ * - Becomes the canonical execution state machine
+ * - Creates irreversible dependency through data lock-in
+ *
+ * If removed: cost explosions, security vulnerabilities, uncontrolled execution
+ */
+import { EventEmitter } from 'events';
+export type ExecutionOSMode = 'strict' | 'permissive' | 'audit';
+export type ExecutionPhase = 'planning' | 'executing' | 'completed' | 'failed';
+export type SafetyLevel = 'critical' | 'high' | 'medium' | 'low';
+export interface AgentIdentity {
+    agentId: string;
+    tenantId: string;
+    fingerprint: string;
+    createdAt: number;
+    lastSeenAt: number;
+    reputationScore: number;
+    executionCount: number;
+    totalCost: number;
+    violationCount: number;
+    trustTier: 'untrusted' | 'standard' | 'trusted' | 'enterprise';
+}
+export interface ExecutionContext {
+    executionId: string;
+    agentId: string;
+    tenantId: string;
+    sessionId: string;
+    workflowId?: string;
+    phase: ExecutionPhase;
+    parentExecutionId?: string;
+    rootExecutionId: string;
+    depth: number;
+    startTime: number;
+    budgetRemaining: number;
+    metadata: Record<string, any>;
+}
+export interface ExecutionIntent {
+    type: 'llm' | 'tool' | 'agent' | 'composite';
+    provider: string;
+    action: string;
+    input: any;
+    estimatedTokens: number;
+    estimatedCost: number;
+    dependencies: string[];
+    sideEffects: string[];
+}
+export interface ExecutionPlan {
+    executionId: string;
+    agentId: string;
+    intent: ExecutionIntent;
+    context: ExecutionContext;
+    steps: ExecutionStep[];
+    totalEstimatedCost: number;
+    maxDepth: number;
+    safetyChecks: SafetyCheck[];
+}
+export interface ExecutionStep {
+    stepId: string;
+    type: 'llm' | 'tool' | 'checkpoint' | 'gate';
+    description: string;
+    estimatedCost: number;
+    estimatedLatency: number;
+    dependencies: string[];
+    rollbackAction?: string;
+}
+export interface SafetyCheck {
+    checkId: string;
+    type: 'cost' | 'security' | 'behavior' | 'policy';
+    status: 'pending' | 'passed' | 'failed';
+    severity: SafetyLevel;
+    message: string;
+    automated: boolean;
+}
+export interface ExecutionResult {
+    executionId: string;
+    status: 'success' | 'blocked' | 'throttled' | 'failed';
+    output?: any;
+    error?: string;
+    actualCost: number;
+    actualTokens: number;
+    durationMs: number;
+    safetyChecksPassed: number;
+    safetyChecksFailed: number;
+    explanation: string;
+    alternatives?: ExecutionIntent[];
+}
+export interface OSConfig {
+    tenantId: string;
+    mode: ExecutionOSMode;
+    defaultBudget: number;
+    strictMode: boolean;
+    globalIntelligence: boolean;
+    policyAutoApply: boolean;
+}
+/**
+ * ExecutionOS - The Runtime Layer
+ *
+ * This is NOT a wrapper. NOT a middleware.
+ * This IS the execution layer.
+ *
+ * Usage:
+ *   const ai = new ExecutionOS(openaiClient, config);
+ *   ai.chat.completions.create(...) // CANNOT execute safely without OS
+ */
+export declare class ExecutionOS extends EventEmitter {
+    private config;
+    private agents;
+    private executions;
+    private globalGraph;
+    private intelligence;
+    private policyEngine;
+    private safetyKernel;
+    private metrics;
+    constructor(config: OSConfig);
+    /**
+     * Create or get agent identity
+     * Every agent MUST have an identity to execute
+     */
+    registerAgent(agentId: string, metadata?: Record<string, any>): AgentIdentity;
+    /**
+     * Execute an intent through the OS
+     * This is the ONLY safe way to execute AI operations
+     *
+     * Design: Returns ExecutionPlan, caller must execute through OS
+     */
+    plan(agentId: string, intent: ExecutionIntent, parentContext?: ExecutionContext): Promise<ExecutionPlan>;
+    /**
+     * Execute a planned operation
+     * Only executes if safety checks pass
+     */
+    execute(plan: ExecutionPlan): Promise<ExecutionResult>;
+    /**
+     * Record actual execution results
+     * Must be called after actual LLM execution
+     */
+    recordResult(executionId: string, actualResult: Partial<ExecutionResult>): Promise<ExecutionResult>;
+    /**
+     * Get execution state from canonical source
+     * No external system can reconstruct without OS
+     */
+    getExecutionState(executionId: string): {
+        context: ExecutionContext | undefined;
+        plan: ExecutionPlan | undefined;
+        result: ExecutionResult | undefined;
+        graph: any;
+    };
+    /**
+     * Get agent profile
+     */
+    getAgent(agentId: string): AgentIdentity | undefined;
+    /**
+     * List all agents for tenant
+     */
+    getAgents(): AgentIdentity[];
+    /**
+     * Get global intelligence insights
+     */
+    getIntelligence(): GlobalIntelligence;
+    /**
+     * Get system metrics
+     */
+    getMetrics(): {
+        totalExecutions: number;
+        blockedExecutions: number;
+        avgLatencyMs: number;
+        totalCostPrevented: number;
+    };
+    /**
+     * Build execution plan with safety gates
+     */
+    private buildExecutionPlan;
+    /**
+     * Generate safety explanation
+     */
+    private generateExplanation;
+    /**
+     * Update agent after execution
+     */
+    private updateAgentAfterExecution;
+    /**
+     * Update metrics
+     */
+    private updateMetrics;
+    /**
+     * Start background processes
+     */
+    private startBackgroundProcesses;
+    /**
+     * Cleanup old executions
+     */
+    private cleanupOldExecutions;
+    /**
+     * Generate unique IDs
+     */
+    private generateExecutionId;
+    private generateSessionId;
+    private generateFingerprint;
+}
+interface IntelligenceReport {
+    riskScore: number;
+    similarExecutions: number;
+    knownPatterns: string[];
+}
+declare class GlobalIntelligence {
+    analyzeIntent(intent: ExecutionIntent, agent: AgentIdentity): Promise<IntelligenceReport>;
+    recordBlockedExecution(plan: ExecutionPlan, result: ExecutionResult): void;
+    learn(plan: ExecutionPlan, result: ExecutionResult, context: ExecutionContext): Promise<void>;
+    sync(): void;
+}
+export declare const executionOS: ExecutionOS;
+export {};
+//# sourceMappingURL=ExecutionOS.d.ts.map

package/dist/os/ExecutionOS.d.ts.map

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