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

package/dist/bundled-agents/policy-engine-agents/src/synthesis/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Executive Synthesis Module
+ * Provides executive summaries for policy operations
+ */
+
+export * from './types';
+export * from './builder';

package/dist/bundled-agents/policy-engine-agents/src/synthesis/types.ts

@@ -0,0 +1,177 @@
+/**
+ * Executive Synthesis Types
+ * Types for policy validation executive summaries
+ */
+
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+export type Recommendation = 'APPROVE' | 'DEFER' | 'REJECT';
+
+export interface DeployReference {
+  environment: string;
+  timestamp: string;
+  version?: string;
+  commit_sha?: string;
+}
+
+export interface IterationMetrics {
+  success_rate: number;
+  failed_iterations: number;
+  blocking_issues: BlockingIssue[];
+  steps_executed: string[];
+}
+
+export interface BlockingIssue {
+  type: 'deny_action' | 'conflicting_priorities' | 'missing_conditions' | 'validation_error' | 'security_risk';
+  severity: RiskLevel;
+  description: string;
+  location?: string;
+  rule_id?: string;
+}
+
+export interface ExecutiveSummary {
+  deploy_reference: DeployReference;
+  iteration_metrics: IterationMetrics;
+  risk_level: RiskLevel;
+  recommendation: Recommendation;
+  rationale: string;
+}
+
+export interface PolicyCreateResult {
+  policy_id: string;
+  version: string;
+  status: string;
+  rules_count: number;
+  validation_errors: string[];
+  synthesis?: ExecutiveSummary;
+}
+
+export interface PolicyEditResult {
+  policy_id: string;
+  version: string;
+  previous_version: string;
+  changes_applied: string[];
+  validation_errors: string[];
+  synthesis?: ExecutiveSummary;
+}
+
+export interface PolicyToggleResult {
+  policy_id: string;
+  previous_status: string;
+  new_status: string;
+  affected_rules: number;
+  /** Decision packet with conflict analysis and enforcement impact */
+  decision_packet?: DecisionPacket;
+  synthesis?: ExecutiveSummary;
+}
+
+export interface PolicyDeleteResult {
+  policy_id: string;
+  deleted: boolean;
+  synthesis?: ExecutiveSummary;
+}
+
+/**
+ * Decision Packet - Core synthesis output for policy operations
+ * Contains conflict analysis, resource impact, and enforcement projection
+ */
+export interface DecisionPacket {
+  /** Policy conflict analysis */
+  conflict_analysis: ConflictAnalysis;
+  /** Count of resources affected by this policy operation */
+  affected_resource_count: number;
+  /** Enforcement impact projection */
+  enforcement_impact: EnforcementImpact;
+  /** Rollback instructions (for enable/disable operations) */
+  rollback_instructions?: RollbackInstructions;
+}
+
+export interface ConflictAnalysis {
+  /** Whether conflicts were detected */
+  has_conflicts: boolean;
+  /** List of conflicting rule pairs */
+  conflicts: PolicyConflict[];
+  /** Severity of most severe conflict */
+  max_severity: RiskLevel;
+  /** Summary description */
+  summary: string;
+}
+
+export interface PolicyConflict {
+  /** Source rule ID */
+  rule_a_id: string;
+  /** Conflicting rule ID */
+  rule_b_id: string;
+  /** Type of conflict */
+  conflict_type: 'priority' | 'decision' | 'condition_overlap' | 'circular_reference';
+  /** Description of the conflict */
+  description: string;
+  /** Severity level */
+  severity: RiskLevel;
+  /** Resolution suggestion */
+  resolution?: string;
+}
+
+export interface EnforcementImpact {
+  /** Predicted number of requests that would be ALLOWED */
+  allowed_predictions: number;
+  /** Predicted number of requests that would be DENIED */
+  denied_predictions: number;
+  /** Predicted number of requests that would be WARNED */
+  warned_predictions: number;
+  /** Predicted number of requests that would be MODIFIED */
+  modified_predictions: number;
+  /** Confidence level of predictions (0-1) */
+  confidence: number;
+  /** Impact assessment */
+  impact_level: 'minimal' | 'moderate' | 'significant' | 'critical';
+  /** Human-readable impact description */
+  description: string;
+}
+
+export interface RollbackInstructions {
+  /** Previous status before the operation */
+  previous_status: string;
+  /** Command to rollback this operation */
+  rollback_command: string;
+  /** Steps to verify rollback success */
+  verification_steps: string[];
+  /** Estimated time window for safe rollback */
+  safe_rollback_window: string;
+  /** Warnings about rollback side effects */
+  warnings: string[];
+}
+
+/**
+ * Policy Dry-Run Result
+ * Evaluates policy impact against current state without making changes
+ */
+export interface PolicyDryRunResult {
+  policy_id: string;
+  /** Policy is valid and could be applied */
+  can_apply: boolean;
+  /** Validation errors that would block application */
+  validation_errors: string[];
+  /** Predicted violations based on current traffic patterns */
+  violation_predictions: ViolationPrediction[];
+  /** Decision packet with full analysis */
+  decision_packet: DecisionPacket;
+  /** Executive synthesis */
+  synthesis: ExecutiveSummary;
+}
+
+export interface ViolationPrediction {
+  /** Rule that would trigger */
+  rule_id: string;
+  /** Rule name */
+  rule_name: string;
+  /** Predicted action (DENY, WARN, MODIFY) */
+  predicted_action: 'DENY' | 'WARN' | 'MODIFY';
+  /** Estimated frequency of this violation */
+  estimated_frequency: 'rare' | 'occasional' | 'frequent' | 'very_frequent';
+  /** Estimated number of requests affected per hour */
+  estimated_affected_requests_per_hour: number;
+  /** Sample conditions that would trigger this rule */
+  sample_trigger_conditions: string[];
+  /** Risk level of this violation pattern */
+  risk_level: RiskLevel;
+}

