@llm-dev-ops/agentics-cli 1.4.25 → 1.4.27

package/dist/bundled-agents/policy-engine-agents/src/commands/policy.ts

@@ -0,0 +1,445 @@
+/**
+ * Policy Command Module
+ * Handles policy CRUD operations with executive synthesis integration
+ */
+
+import { readFileSync } from 'fs';
+import { PolicyRepository } from '@db/models/policy-repository';
+import { YAMLParser } from '@core/parser/yaml-parser';
+import { JSONParser } from '@core/parser/json-parser';
+import { SchemaValidator } from '@core/validator/schema-validator';
+import { Policy, PolicyStatus, DecisionType } from '../types/policy';
+import {
+  ExecutiveSummary,
+  PolicyCreateResult,
+  PolicyEditResult,
+  PolicyToggleResult,
+  PolicyDeleteResult,
+  PolicyDryRunResult,
+  buildPolicyCreateSynthesis,
+  buildPolicyEditSynthesis,
+  buildPolicyToggleSynthesis,
+  buildPolicyDryRunSynthesis,
+  buildDecisionPacket,
+  buildExecutiveSummary,
+  elevateRiskForProduction,
+  extractBlockingIssues,
+  isProductionTarget,
+  calculateSuccessRate,
+} from '../synthesis';
+
+const policyRepository = new PolicyRepository();
+const yamlParser = new YAMLParser();
+const jsonParser = new JSONParser();
+const validator = new SchemaValidator();
+
+/**
+ * Determine the environment from policy namespace or metadata
+ */
+function determineEnvironment(policy: Policy): string {
+  const namespace = policy.metadata.namespace.toLowerCase();
+
+  if (namespace.includes('prod') || namespace.includes('production')) {
+    return 'production';
+  }
+  if (namespace.includes('staging') || namespace.includes('stage')) {
+    return 'staging';
+  }
+  if (namespace.includes('dev') || namespace.includes('development')) {
+    return 'development';
+  }
+  if (namespace.includes('test')) {
+    return 'test';
+  }
+
+  // Policies affect all environments by default
+  return 'production';
+}
+
+/**
+ * Parse a policy file (YAML or JSON)
+ */
+function parsePolicy(filePath: string): Policy {
+  const content = readFileSync(filePath, 'utf-8');
+  const isYaml = filePath.endsWith('.yaml') || filePath.endsWith('.yml');
+  return isYaml ? yamlParser.parse(content) : jsonParser.parse(content);
+}
+
+/**
+ * Create a new policy
+ */
+export async function createPolicy(
+  filePath: string,
+  createdBy?: string,
+): Promise<PolicyCreateResult> {
+  const policy = parsePolicy(filePath);
+  const validation = validator.validate(policy);
+
+  let created: Policy | null = null;
+  let success = false;
+
+  if (validation.valid) {
+    created = await policyRepository.create(policy, createdBy);
+    success = true;
+  }
+
+  const synthesis = buildPolicyCreateSynthesis(
+    created || policy,
+    validation.errors,
+    success,
+  );
+
+  // Elevate risk for production targets
+  if (isProductionTarget(policy.metadata.namespace)) {
+    elevateRiskForProduction(synthesis);
+  }
+
+  return {
+    policy_id: created?.metadata.id || policy.metadata.id,
+    version: created?.metadata.version || policy.metadata.version,
+    status: created?.status || policy.status,
+    rules_count: policy.rules.length,
+    validation_errors: validation.errors,
+    synthesis,
+  };
+}
+
+/**
+ * Update an existing policy
+ */
+export async function updatePolicy(
+  policyId: string,
+  filePath: string,
+): Promise<PolicyEditResult> {
+  const existingPolicy = await policyRepository.findById(policyId);
+  if (!existingPolicy) {
+    throw new Error(`Policy not found: ${policyId}`);
+  }
+
+  const updates = parsePolicy(filePath);
+  const validation = validator.validate(updates);
+
+  let updated: Policy | null = null;
+  let success = false;
+  const changesApplied: string[] = [];
+
+  if (validation.valid) {
+    updated = await policyRepository.update(policyId, updates);
+    success = true;
+
+    // Track what changed
+    if (updates.rules) {
+      changesApplied.push('rules');
+    }
+    if (updates.metadata) {
+      changesApplied.push('metadata');
+    }
+    if (updates.status) {
+      changesApplied.push('status');
+    }
+  }
+
+  const synthesis = buildPolicyEditSynthesis(
+    updated || updates,
+    validation.errors,
+    success,
+  );
+
+  if (isProductionTarget((updated || updates).metadata.namespace)) {
+    elevateRiskForProduction(synthesis);
+  }
+
+  return {
+    policy_id: policyId,
+    version: updated?.metadata.version || updates.metadata?.version || existingPolicy.metadata.version,
+    previous_version: existingPolicy.metadata.version,
+    changes_applied: changesApplied,
+    validation_errors: validation.errors,
+    synthesis,
+  };
+}
+
+/**
+ * Toggle policy status (enable/disable/deprecate)
+ * Includes rollback instructions in synthesis for enable/disable operations
+ */
+export async function togglePolicyStatus(
+  policyId: string,
+  newStatus: PolicyStatus,
+): Promise<PolicyToggleResult> {
+  const existingPolicy = await policyRepository.findById(policyId);
+  if (!existingPolicy) {
+    throw new Error(`Policy not found: ${policyId}`);
+  }
+
+  const previousStatus = existingPolicy.status;
+  const updated = await policyRepository.update(policyId, { status: newStatus });
+
+  // Get existing policies for conflict analysis
+  const existingPolicies = await policyRepository.findActive();
+
+  // Determine operation type for rollback instructions
+  const isEnabling = newStatus === PolicyStatus.ACTIVE && previousStatus !== PolicyStatus.ACTIVE;
+  const isDisabling = newStatus !== PolicyStatus.ACTIVE && previousStatus === PolicyStatus.ACTIVE;
+  const operationType = isEnabling ? 'enable' : isDisabling ? 'disable' : 'edit';
+
+  // Build decision packet with rollback instructions
+  const decisionPacket = buildDecisionPacket(updated, existingPolicies, {
+    includeRollback: true,
+    previousStatus,
+    operationType,
+  });
+
+  const synthesis = buildPolicyToggleSynthesis(
+    updated,
+    previousStatus,
+    newStatus,
+  );
+
+  if (isProductionTarget(updated.metadata.namespace)) {
+    elevateRiskForProduction(synthesis);
+  }
+
+  // Enhance rationale with rollback info for enable/disable
+  if (decisionPacket.rollback_instructions) {
+    synthesis.rationale = `${synthesis.rationale}. Rollback: ${decisionPacket.rollback_instructions.rollback_command}`;
+  }
+
+  return {
+    policy_id: policyId,
+    previous_status: previousStatus,
+    new_status: newStatus,
+    affected_rules: updated.rules.filter(r => r.enabled !== false).length,
+    decision_packet: decisionPacket,
+    synthesis,
+  };
+}
+
+/**
+ * Delete a policy
+ */
+export async function deletePolicy(policyId: string): Promise<PolicyDeleteResult> {
+  const existingPolicy = await policyRepository.findById(policyId);
+  if (!existingPolicy) {
+    throw new Error(`Policy not found: ${policyId}`);
+  }
+
+  await policyRepository.delete(policyId);
+
+  const synthesis = buildExecutiveSummary(
+    {
+      environment: determineEnvironment(existingPolicy),
+      timestamp: new Date().toISOString(),
+      version: existingPolicy.metadata.version,
+      commit_sha: process.env['GIT_SHA'],
+    },
+    {
+      success_rate: 1.0,
+      failed_iterations: 0,
+      blocking_issues: [],
+    },
+    ['policy lookup', 'deletion', 'cache invalidation'],
+  );
+
+  // Deleting production policies is high risk
+  if (isProductionTarget(existingPolicy.metadata.namespace)) {
+    synthesis.risk_level = 'high';
+    synthesis.recommendation = 'DEFER';
+    synthesis.rationale = `[Production Policy Deletion] Policy ${existingPolicy.metadata.name} removed from production environment`;
+  }
+
+  return {
+    policy_id: policyId,
+    deleted: true,
+    synthesis,
+  };
+}
+
+/**
+ * Validate a policy without persisting
+ */
+export async function validatePolicy(filePath: string): Promise<{
+  valid: boolean;
+  policy: Policy;
+  errors: string[];
+  synthesis: ExecutiveSummary;
+}> {
+  const policy = parsePolicy(filePath);
+  const validation = validator.validate(policy);
+
+  const blockingIssues = extractBlockingIssues(policy, validation.errors);
+
+  const synthesis = buildExecutiveSummary(
+    {
+      environment: determineEnvironment(policy),
+      timestamp: new Date().toISOString(),
+      version: policy.metadata.version,
+      commit_sha: process.env['GIT_SHA'],
+    },
+    {
+      success_rate: calculateSuccessRate(validation.errors, policy.rules.length),
+      failed_iterations: validation.errors.length,
+      blocking_issues: blockingIssues,
+    },
+    ['policy parsing', 'schema validation', 'rule validation'],
+  );
+
+  return {
+    valid: validation.valid,
+    policy,
+    errors: validation.errors,
+    synthesis,
+  };
+}
+
+/**
+ * Get policy with synthesis analysis
+ */
+export async function analyzePolicy(policyId: string): Promise<{
+  policy: Policy;
+  synthesis: ExecutiveSummary;
+}> {
+  const policy = await policyRepository.findById(policyId);
+  if (!policy) {
+    throw new Error(`Policy not found: ${policyId}`);
+  }
+
+  const validation = validator.validate(policy);
+  const blockingIssues = extractBlockingIssues(policy, validation.errors);
+
+  const synthesis = buildExecutiveSummary(
+    {
+      environment: determineEnvironment(policy),
+      timestamp: new Date().toISOString(),
+      version: policy.metadata.version,
+    },
+    {
+      success_rate: validation.valid ? 1.0 : calculateSuccessRate(validation.errors, policy.rules.length),
+      failed_iterations: validation.errors.length,
+      blocking_issues: blockingIssues,
+    },
+    ['policy retrieval', 'validation', 'analysis'],
+  );
+
+  // Add security risk analysis
+  const securityRisks = analyzeSecurityRisks(policy);
+  if (securityRisks.length > 0) {
+    synthesis.iteration_metrics.blocking_issues.push(...securityRisks);
+    if (securityRisks.some(r => r.severity === 'critical')) {
+      synthesis.risk_level = 'critical';
+      synthesis.recommendation = 'REJECT';
+    } else if (securityRisks.some(r => r.severity === 'high')) {
+      synthesis.risk_level = 'high';
+      synthesis.recommendation = 'DEFER';
+    }
+    synthesis.rationale = `Security risks detected: ${securityRisks.length}. ${synthesis.rationale}`;
+  }
+
+  return {
+    policy,
+    synthesis,
+  };
+}
+
+/**
+ * Analyze security risks in a policy
+ */
+function analyzeSecurityRisks(policy: Policy): Array<{
+  type: 'security_risk';
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  description: string;
+  rule_id?: string;
+}> {
+  const risks: Array<{
+    type: 'security_risk';
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    description: string;
+    rule_id?: string;
+  }> = [];
+
+  for (const rule of policy.rules) {
+    // Check for overly permissive rules
+    if (rule.action.decision === DecisionType.ALLOW) {
+      if (!rule.condition.field && !rule.condition.conditions) {
+        risks.push({
+          type: 'security_risk',
+          severity: 'high',
+          description: `Rule ${rule.name} allows all without conditions`,
+          rule_id: rule.id,
+        });
+      }
+    }
+
+    // Check for disabled security rules
+    if (rule.enabled === false && rule.action.decision === DecisionType.DENY) {
+      risks.push({
+        type: 'security_risk',
+        severity: 'medium',
+        description: `Security deny rule ${rule.name} is disabled`,
+        rule_id: rule.id,
+      });
+    }
+  }
+
+  return risks;
+}
+
+/**
+ * Dry-run policy evaluation without state changes
+ * Returns violation predictions and enforcement impact projection
+ */
+export async function dryRunPolicy(filePath: string): Promise<PolicyDryRunResult> {
+  const policy = parsePolicy(filePath);
+  const validation = validator.validate(policy);
+
+  // Get existing policies for conflict analysis
+  const existingPolicies = await policyRepository.findActive();
+
+  // Build comprehensive dry-run synthesis
+  const {
+    canApply,
+    violationPredictions,
+    decisionPacket,
+    synthesis,
+  } = buildPolicyDryRunSynthesis(policy, validation.errors, existingPolicies);
+
+  // Apply production risk elevation
+  if (isProductionTarget(policy.metadata.namespace)) {
+    elevateRiskForProduction(synthesis);
+  }
+
+  return {
+    policy_id: policy.metadata.id,
+    can_apply: canApply,
+    validation_errors: validation.errors,
+    violation_predictions: violationPredictions,
+    decision_packet: decisionPacket,
+    synthesis,
+  };
+}
+
+/**
+ * Enable a policy (convenience wrapper for togglePolicyStatus)
+ */
+export async function enablePolicy(policyId: string): Promise<PolicyToggleResult> {
+  return togglePolicyStatus(policyId, PolicyStatus.ACTIVE);
+}
+
+/**
+ * Disable a policy (convenience wrapper for togglePolicyStatus)
+ */
+export async function disablePolicy(policyId: string): Promise<PolicyToggleResult> {
+  return togglePolicyStatus(policyId, PolicyStatus.DRAFT);
+}
+
+export default {
+  createPolicy,
+  updatePolicy,
+  togglePolicyStatus,
+  enablePolicy,
+  disablePolicy,
+  deletePolicy,
+  validatePolicy,
+  analyzePolicy,
+  dryRunPolicy,
+};

