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

package/dist/bundled-agents/policy-engine-agents/dist/agents/approval-routing/agent.js

@@ -0,0 +1,730 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalRoutingAgent = exports.DECISION_TYPE = exports.AGENT_VERSION = exports.AGENT_ID = void 0;
+/**
+ * Approval Routing Agent
+ *
+ * CLASSIFICATION: APPROVAL GATING
+ *
+ * PURPOSE:
+ * Determine required approval paths for policy-gated actions. Routes
+ * approval requests to appropriate approvers based on configured rules.
+ *
+ * SCOPE:
+ * - Evaluate approval rules against action context
+ * - Determine required approvers
+ * - Build approval chains for multi-step workflows
+ * - Handle escalation paths
+ * - Check auto-approval conditions
+ *
+ * DECISION_TYPE: "approval_routing_decision"
+ *
+ * NON-RESPONSIBILITIES (MUST NOT):
+ * - Execute approval workflows
+ * - Send notifications directly
+ * - Store approval state
+ * - Modify approval rules at runtime
+ * - Access user management systems directly
+ * - Connect directly to databases
+ * - Execute SQL queries
+ * - Track approval progress
+ *
+ * This agent follows the LLM-Policy-Engine Agent Infrastructure Constitution.
+ */
+const crypto_1 = require("crypto");
+const uuid_1 = require("uuid");
+const ruvector_service_1 = require("../../integrations/ruvector-service");
+const observatory_1 = require("../../integrations/observatory");
+const logger_1 = __importDefault(require("@utils/logger"));
+const config_1 = require("@utils/config");
+/**
+ * Agent metadata constants
+ */
+exports.AGENT_ID = 'approval-routing-agent';
+exports.AGENT_VERSION = '1.0.0';
+exports.DECISION_TYPE = 'approval_routing_decision';
+/**
+ * Default approval rules (loaded from configuration in production)
+ */
+const DEFAULT_RULES = [
+    {
+        rule_id: 'high-value-model-access',
+        rule_name: 'High-Value Model Access',
+        description: 'Requires approval for access to premium LLM models',
+        condition: {
+            match: [
+                { field: 'resource_type', operator: 'equals', value: 'model' },
+                { field: 'details.tier', operator: 'equals', value: 'premium' },
+            ],
+            operator: 'all',
+        },
+        required_approvers: 1,
+        approver_pool: [],
+        timeout_seconds: 3600,
+        escalation_config: {
+            enabled: true,
+            levels: [],
+            max_escalations: 2,
+            final_action: 'deny',
+        },
+        priority: 100,
+        active: true,
+    },
+];
+/**
+ * Approval Routing Agent
+ *
+ * Stateless agent that evaluates approval requirements and produces
+ * ApprovalDecisionEvents.
+ */
+class ApprovalRoutingAgent {
+    rules;
+    environment;
+    constructor(rules = DEFAULT_RULES) {
+        this.rules = rules;
+        this.environment = config_1.config.environment || 'development';
+    }
+    /**
+     * Load approval rules
+     */
+    loadRules(rules) {
+        this.rules = rules;
+    }
+    /**
+     * Add a single rule
+     */
+    addRule(rule) {
+        this.rules.push(rule);
+    }
+    /**
+     * PRIMARY ENTRY POINT: Evaluate approval requirements
+     *
+     * This method:
+     * 1. Validates inputs
+     * 2. Evaluates approval rules
+     * 3. Determines required approvers
+     * 4. Builds approval chain
+     * 5. Calculates confidence
+     * 6. Emits exactly ONE ApprovalDecisionEvent to ruvector-service
+     * 7. Emits telemetry to Observatory
+     * 8. Returns deterministic, machine-readable output
+     */
+    async evaluate(input) {
+        const startTime = performance.now();
+        const eventId = (0, uuid_1.v4)();
+        const traceId = (0, uuid_1.v4)();
+        logger_1.default.info({ eventId, requestId: input.request_id, traceId }, 'Approval Routing Agent: Starting evaluation');
+        try {
+            // Find matching rules
+            const matchedRules = this.findMatchingRules(input);
+            // Determine routing outcome
+            const output = this.buildRoutingOutput(input, matchedRules, startTime);
+            // Calculate confidence score
+            const confidence = this.calculateConfidence(matchedRules, output);
+            // Create inputs hash for deduplication
+            const inputsHash = this.hashInputs(input);
+            // Build DecisionEvent
+            const 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,
+                rules_applied: matchedRules,
+                execution_ref: {
+                    request_id: input.request_id,
+                    trace_id: traceId,
+                    span_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: 'approval-routing-agent',
+                    sla_tier: input.priority || 'normal',
+                },
+            };
+            // Persist DecisionEvent to ruvector-service (async, non-blocking)
+            this.persistDecisionEvent(decisionEvent).catch((error) => {
+                logger_1.default.error({ error, eventId }, 'Failed to persist ApprovalDecisionEvent');
+            });
+            // Emit telemetry to Observatory (async, non-blocking)
+            this.emitTelemetry(decisionEvent, startTime).catch((error) => {
+                logger_1.default.error({ error, eventId }, 'Failed to emit telemetry');
+            });
+            logger_1.default.info({
+                eventId,
+                decision: output.decision,
+                requiredApprovers: output.required_approvers.length,
+                chainSteps: output.approval_chain.length,
+                confidence,
+                evaluationTimeMs: output.evaluation_time_ms,
+            }, 'Approval Routing Agent: Evaluation completed');
+            return decisionEvent;
+        }
+        catch (error) {
+            // On failure, still emit a DecisionEvent with error state
+            const errorEvent = this.createErrorDecisionEvent(eventId, input, error, startTime);
+            this.persistDecisionEvent(errorEvent).catch((persistError) => {
+                logger_1.default.error({ persistError, eventId }, 'Failed to persist error DecisionEvent');
+            });
+            throw error;
+        }
+    }
+    /**
+     * ROUTE: Determine approval routing for an action
+     */
+    async route(input) {
+        return this.evaluate(input);
+    }
+    /**
+     * RESOLVE: Resolve approval conflicts
+     */
+    async resolve(input) {
+        // Resolution uses the same evaluation logic but may add trace info
+        return this.evaluate({ ...input, trace: true });
+    }
+    /**
+     * Get approval status for a request
+     * @param requestId - The approval request ID to look up
+     */
+    async getStatus(requestId) {
+        // In production, this would query ruvector-service
+        logger_1.default.info({ requestId }, 'Getting approval status');
+        return null;
+    }
+    /**
+     * Find rules that match the input
+     */
+    findMatchingRules(input) {
+        const matched = [];
+        for (const rule of this.rules) {
+            if (!rule.active)
+                continue;
+            // Check if rule IDs filter is specified
+            if (input.approval_rules && !input.approval_rules.includes(rule.rule_id)) {
+                continue;
+            }
+            // Evaluate rule conditions
+            if (this.evaluateRuleConditions(rule, input)) {
+                matched.push(rule);
+            }
+        }
+        // Sort by priority (higher priority first)
+        return matched.sort((a, b) => b.priority - a.priority);
+    }
+    /**
+     * Evaluate rule conditions against input
+     */
+    evaluateRuleConditions(rule, input) {
+        const { match, operator } = rule.condition;
+        const results = match.map((condition) => {
+            const value = this.getFieldValue(input, condition.field);
+            return this.evaluateCondition(value, condition.operator, condition.value);
+        });
+        if (operator === 'all') {
+            return results.every((r) => r);
+        }
+        else {
+            return results.some((r) => r);
+        }
+    }
+    /**
+     * Get field value from input using dot notation
+     */
+    getFieldValue(input, field) {
+        const parts = field.split('.');
+        let value = input.action_context;
+        for (const part of parts) {
+            if (value && typeof value === 'object' && part in value) {
+                value = value[part];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return value;
+    }
+    /**
+     * Evaluate a single condition
+     */
+    evaluateCondition(value, operator, expected) {
+        switch (operator) {
+            case 'equals':
+                return value === expected;
+            case 'not_equals':
+                return value !== expected;
+            case 'contains':
+                if (typeof value === 'string' && typeof expected === 'string') {
+                    return value.includes(expected);
+                }
+                if (Array.isArray(value)) {
+                    return value.includes(expected);
+                }
+                return false;
+            case 'greater_than':
+                return typeof value === 'number' && typeof expected === 'number' && value > expected;
+            case 'less_than':
+                return typeof value === 'number' && typeof expected === 'number' && value < expected;
+            case 'in':
+                return Array.isArray(expected) && expected.includes(value);
+            case 'not_in':
+                return Array.isArray(expected) && !expected.includes(value);
+            case 'matches':
+                if (typeof value === 'string' && typeof expected === 'string') {
+                    try {
+                        return new RegExp(expected).test(value);
+                    }
+                    catch {
+                        return false;
+                    }
+                }
+                return false;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Build the routing output from matched rules
+     */
+    buildRoutingOutput(input, matchedRules, startTime) {
+        // Check for auto-approval first
+        const autoApproveResult = this.checkAutoApproval(input, matchedRules);
+        if (autoApproveResult) {
+            return {
+                decision: 'auto_approved',
+                required_approvers: [],
+                approval_chain: [],
+                timeout_seconds: 0,
+                escalation_path: [],
+                justification_required: false,
+                routing_metadata: {
+                    rules_evaluated: this.rules.map((r) => r.rule_id),
+                    rules_matched: matchedRules.map((r) => r.rule_id),
+                    auto_approve_reason: autoApproveResult,
+                },
+                evaluation_time_ms: performance.now() - startTime,
+            };
+        }
+        // If no rules matched, approve by default (bypass)
+        if (matchedRules.length === 0) {
+            return {
+                decision: 'approval_bypassed',
+                required_approvers: [],
+                approval_chain: [],
+                timeout_seconds: 0,
+                escalation_path: [],
+                justification_required: false,
+                routing_metadata: {
+                    rules_evaluated: this.rules.map((r) => r.rule_id),
+                    rules_matched: [],
+                    bypass_reason: 'No matching approval rules',
+                },
+                evaluation_time_ms: performance.now() - startTime,
+            };
+        }
+        // Build approval chain from matched rules
+        const approvalChain = this.buildApprovalChain(matchedRules);
+        const requiredApprovers = this.collectRequiredApprovers(matchedRules);
+        const escalationPath = this.buildEscalationPath(matchedRules);
+        const totalTimeout = this.calculateTotalTimeout(matchedRules);
+        // Determine decision based on priority
+        const decision = this.isHighPriority(input)
+            ? 'escalation_required'
+            : 'approval_required';
+        return {
+            decision,
+            required_approvers: requiredApprovers,
+            approval_chain: approvalChain,
+            timeout_seconds: totalTimeout,
+            escalation_path: escalationPath,
+            justification_required: this.requiresJustification(matchedRules),
+            routing_metadata: {
+                rules_evaluated: this.rules.map((r) => r.rule_id),
+                rules_matched: matchedRules.map((r) => r.rule_id),
+                risk_score: this.calculateRiskScore(input, matchedRules),
+                compliance_tags: this.getComplianceTags(matchedRules),
+            },
+            evaluation_time_ms: performance.now() - startTime,
+        };
+    }
+    /**
+     * Check if auto-approval conditions are met
+     */
+    checkAutoApproval(input, matchedRules) {
+        for (const rule of matchedRules) {
+            if (!rule.auto_approve_conditions)
+                continue;
+            const conditions = rule.auto_approve_conditions;
+            // Check allowed roles
+            if (conditions.allowed_roles && conditions.allowed_roles.length > 0) {
+                const hasAllowedRole = input.requester.roles.some((role) => conditions.allowed_roles.includes(role));
+                if (hasAllowedRole) {
+                    return `Requester has auto-approve role: ${input.requester.roles.join(', ')}`;
+                }
+            }
+            // Check allowed resource types
+            if (conditions.allowed_resource_types && conditions.allowed_resource_types.length > 0) {
+                if (conditions.allowed_resource_types.includes(input.action_context.resource_type)) {
+                    return `Resource type ${input.action_context.resource_type} is auto-approved`;
+                }
+            }
+            // Check allowed operations
+            if (conditions.allowed_operations && conditions.allowed_operations.length > 0) {
+                if (conditions.allowed_operations.includes(input.action_context.operation)) {
+                    return `Operation ${input.action_context.operation} is auto-approved`;
+                }
+            }
+            // Check max_value
+            if (conditions.max_value !== undefined) {
+                const value = this.getFieldValue(input, 'details.value');
+                if (typeof value === 'number' && value <= conditions.max_value) {
+                    return `Value ${value} is within auto-approve threshold of ${conditions.max_value}`;
+                }
+            }
+            // Check time restrictions
+            if (conditions.time_restrictions) {
+                const now = new Date();
+                const hour = now.getHours();
+                const { start_hour, end_hour, business_days_only } = conditions.time_restrictions;
+                const isBusinessHours = hour >= start_hour && hour < end_hour;
+                const isBusinessDay = now.getDay() !== 0 && now.getDay() !== 6;
+                if (isBusinessHours && (!business_days_only || isBusinessDay)) {
+                    return `Auto-approved during business hours`;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Build approval chain from rules
+     */
+    buildApprovalChain(rules) {
+        const chain = [];
+        let stepOrder = 1;
+        for (const rule of rules) {
+            if (rule.approver_pool.length === 0)
+                continue;
+            chain.push({
+                step_id: (0, uuid_1.v4)(),
+                step_order: stepOrder++,
+                step_type: rule.required_approvers > 1 ? 'parallel' : 'any_of',
+                step_name: rule.rule_name,
+                approvers: rule.approver_pool.filter((a) => a.available !== false),
+                required_approvals: rule.required_approvers,
+                timeout_seconds: rule.timeout_seconds,
+                escalation_on_timeout: rule.escalation_config.enabled,
+                source_rule_id: rule.rule_id,
+                instructions: rule.description,
+            });
+        }
+        return chain;
+    }
+    /**
+     * Collect all required approvers from rules
+     */
+    collectRequiredApprovers(rules) {
+        const approvers = new Map();
+        for (const rule of rules) {
+            for (const approver of rule.approver_pool) {
+                if (approver.available !== false && !approvers.has(approver.id)) {
+                    approvers.set(approver.id, approver);
+                }
+            }
+        }
+        return Array.from(approvers.values());
+    }
+    /**
+     * Build escalation path from rules
+     */
+    buildEscalationPath(rules) {
+        const levels = new Map();
+        for (const rule of rules) {
+            if (!rule.escalation_config.enabled)
+                continue;
+            for (const level of rule.escalation_config.levels) {
+                const existing = levels.get(level.level);
+                if (!existing) {
+                    levels.set(level.level, { ...level });
+                }
+                else {
+                    // Merge approvers at the same level
+                    const existingIds = new Set(existing.approvers.map((a) => a.id));
+                    for (const approver of level.approvers) {
+                        if (!existingIds.has(approver.id)) {
+                            existing.approvers.push(approver);
+                        }
+                    }
+                    // Use shorter timeout
+                    existing.timeout_seconds = Math.min(existing.timeout_seconds, level.timeout_seconds);
+                }
+            }
+        }
+        return Array.from(levels.values()).sort((a, b) => a.level - b.level);
+    }
+    /**
+     * Calculate total timeout from rules
+     */
+    calculateTotalTimeout(rules) {
+        let total = 0;
+        for (const rule of rules) {
+            total += rule.timeout_seconds;
+            // Add escalation timeouts
+            if (rule.escalation_config.enabled) {
+                for (const level of rule.escalation_config.levels) {
+                    total += level.timeout_seconds;
+                }
+            }
+        }
+        return total;
+    }
+    /**
+     * Check if request is high priority
+     */
+    isHighPriority(input) {
+        return input.priority === 'critical' || input.priority === 'high' || input.priority === 'emergency';
+    }
+    /**
+     * Check if justification is required
+     */
+    requiresJustification(rules) {
+        // Require justification for high-priority rules (priority >= 80)
+        return rules.some((r) => r.priority >= 80);
+    }
+    /**
+     * Calculate risk score based on action and rules
+     */
+    calculateRiskScore(input, rules) {
+        let score = 0;
+        // Base score from operation type
+        const operation = input.action_context.operation;
+        if (operation === 'delete')
+            score += 30;
+        else if (operation === 'update')
+            score += 20;
+        else if (operation === 'execute')
+            score += 25;
+        else if (operation === 'create')
+            score += 15;
+        // Add score based on matched rules
+        score += rules.length * 10;
+        // Add score based on rule priority
+        for (const rule of rules) {
+            score += Math.floor(rule.priority / 10);
+        }
+        // Cap at 100
+        return Math.min(100, score);
+    }
+    /**
+     * Get compliance tags from rules
+     */
+    getComplianceTags(rules) {
+        const tags = new Set();
+        for (const rule of rules) {
+            if (rule.tags) {
+                for (const tag of rule.tags) {
+                    tags.add(tag);
+                }
+            }
+        }
+        return Array.from(tags);
+    }
+    /**
+     * Calculate confidence score
+     *
+     * Confidence is based on:
+     * - Number of rules evaluated
+     * - Clarity of decision (single rule vs. multiple)
+     * - Auto-approval certainty
+     */
+    calculateConfidence(rules, output) {
+        let confidence = 1.0;
+        // Reduce confidence if no rules matched (default bypass)
+        if (rules.length === 0) {
+            confidence *= 0.85;
+        }
+        // Reduce confidence for multiple conflicting rules
+        if (rules.length > 3) {
+            confidence *= 0.95;
+        }
+        // Reduce confidence for escalation decisions
+        if (output.decision === 'escalation_required') {
+            confidence *= 0.9;
+        }
+        // Increase confidence for auto-approval with clear reason
+        if (output.decision === 'auto_approved' && output.routing_metadata.auto_approve_reason) {
+            confidence = Math.min(confidence * 1.05, 0.98);
+        }
+        // Reduce confidence if approvers are unavailable
+        const totalApprovers = rules.reduce((sum, r) => sum + r.approver_pool.length, 0);
+        const availableApprovers = rules.reduce((sum, r) => sum + r.approver_pool.filter((a) => a.available !== false).length, 0);
+        if (totalApprovers > 0 && availableApprovers < totalApprovers) {
+            confidence *= availableApprovers / totalApprovers;
+        }
+        return Math.max(0, Math.min(1, confidence));
+    }
+    /**
+     * Create SHA256 hash of inputs for deduplication
+     */
+    hashInputs(input) {
+        const serialized = JSON.stringify({
+            request_id: input.request_id,
+            action_context: input.action_context,
+            requester: input.requester,
+            approval_rules: input.approval_rules,
+        });
+        return (0, crypto_1.createHash)('sha256').update(serialized).digest('hex').substring(0, 16);
+    }
+    /**
+     * Persist DecisionEvent to ruvector-service
+     */
+    async persistDecisionEvent(event) {
+        // Cast to base DecisionEvent type for persistence
+        const baseEvent = event;
+        const ack = await ruvector_service_1.ruvectorServiceClient.persistDecisionEvent(baseEvent);
+        if (!ack.accepted) {
+            logger_1.default.warn({ event_id: event.event_id, error: ack.error }, 'ApprovalDecisionEvent persistence was not accepted');
+        }
+    }
+    /**
+     * Emit telemetry to Observatory
+     */
+    async emitTelemetry(event, startTime) {
+        const telemetryEvent = {
+            eventId: event.event_id,
+            timestamp: event.timestamp,
+            traceId: event.execution_ref.trace_id,
+            spanId: event.execution_ref.span_id,
+            policyId: event.rules_applied[0]?.rule_id || 'none',
+            ruleId: event.rules_applied[0]?.rule_id,
+            decision: this.mapDecisionToTelemetry(event.outputs.decision),
+            durationMs: performance.now() - startTime,
+            cached: event.metadata?.cached || false,
+            context: {
+                agent_id: event.agent_id,
+                environment: event.execution_ref.environment,
+            },
+            labels: {
+                agent_version: event.agent_version,
+                decision_type: event.decision_type,
+                priority: event.metadata?.sla_tier || 'normal',
+            },
+        };
+        await observatory_1.observatoryClient.emitEvaluationEvent(telemetryEvent);
+    }
+    /**
+     * Map ApprovalDecisionOutcome to Observatory DecisionOutcome
+     */
+    mapDecisionToTelemetry(decision) {
+        switch (decision) {
+            case 'auto_approved':
+            case 'approval_bypassed':
+                return 'allow';
+            case 'approval_required':
+            case 'pending_approval':
+                return 'warn';
+            case 'escalation_required':
+                return 'modify';
+            default:
+                return 'warn';
+        }
+    }
+    /**
+     * Create error DecisionEvent for failure cases
+     */
+    createErrorDecisionEvent(eventId, input, error, startTime) {
+        const 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: 'pending_approval',
+                required_approvers: [],
+                approval_chain: [],
+                timeout_seconds: 3600,
+                escalation_path: [],
+                justification_required: false,
+                routing_metadata: {
+                    rules_evaluated: [],
+                    rules_matched: [],
+                    escalation_reason: `Evaluation error: ${errorMessage}`,
+                },
+                evaluation_time_ms: performance.now() - startTime,
+            },
+            confidence: 0,
+            rules_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: 'approval-routing-agent',
+            },
+        };
+    }
+    /**
+     * Get agent registration metadata
+     */
+    static getRegistration() {
+        return {
+            agent_id: exports.AGENT_ID,
+            agent_version: exports.AGENT_VERSION,
+            agent_type: 'approval_gating',
+            agent_name: 'Approval Routing Agent',
+            description: 'Determine required approval paths for policy-gated actions. Routes approval requests to appropriate approvers based on configured rules.',
+            input_schema: 'ApprovalRoutingInput',
+            output_schema: 'ApprovalDecisionEvent',
+            decision_types: [exports.DECISION_TYPE],
+            cli_contract: {
+                command: 'agent',
+                subcommands: ['evaluate', 'route', 'resolve'],
+                required_flags: ['--action-context', '--requester', '--request-id'],
+                optional_flags: ['--rules', '--priority', '--dry-run', '--trace', '--json'],
+            },
+            consumers: [
+                'llm-orchestrator',
+                'approval-workflow-service',
+                'notification-service',
+                'audit-service',
+                'governance-systems',
+            ],
+            non_responsibilities: [
+                'Execute approval workflows',
+                'Send notifications directly',
+                'Store approval state',
+                'Modify approval rules at runtime',
+                'Access user management systems directly',
+                'Track approval progress',
+                'Connect directly to databases',
+                'Execute SQL queries',
+            ],
+            failure_modes: [
+                'Rule evaluation timeout',
+                'Invalid action context format',
+                'Missing required fields',
+                'Rule parsing error',
+                'ruvector-service unavailable (graceful degradation)',
+                'Observatory unavailable (graceful degradation)',
+                'No approvers available',
+            ],
+            registered_at: new Date().toISOString(),
+        };
+    }
+}
+exports.ApprovalRoutingAgent = ApprovalRoutingAgent;
+//# sourceMappingURL=agent.js.map