package/dist/bundled-agents/policy-engine-agents/src/types/config.ts

@@ -0,0 +1,80 @@
+/**
+ * Configuration Type Definitions
+ */
+
+export interface DatabaseConfig {
+  url: string;
+  poolMin?: number;
+  poolMax?: number;
+  ssl?: boolean;
+}
+
+export interface RedisConfig {
+  url: string;
+  password?: string;
+  db?: number;
+  keyPrefix?: string;
+}
+
+export interface CacheConfig {
+  ttl: number; // seconds
+  maxSize: number;
+  enabled?: boolean;
+}
+
+export interface ServerConfig {
+  port: number;
+  grpcPort: number;
+  host?: string;
+}
+
+export interface SecurityConfig {
+  jwtSecret: string;
+  jwtExpiresIn: string;
+  apiKeyHeader?: string;
+}
+
+export interface RateLimitConfig {
+  windowMs: number;
+  maxRequests: number;
+}
+
+export interface ObservabilityConfig {
+  metricsPort: number;
+  metricsPath: string;
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+  traceEnabled: boolean;
+}
+
+export interface IntegrationConfig {
+  llmShieldUrl?: string;
+  llmCostOpsUrl?: string;
+  llmGovernanceUrl?: string;
+  llmEdgeAgentUrl?: string;
+  // Phase 2B: Upstream consumption adapters
+  llmSchemaRegistryUrl?: string;
+  llmConfigManagerUrl?: string;
+  llmObservatoryUrl?: string;
+  // RuVector Service for DecisionEvent persistence
+  ruvectorServiceUrl?: string;
+}
+
+export interface PerformanceConfig {
+  maxPolicySizeMB: number;
+  maxEvaluationTimeMs: number;
+  enableParallelEvaluation: boolean;
+}
+
+export interface AppConfig {
+  nodeEnv: string;
+  database: DatabaseConfig;
+  redis: RedisConfig;
+  cache: CacheConfig;
+  server: ServerConfig;
+  security: SecurityConfig;
+  rateLimit: RateLimitConfig;
+  observability: ObservabilityConfig;
+  integrations: IntegrationConfig;
+  performance: PerformanceConfig;
+  environment?: string;
+}

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