package/dist/bundled-agents/policy-engine-agents/src/core/engine/policy-engine.ts

@@ -0,0 +1,263 @@
+/**
+ * Policy Engine - Main evaluation engine
+ */
+import {
+  Policy,
+  EvaluationContext,
+  PolicyDecision,
+  DecisionType,
+  EvaluationTrace,
+  ConditionEvaluation,
+  PolicyEvaluationRequest,
+  PolicyEvaluationResponse,
+} from '../../types/policy';
+import { ConditionEvaluator } from '../evaluator/condition-evaluator';
+import { TokenCounter, PIIDetector, CostCalculator } from '../primitives';
+import { PolicyEvaluationError } from '@utils/errors';
+import logger from '@utils/logger';
+import { v4 as uuidv4 } from 'uuid';
+
+export class PolicyEngine {
+  private conditionEvaluator: ConditionEvaluator;
+  private tokenCounter: TokenCounter;
+  private piiDetector: PIIDetector;
+  private costCalculator: CostCalculator;
+  private policies: Map<string, Policy>;
+
+  constructor(policies: Policy[] = []) {
+    this.conditionEvaluator = new ConditionEvaluator();
+    this.tokenCounter = new TokenCounter();
+    this.piiDetector = new PIIDetector();
+    this.costCalculator = new CostCalculator();
+    this.policies = new Map();
+
+    // Load initial policies
+    for (const policy of policies) {
+      this.addPolicy(policy);
+    }
+  }
+
+  /**
+   * Add a policy to the engine
+   */
+  addPolicy(policy: Policy): void {
+    if (policy.status === 'active') {
+      this.policies.set(policy.metadata.id, policy);
+      logger.info({ policyId: policy.metadata.id }, 'Policy added to engine');
+    }
+  }
+
+  /**
+   * Remove a policy from the engine
+   */
+  removePolicy(policyId: string): void {
+    this.policies.delete(policyId);
+    logger.info({ policyId }, 'Policy removed from engine');
+  }
+
+  /**
+   * Update a policy in the engine
+   */
+  updatePolicy(policy: Policy): void {
+    this.policies.set(policy.metadata.id, policy);
+    logger.info({ policyId: policy.metadata.id }, 'Policy updated in engine');
+  }
+
+  /**
+   * Get all active policies (sorted by priority, highest first)
+   */
+  getPolicies(): Policy[] {
+    return Array.from(this.policies.values()).sort(
+      (a, b) => (b.metadata.priority || 0) - (a.metadata.priority || 0),
+    );
+  }
+
+  /**
+   * Evaluate a request against all policies
+   */
+  async evaluate(request: PolicyEvaluationRequest): Promise<PolicyEvaluationResponse> {
+    const startTime = performance.now();
+    const { requestId = uuidv4(), context, policies: policyIds, dryRun = false, trace = false } = request;
+
+    logger.info({ requestId, dryRun, trace }, 'Starting policy evaluation');
+
+    try {
+      // Enrich context with calculated fields
+      const enrichedContext = await this.enrichContext(context);
+
+      // Get policies to evaluate
+      const policiesToEvaluate = policyIds
+        ? policyIds.map((id) => this.policies.get(id)).filter((p): p is Policy => p !== undefined)
+        : Array.from(this.policies.values());
+
+      // Sort policies by priority (higher priority first)
+      policiesToEvaluate.sort((a, b) => (b.metadata.priority || 0) - (a.metadata.priority || 0));
+
+      // Evaluate policies
+      const decision = await this.evaluatePolicies(
+        policiesToEvaluate,
+        enrichedContext,
+        trace,
+      );
+
+      const evaluationTimeMs = performance.now() - startTime;
+
+      logger.info(
+        {
+          requestId,
+          decision: decision.decision,
+          evaluationTimeMs,
+          matchedPolicies: decision.matchedPolicies.length,
+        },
+        'Policy evaluation completed',
+      );
+
+      return {
+        requestId,
+        decision: {
+          ...decision,
+          evaluationTimeMs,
+        },
+        timestamp: Date.now(),
+        cached: false,
+      };
+    } catch (error) {
+      logger.error({ requestId, error }, 'Policy evaluation failed');
+      throw new PolicyEvaluationError(
+        `Evaluation failed: ${error instanceof Error ? error.message : String(error)}`,
+        { requestId },
+      );
+    }
+  }
+
+  /**
+   * Enrich context with calculated fields
+   */
+  private async enrichContext(context: EvaluationContext): Promise<EvaluationContext> {
+    const enriched = { ...context };
+
+    // Add token count if prompt is provided
+    if (context.llm?.prompt) {
+      const { tokens } = this.tokenCounter.estimateTokens(
+        context.llm.prompt,
+        context.llm.model,
+      );
+      enriched.llm = {
+        ...context.llm,
+        estimatedTokens: tokens,
+      } as any;
+    }
+
+    // Add PII detection
+    if (context.llm?.prompt) {
+      const piiMatches = this.piiDetector.detectPII(context.llm.prompt);
+      enriched.llm = {
+        ...enriched.llm!,
+        containsPII: piiMatches.length > 0,
+        piiTypes: [...new Set(piiMatches.map((m) => m.type))],
+      } as any;
+    }
+
+    // Add cost estimate
+    if (context.llm?.provider && context.llm?.model && context.llm?.prompt) {
+      const costEstimate = this.costCalculator.estimateCostFromText(
+        context.llm.provider,
+        context.llm.model,
+        context.llm.prompt,
+        context.llm.maxTokens || 500,
+      );
+      enriched.llm = {
+        ...enriched.llm!,
+        estimatedCost: costEstimate.totalCost,
+      } as any;
+    }
+
+    return enriched;
+  }
+
+  /**
+   * Evaluate multiple policies and aggregate decisions
+   */
+  private async evaluatePolicies(
+    policies: Policy[],
+    context: EvaluationContext,
+    trace: boolean,
+  ): Promise<PolicyDecision> {
+    const matchedPolicies: string[] = [];
+    const matchedRules: string[] = [];
+    const traces: EvaluationTrace[] = [];
+    const modifications: Record<string, any> = {};
+
+    let finalDecision: DecisionType = DecisionType.ALLOW;
+    let finalReason: string | undefined;
+
+    // Evaluate each policy
+    for (const policy of policies) {
+      for (const rule of policy.rules) {
+        if (!rule.enabled) continue;
+
+        const conditionResult = this.conditionEvaluator.evaluate(rule.condition, context);
+
+        if (trace) {
+          const conditionEval: ConditionEvaluation = {
+            condition: rule.condition,
+            result: conditionResult.result,
+            evaluationTimeMs: conditionResult.evaluationTimeMs,
+            details: conditionResult.details,
+          };
+
+          traces.push({
+            policyId: policy.metadata.id,
+            ruleId: rule.id,
+            conditionEvaluations: [conditionEval],
+            finalDecision: rule.action.decision,
+            timestamp: Date.now(),
+          });
+        }
+
+        // If condition matches, record it
+        if (conditionResult.result) {
+          matchedPolicies.push(policy.metadata.id);
+          matchedRules.push(rule.id);
+
+          // Priority: DENY > MODIFY > WARN > ALLOW
+          if (rule.action.decision === DecisionType.DENY) {
+            finalDecision = DecisionType.DENY;
+            finalReason = rule.action.reason;
+            break; // DENY is highest priority, stop evaluation
+          } else if (rule.action.decision === DecisionType.MODIFY) {
+            finalDecision = DecisionType.MODIFY;
+            finalReason = rule.action.reason;
+            Object.assign(modifications, rule.action.modifications || {});
+          } else if (rule.action.decision === DecisionType.WARN) {
+            finalDecision = DecisionType.WARN;
+            finalReason = rule.action.reason;
+          }
+        }
+      }
+
+      // Break early if DENY decision made
+      if (finalDecision === DecisionType.DENY) {
+        break;
+      }
+    }
+
+    return {
+      decision: finalDecision,
+      allowed: finalDecision !== DecisionType.DENY,
+      reason: finalReason,
+      matchedPolicies: [...new Set(matchedPolicies)],
+      matchedRules: [...new Set(matchedRules)],
+      evaluationTimeMs: 0, // Will be set by caller
+      modifications: Object.keys(modifications).length > 0 ? modifications : undefined,
+      trace: trace && traces.length > 0 ? traces[0] : undefined,
+    };
+  }
+
+  /**
+   * Simulate policy evaluation (dry run)
+   */
+  async simulate(request: PolicyEvaluationRequest): Promise<PolicyEvaluationResponse> {
+    return this.evaluate({ ...request, dryRun: true, trace: true });
+  }
+}