@llm-dev-ops/agentics-cli 1.4.26 → 1.4.29

package/dist/bundled-agents/policy-engine-agents/dist/functions/agents/policy-enforcement/agent.js

@@ -0,0 +1,605 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyEnforcementAgent = exports.DECISION_TYPE = exports.AGENT_VERSION = exports.AGENT_ID = void 0;
+/**
+ * Policy Enforcement Agent
+ *
+ * CLASSIFICATION: POLICY EVALUATION / ENFORCEMENT
+ *
+ * PURPOSE:
+ * Evaluate execution requests against defined policy rules and produce
+ * authoritative allow, deny, or approval-required decisions.
+ *
+ * SCOPE:
+ * - Evaluate policy rules against execution context
+ * - Apply constraint logic
+ * - Emit enforceable policy decisions
+ *
+ * DECISION_TYPE: "policy_enforcement_decision"
+ *
+ * NON-RESPONSIBILITIES (MUST NOT):
+ * - Intercept execution traffic directly
+ * - Retry or recover execution
+ * - Execute workflows
+ * - Modify runtime configurations
+ * - Apply optimizations
+ * - Perform analytics or forecasting
+ * - Connect directly to databases
+ *
+ * This agent follows the LLM-Policy-Engine Agent Infrastructure Constitution.
+ */
+var crypto_1 = require("crypto");
+var uuid_1 = require("uuid");
+var policy_1 = require("../../types/policy");
+var policy_engine_1 = require("../../core/engine/policy-engine");
+var ruvector_service_1 = require("../../integrations/ruvector-service");
+var observatory_1 = require("../../integrations/observatory");
+var logger_1 = __importDefault(require("../../utils/logger"));
+var config_1 = require("../../utils/config");
+/**
+ * Agent metadata constants
+ */
+exports.AGENT_ID = 'policy-enforcement-agent';
+exports.AGENT_VERSION = '1.0.0';
+exports.DECISION_TYPE = 'policy_enforcement_decision';
+/**
+ * Policy Enforcement Agent
+ *
+ * Stateless agent that evaluates policy rules and produces DecisionEvents.
+ * Designed for deployment as a Google Cloud Edge Function.
+ */
+var PolicyEnforcementAgent = /** @class */ (function () {
+    function PolicyEnforcementAgent(policies) {
+        if (policies === void 0) { policies = []; }
+        this.engine = new policy_engine_1.PolicyEngine(policies);
+        this.environment = config_1.config.environment || 'development';
+    }
+    /**
+     * Reload policies into the engine
+     */
+    PolicyEnforcementAgent.prototype.loadPolicies = function (policies) {
+        for (var _i = 0, policies_1 = policies; _i < policies_1.length; _i++) {
+            var policy = policies_1[_i];
+            this.engine.addPolicy(policy);
+        }
+    };
+    /**
+     * PRIMARY ENTRY POINT: Evaluate a policy enforcement request
+     *
+     * This method:
+     * 1. Validates inputs
+     * 2. Evaluates policies
+     * 3. Calculates confidence
+     * 4. Emits exactly ONE DecisionEvent to ruvector-service
+     * 5. Emits telemetry to Observatory
+     * 6. Returns deterministic, machine-readable output
+     */
+    PolicyEnforcementAgent.prototype.evaluate = function (input) {
+        return __awaiter(this, void 0, void 0, function () {
+            var startTime, eventId, traceId, request, response, output, constraintsApplied, confidence, inputsHash, decisionEvent, error_1, errorEvent;
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        startTime = performance.now();
+                        eventId = (0, uuid_1.v4)();
+                        traceId = (0, uuid_1.v4)();
+                        logger_1.default.info({ eventId: eventId, requestId: input.request_id, traceId: traceId }, 'Policy Enforcement Agent: Starting evaluation');
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 3, , 4]);
+                        request = this.convertToInternalRequest(input);
+                        return [4 /*yield*/, this.engine.evaluate(request)];
+                    case 2:
+                        response = _b.sent();
+                        output = this.convertToEnforcementOutput(response);
+                        constraintsApplied = this.buildAppliedConstraints(response);
+                        confidence = this.calculateConfidence(response, constraintsApplied);
+                        inputsHash = this.hashInputs(input);
+                        decisionEvent = {
+                            event_id: eventId,
+                            agent_id: exports.AGENT_ID,
+                            agent_version: exports.AGENT_VERSION,
+                            decision_type: exports.DECISION_TYPE,
+                            inputs_hash: inputsHash,
+                            outputs: output,
+                            confidence: confidence,
+                            constraints_applied: constraintsApplied,
+                            execution_ref: {
+                                request_id: input.request_id,
+                                trace_id: traceId,
+                                span_id: (0, uuid_1.v4)(),
+                                environment: this.environment,
+                                session_id: (_a = input.context.request) === null || _a === void 0 ? void 0 : _a.id,
+                            },
+                            timestamp: new Date().toISOString(),
+                            metadata: {
+                                cached: response.cached || false,
+                                engine_version: exports.AGENT_VERSION,
+                                mode: input.dry_run ? 'dry-run' : 'real-time',
+                                source: 'policy-enforcement-agent',
+                            },
+                        };
+                        // Persist DecisionEvent to ruvector-service (async, non-blocking)
+                        this.persistDecisionEvent(decisionEvent).catch(function (error) {
+                            logger_1.default.error({ error: error, eventId: eventId }, 'Failed to persist DecisionEvent');
+                        });
+                        // Emit telemetry to Observatory (async, non-blocking)
+                        this.emitTelemetry(decisionEvent, startTime).catch(function (error) {
+                            logger_1.default.error({ error: error, eventId: eventId }, 'Failed to emit telemetry');
+                        });
+                        logger_1.default.info({
+                            eventId: eventId,
+                            decision: output.decision,
+                            allowed: output.allowed,
+                            confidence: confidence,
+                            evaluationTimeMs: output.evaluation_time_ms,
+                        }, 'Policy Enforcement Agent: Evaluation completed');
+                        return [2 /*return*/, decisionEvent];
+                    case 3:
+                        error_1 = _b.sent();
+                        errorEvent = this.createErrorDecisionEvent(eventId, input, error_1, startTime);
+                        // Attempt to persist error event
+                        this.persistDecisionEvent(errorEvent).catch(function (persistError) {
+                            logger_1.default.error({ persistError: persistError, eventId: eventId }, 'Failed to persist error DecisionEvent');
+                        });
+                        throw error_1;
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * RESOLVE: Resolve constraint conflicts for a given context
+     */
+    PolicyEnforcementAgent.prototype.resolve = function (input) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                // Resolution uses the same evaluation logic but with trace enabled
+                return [2 /*return*/, this.evaluate(__assign(__assign({}, input), { trace: true }))];
+            });
+        });
+    };
+    /**
+     * ROUTE: Route a decision to appropriate enforcement layers
+     */
+    PolicyEnforcementAgent.prototype.route = function (input) {
+        return __awaiter(this, void 0, void 0, function () {
+            var event;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.evaluate(input)];
+                    case 1:
+                        event = _a.sent();
+                        // Add routing information to metadata
+                        event.metadata = __assign(__assign({}, event.metadata), { routed: true, routing_targets: this.determineRoutingTargets(event) });
+                        return [2 /*return*/, event];
+                }
+            });
+        });
+    };
+    /**
+     * Convert external input to internal PolicyEvaluationRequest
+     */
+    PolicyEnforcementAgent.prototype.convertToInternalRequest = function (input) {
+        var context = {
+            llm: input.context.llm
+                ? {
+                    provider: input.context.llm.provider,
+                    model: input.context.llm.model,
+                    prompt: input.context.llm.prompt,
+                    maxTokens: input.context.llm.max_tokens,
+                    temperature: input.context.llm.temperature,
+                }
+                : undefined,
+            user: input.context.user
+                ? {
+                    id: input.context.user.id,
+                    email: input.context.user.email,
+                    roles: input.context.user.roles,
+                    permissions: input.context.user.permissions,
+                }
+                : undefined,
+            team: input.context.team
+                ? {
+                    id: input.context.team.id,
+                    name: input.context.team.name,
+                    tier: input.context.team.tier,
+                }
+                : undefined,
+            project: input.context.project
+                ? {
+                    id: input.context.project.id,
+                    name: input.context.project.name,
+                    environment: input.context.project.environment,
+                }
+                : undefined,
+            request: input.context.request
+                ? {
+                    id: input.context.request.id,
+                    timestamp: input.context.request.timestamp,
+                    ipAddress: input.context.request.ip_address,
+                    userAgent: input.context.request.user_agent,
+                }
+                : undefined,
+            metadata: input.context.metadata,
+        };
+        return {
+            requestId: input.request_id,
+            context: context,
+            policies: input.policy_ids,
+            dryRun: input.dry_run,
+            trace: input.trace,
+        };
+    };
+    /**
+     * Convert internal response to PolicyEnforcementOutput
+     */
+    PolicyEnforcementAgent.prototype.convertToEnforcementOutput = function (response) {
+        var decision = response.decision;
+        // Map internal DecisionType to PolicyDecisionOutcome
+        var outcome;
+        switch (decision.decision) {
+            case policy_1.DecisionType.ALLOW:
+                outcome = 'policy_allow';
+                break;
+            case policy_1.DecisionType.DENY:
+                outcome = 'policy_deny';
+                break;
+            case policy_1.DecisionType.WARN:
+                outcome = 'conditional_allow';
+                break;
+            case policy_1.DecisionType.MODIFY:
+                outcome = 'conditional_allow';
+                break;
+            default:
+                outcome = 'policy_deny';
+        }
+        // Check if approval is required based on matched rules
+        // This is a simplified check - in production would analyze specific approval rules
+        var requiresApproval = decision.matchedRules.some(function (rule) { return rule.includes('approval') || rule.includes('review'); });
+        if (requiresApproval && decision.allowed) {
+            outcome = 'approval_required';
+        }
+        return {
+            decision: outcome,
+            allowed: decision.allowed,
+            reason: decision.reason,
+            matched_policies: decision.matchedPolicies,
+            matched_rules: decision.matchedRules,
+            modifications: decision.modifications,
+            approval_requirements: requiresApproval
+                ? {
+                    approvers: ['admin', 'security-team'],
+                    timeout_seconds: 3600,
+                    escalation_path: ['security-lead', 'cto'],
+                }
+                : undefined,
+            evaluation_time_ms: decision.evaluationTimeMs,
+        };
+    };
+    /**
+     * Build list of applied constraints from evaluation response
+     */
+    PolicyEnforcementAgent.prototype.buildAppliedConstraints = function (response) {
+        var constraints = [];
+        // Add matched policies as constraints
+        for (var _i = 0, _a = response.decision.matchedPolicies; _i < _a.length; _i++) {
+            var policyId = _a[_i];
+            constraints.push({
+                constraint_id: policyId,
+                constraint_name: policyId,
+                constraint_type: 'policy_rule',
+                severity: this.determineSeverity(response.decision.decision),
+                scope: 'namespace',
+                satisfied: response.decision.allowed,
+                reason: response.decision.reason,
+            });
+        }
+        // Add matched rules as constraints
+        for (var _b = 0, _c = response.decision.matchedRules; _b < _c.length; _b++) {
+            var ruleId = _c[_b];
+            constraints.push({
+                constraint_id: ruleId,
+                constraint_name: ruleId,
+                constraint_type: 'policy_rule',
+                severity: this.determineSeverity(response.decision.decision),
+                scope: 'project',
+                satisfied: response.decision.allowed,
+                reason: response.decision.reason,
+            });
+        }
+        return constraints;
+    };
+    /**
+     * Determine constraint severity from decision type
+     */
+    PolicyEnforcementAgent.prototype.determineSeverity = function (decision) {
+        switch (decision) {
+            case policy_1.DecisionType.ALLOW:
+                return 'info';
+            case policy_1.DecisionType.WARN:
+                return 'warning';
+            case policy_1.DecisionType.MODIFY:
+                return 'warning';
+            case policy_1.DecisionType.DENY:
+                return 'error';
+            default:
+                return 'info';
+        }
+    };
+    /**
+     * Calculate confidence score based on evaluation results
+     *
+     * Confidence is based on:
+     * - Number of policies evaluated
+     * - Clarity of decision (all rules agree vs. mixed)
+     * - Presence of ambiguous conditions
+     */
+    PolicyEnforcementAgent.prototype.calculateConfidence = function (response, constraints) {
+        var confidence = 1.0;
+        // Reduce confidence if no policies matched (default allow)
+        if (response.decision.matchedPolicies.length === 0) {
+            confidence *= 0.8;
+        }
+        // Reduce confidence if constraints had mixed results
+        var satisfiedCount = constraints.filter(function (c) { return c.satisfied; }).length;
+        var totalCount = constraints.length;
+        if (totalCount > 0 && satisfiedCount > 0 && satisfiedCount < totalCount) {
+            confidence *= 0.9;
+        }
+        // Reduce confidence for MODIFY decisions (ambiguous outcome)
+        if (response.decision.decision === policy_1.DecisionType.MODIFY) {
+            confidence *= 0.95;
+        }
+        // Reduce confidence for WARN decisions
+        if (response.decision.decision === policy_1.DecisionType.WARN) {
+            confidence *= 0.9;
+        }
+        // Ensure confidence is between 0 and 1
+        return Math.max(0, Math.min(1, confidence));
+    };
+    /**
+     * Create SHA256 hash of inputs for deduplication
+     */
+    PolicyEnforcementAgent.prototype.hashInputs = function (input) {
+        var serialized = JSON.stringify({
+            request_id: input.request_id,
+            context: input.context,
+            policy_ids: input.policy_ids,
+        });
+        return (0, crypto_1.createHash)('sha256').update(serialized).digest('hex').substring(0, 16);
+    };
+    /**
+     * Persist DecisionEvent to ruvector-service
+     */
+    PolicyEnforcementAgent.prototype.persistDecisionEvent = function (event) {
+        return __awaiter(this, void 0, void 0, function () {
+            var ack;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, ruvector_service_1.ruvectorServiceClient.persistDecisionEvent(event)];
+                    case 1:
+                        ack = _a.sent();
+                        if (!ack.accepted) {
+                            logger_1.default.warn({ event_id: event.event_id, error: ack.error }, 'DecisionEvent persistence was not accepted');
+                        }
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Emit telemetry to Observatory
+     */
+    PolicyEnforcementAgent.prototype.emitTelemetry = function (event, startTime) {
+        return __awaiter(this, void 0, void 0, function () {
+            var telemetryEvent;
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        telemetryEvent = {
+                            eventId: event.event_id,
+                            timestamp: event.timestamp,
+                            traceId: event.execution_ref.trace_id,
+                            spanId: event.execution_ref.span_id,
+                            policyId: event.outputs.matched_policies[0] || 'none',
+                            ruleId: event.outputs.matched_rules[0],
+                            decision: this.mapDecisionToTelemetry(event.outputs.decision),
+                            durationMs: performance.now() - startTime,
+                            cached: ((_a = event.metadata) === null || _a === void 0 ? void 0 : _a.cached) || false,
+                            context: {
+                                agent_id: event.agent_id,
+                                environment: event.execution_ref.environment,
+                            },
+                            labels: {
+                                agent_version: event.agent_version,
+                                decision_type: event.decision_type,
+                            },
+                        };
+                        return [4 /*yield*/, observatory_1.observatoryClient.emitEvaluationEvent(telemetryEvent)];
+                    case 1:
+                        _b.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Map PolicyDecisionOutcome to Observatory DecisionOutcome
+     */
+    PolicyEnforcementAgent.prototype.mapDecisionToTelemetry = function (decision) {
+        switch (decision) {
+            case 'policy_allow':
+                return 'allow';
+            case 'policy_deny':
+                return 'deny';
+            case 'approval_required':
+                return 'warn';
+            case 'conditional_allow':
+                return 'modify';
+            case 'constraint_violation':
+                return 'deny';
+            default:
+                return 'error';
+        }
+    };
+    /**
+     * Determine routing targets based on decision
+     */
+    PolicyEnforcementAgent.prototype.determineRoutingTargets = function (event) {
+        var targets = [];
+        switch (event.outputs.decision) {
+            case 'policy_deny':
+                targets.push('llm-incident-manager');
+                targets.push('governance-system');
+                break;
+            case 'approval_required':
+                targets.push('llm-orchestrator');
+                targets.push('approval-system');
+                break;
+            case 'conditional_allow':
+                targets.push('llm-edge-agent');
+                break;
+            case 'policy_allow':
+                targets.push('llm-edge-agent');
+                break;
+        }
+        return targets;
+    };
+    /**
+     * Create error DecisionEvent for failure cases
+     */
+    PolicyEnforcementAgent.prototype.createErrorDecisionEvent = function (eventId, input, error, startTime) {
+        var errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            event_id: eventId,
+            agent_id: exports.AGENT_ID,
+            agent_version: exports.AGENT_VERSION,
+            decision_type: exports.DECISION_TYPE,
+            inputs_hash: this.hashInputs(input),
+            outputs: {
+                decision: 'policy_deny',
+                allowed: false,
+                reason: "Evaluation error: ".concat(errorMessage),
+                matched_policies: [],
+                matched_rules: [],
+                evaluation_time_ms: performance.now() - startTime,
+            },
+            confidence: 0,
+            constraints_applied: [],
+            execution_ref: {
+                request_id: input.request_id,
+                trace_id: (0, uuid_1.v4)(),
+                environment: this.environment,
+            },
+            timestamp: new Date().toISOString(),
+            metadata: {
+                cached: false,
+                engine_version: exports.AGENT_VERSION,
+                mode: input.dry_run ? 'dry-run' : 'real-time',
+                source: 'policy-enforcement-agent',
+                error: errorMessage,
+            },
+        };
+    };
+    /**
+     * Get agent registration metadata
+     */
+    PolicyEnforcementAgent.getRegistration = function () {
+        return {
+            agent_id: exports.AGENT_ID,
+            agent_version: exports.AGENT_VERSION,
+            agent_type: 'policy_evaluation',
+            agent_name: 'Policy Enforcement Agent',
+            description: 'Evaluate execution requests against defined policy rules and produce authoritative allow, deny, or approval-required decisions.',
+            input_schema: 'PolicyEnforcementInput',
+            output_schema: 'DecisionEvent',
+            decision_types: [exports.DECISION_TYPE],
+            cli_contract: {
+                command: 'agent',
+                subcommands: ['evaluate', 'resolve', 'route'],
+                required_flags: ['--context', '--request-id'],
+                optional_flags: ['--policies', '--dry-run', '--trace', '--json'],
+            },
+            consumers: [
+                'llm-edge-agent',
+                'llm-orchestrator',
+                'llm-incident-manager',
+                'governance-systems',
+            ],
+            non_responsibilities: [
+                'Intercept execution traffic directly',
+                'Retry or recover execution',
+                'Execute workflows',
+                'Modify runtime configurations',
+                'Apply optimizations',
+                'Perform analytics or forecasting',
+                'Connect directly to databases',
+                'Execute SQL queries',
+            ],
+            failure_modes: [
+                'Policy evaluation timeout',
+                'Invalid context format',
+                'Missing required fields',
+                'Policy parsing error',
+                'ruvector-service unavailable (graceful degradation)',
+                'Observatory unavailable (graceful degradation)',
+            ],
+            registered_at: new Date().toISOString(),
+        };
+    };
+    return PolicyEnforcementAgent;
+}());
+exports.PolicyEnforcementAgent = PolicyEnforcementAgent;