@@ -0,0 +1,167 @@
+/**
+ * Core Policy Type Definitions
+ * Following the SPARC specification for LLM-Policy-Engine
+ */
+
+export enum PolicyStatus {
+  ACTIVE = 'active',
+  DRAFT = 'draft',
+  DEPRECATED = 'deprecated',
+}
+
+export enum DecisionType {
+  ALLOW = 'allow',
+  DENY = 'deny',
+  WARN = 'warn',
+  MODIFY = 'modify',
+}
+
+export enum ConditionOperator {
+  EQUALS = 'eq',
+  NOT_EQUALS = 'ne',
+  GREATER_THAN = 'gt',
+  GREATER_THAN_OR_EQUAL = 'gte',
+  LESS_THAN = 'lt',
+  LESS_THAN_OR_EQUAL = 'lte',
+  IN = 'in',
+  NOT_IN = 'not_in',
+  CONTAINS = 'contains',
+  NOT_CONTAINS = 'not_contains',
+  MATCHES = 'matches',
+  AND = 'and',
+  OR = 'or',
+  NOT = 'not',
+}
+
+export interface PolicyMetadata {
+  id: string;
+  name: string;
+  description?: string;
+  version: string;
+  namespace: string;
+  tags?: string[];
+  createdAt?: Date;
+  updatedAt?: Date;
+  createdBy?: string;
+  priority?: number;
+}
+
+export interface Condition {
+  operator: ConditionOperator;
+  field?: string;
+  value?: any;
+  conditions?: Condition[]; // For nested AND/OR/NOT
+}
+
+export interface Action {
+  decision: DecisionType;
+  reason?: string;
+  metadata?: Record<string, any>;
+  modifications?: Record<string, any>; // For MODIFY decisions
+}
+
+export interface PolicyRule {
+  id: string;
+  name: string;
+  description?: string;
+  condition: Condition;
+  action: Action;
+  enabled?: boolean;
+}
+
+export interface Policy {
+  metadata: PolicyMetadata;
+  rules: PolicyRule[];
+  status: PolicyStatus;
+}
+
+export interface EvaluationContext {
+  llm?: {
+    provider: string;
+    model: string;
+    prompt?: string;
+    maxTokens?: number;
+    temperature?: number;
+    functions?: any[];
+  };
+  user?: {
+    id: string;
+    email?: string;
+    roles?: string[];
+    permissions?: string[];
+  };
+  team?: {
+    id: string;
+    name?: string;
+    tier?: string;
+  };
+  project?: {
+    id: string;
+    name?: string;
+    environment?: string;
+  };
+  request?: {
+    id: string;
+    timestamp: number;
+    ipAddress?: string;
+    userAgent?: string;
+  };
+  metadata?: Record<string, any>;
+}
+
+export interface PolicyDecision {
+  decision: DecisionType;
+  allowed: boolean;
+  reason?: string;
+  matchedPolicies: string[];
+  matchedRules: string[];
+  evaluationTimeMs: number;
+  modifications?: Record<string, any>;
+  metadata?: Record<string, any>;
+  trace?: EvaluationTrace;
+}
+
+export interface EvaluationTrace {
+  policyId: string;
+  ruleId: string;
+  conditionEvaluations: ConditionEvaluation[];
+  finalDecision: DecisionType;
+  timestamp: number;
+}
+
+export interface ConditionEvaluation {
+  condition: Condition;
+  result: boolean;
+  evaluationTimeMs: number;
+  details?: string;
+}
+
+export interface PolicyEvaluationRequest {
+  requestId: string;
+  context: EvaluationContext;
+  policies?: string[]; // Optional: specific policies to evaluate
+  dryRun?: boolean;
+  trace?: boolean;
+}
+
+export interface PolicyEvaluationResponse {
+  requestId: string;
+  decision: PolicyDecision;
+  timestamp: number;
+  cached?: boolean;
+}
+
+export interface CostEstimate {
+  provider: string;
+  model: string;
+  estimatedTokens: number;
+  estimatedCost: number;
+  currency: string;
+}
+
+export interface SecurityViolation {
+  type: 'prompt_injection' | 'pii_leakage' | 'data_exfiltration' | 'toxic_content';
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  details: string;
+  location?: string;
+}

package/dist/bundled-agents/policy-engine-agents/src/utils/config.ts

@@ -0,0 +1,78 @@
+/**
+ * Configuration loader
+ */
+import dotenv from 'dotenv';
+import { AppConfig } from '../types/config';
+
+dotenv.config();
+
+export const config: AppConfig = {
+  nodeEnv: process.env.NODE_ENV || 'development',
+
+  database: {
+    url: process.env.DATABASE_URL || 'postgresql://postgres:postgres@localhost:5432/llm_policy_engine',
+    poolMin: parseInt(process.env.DATABASE_POOL_MIN || '2', 10),
+    poolMax: parseInt(process.env.DATABASE_POOL_MAX || '10', 10),
+    ssl: process.env.DATABASE_SSL === 'true',
+  },
+
+  redis: {
+    url: process.env.REDIS_URL || 'redis://localhost:6379',
+    password: process.env.REDIS_PASSWORD,
+    db: parseInt(process.env.REDIS_DB || '0', 10),
+    keyPrefix: process.env.REDIS_KEY_PREFIX || 'llm-policy:',
+  },
+
+  cache: {
+    ttl: parseInt(process.env.CACHE_TTL || '300', 10),
+    maxSize: parseInt(process.env.CACHE_MAX_SIZE || '10000', 10),
+    enabled: process.env.CACHE_ENABLED !== 'false',
+  },
+
+  server: {
+    port: parseInt(process.env.PORT || '3000', 10),
+    grpcPort: parseInt(process.env.GRPC_PORT || '50051', 10),
+    host: process.env.HOST || '0.0.0.0',
+  },
+
+  security: {
+    jwtSecret: process.env.JWT_SECRET || 'your-secret-key-change-in-production',
+    jwtExpiresIn: process.env.JWT_EXPIRES_IN || '24h',
+    apiKeyHeader: process.env.API_KEY_HEADER || 'X-API-Key',
+  },
+
+  rateLimit: {
+    windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS || '60000', 10),
+    maxRequests: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS || '100', 10),
+  },
+
+  observability: {
+    metricsPort: parseInt(process.env.METRICS_PORT || '9090', 10),
+    metricsPath: process.env.METRICS_PATH || '/metrics',
+    logLevel: (process.env.LOG_LEVEL || 'info') as any,
+    traceEnabled: process.env.TRACE_ENABLED === 'true',
+  },
+
+  integrations: {
+    llmShieldUrl: process.env.LLM_SHIELD_URL,
+    llmCostOpsUrl: process.env.LLM_COSTOPS_URL,
+    llmGovernanceUrl: process.env.LLM_GOVERNANCE_URL,
+    llmEdgeAgentUrl: process.env.LLM_EDGE_AGENT_URL,
+    // Phase 2B: Upstream consumption adapters
+    llmSchemaRegistryUrl: process.env.LLM_SCHEMA_REGISTRY_URL,
+    llmConfigManagerUrl: process.env.LLM_CONFIG_MANAGER_URL,
+    llmObservatoryUrl: process.env.LLM_OBSERVATORY_URL,
+    // RuVector Service for DecisionEvent persistence
+    ruvectorServiceUrl: process.env.RUVECTOR_SERVICE_URL,
+  },
+
+  environment: process.env.ENVIRONMENT || process.env.NODE_ENV || 'development',
+
+  performance: {
+    maxPolicySizeMB: parseInt(process.env.MAX_POLICY_SIZE_MB || '10', 10),
+    maxEvaluationTimeMs: parseInt(process.env.MAX_EVALUATION_TIME_MS || '100', 10),
+    enableParallelEvaluation: process.env.ENABLE_PARALLEL_EVALUATION !== 'false',
+  },
+};
+
+export default config;

package/dist/bundled-agents/policy-engine-agents/src/utils/errors.ts

@@ -0,0 +1,79 @@
+/**
+ * Custom Error Classes
+ */
+
+export class PolicyEngineError extends Error {
+  constructor(
+    message: string,
+    public code: string = 'POLICY_ENGINE_ERROR',
+    public statusCode: number = 500,
+    public details?: any,
+  ) {
+    super(message);
+    this.name = 'PolicyEngineError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class PolicyParseError extends PolicyEngineError {
+  constructor(message: string, details?: any) {
+    super(message, 'POLICY_PARSE_ERROR', 400, details);
+    this.name = 'PolicyParseError';
+  }
+}
+
+export class PolicyValidationError extends PolicyEngineError {
+  constructor(message: string, details?: any) {
+    super(message, 'POLICY_VALIDATION_ERROR', 400, details);
+    this.name = 'PolicyValidationError';
+  }
+}
+
+export class PolicyEvaluationError extends PolicyEngineError {
+  constructor(message: string, details?: any) {
+    super(message, 'POLICY_EVALUATION_ERROR', 500, details);
+    this.name = 'PolicyEvaluationError';
+  }
+}
+
+export class PolicyNotFoundError extends PolicyEngineError {
+  constructor(policyId: string) {
+    super(`Policy not found: ${policyId}`, 'POLICY_NOT_FOUND', 404, { policyId });
+    this.name = 'PolicyNotFoundError';
+  }
+}
+
+export class CacheError extends PolicyEngineError {
+  constructor(message: string, details?: any) {
+    super(message, 'CACHE_ERROR', 500, details);
+    this.name = 'CacheError';
+  }
+}
+
+export class DatabaseError extends PolicyEngineError {
+  constructor(message: string, details?: any) {
+    super(message, 'DATABASE_ERROR', 500, details);
+    this.name = 'DatabaseError';
+  }
+}
+
+export class AuthenticationError extends PolicyEngineError {
+  constructor(message: string = 'Authentication failed') {
+    super(message, 'AUTHENTICATION_ERROR', 401);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class AuthorizationError extends PolicyEngineError {
+  constructor(message: string = 'Unauthorized access') {
+    super(message, 'AUTHORIZATION_ERROR', 403);
+    this.name = 'AuthorizationError';
+  }
+}
+
+export class RateLimitError extends PolicyEngineError {
+  constructor(message: string = 'Rate limit exceeded') {
+    super(message, 'RATE_LIMIT_ERROR', 429);
+    this.name = 'RateLimitError';
+  }
+}

package/dist/bundled-agents/policy-engine-agents/src/utils/logger.ts

@@ -0,0 +1,32 @@
+/**
+ * Logger utility using Pino
+ */
+import pino from 'pino';
+import { config } from './config';
+
+const logger = pino({
+  level: config.observability.logLevel,
+  transport:
+    config.nodeEnv === 'development'
+      ? {
+          target: 'pino-pretty',
+          options: {
+            colorize: true,
+            translateTime: 'SYS:standard',
+            ignore: 'pid,hostname',
+          },
+        }
+      : undefined,
+  formatters: {
+    level: (label) => {
+      return { level: label };
+    },
+  },
+  timestamp: pino.stdTimeFunctions.isoTime,
+});
+
+export default logger;
+
+export const createChildLogger = (context: Record<string, any>) => {
+  return logger.child(context);
+};