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

package/dist/bundled-agents/analytics-hub-agents/src/compliance/gdpr.ts

@@ -0,0 +1,330 @@
+/**
+ * GDPR Compliance Features
+ * Implements Right to Access, Right to Erasure, Data Portability, Consent Management
+ */
+
+import { auditLogger, AuditAction, AuditSeverity } from '../auth/audit';
+
+export interface GDPRDataExportRequest {
+  userId: string;
+  requestedBy: string;
+  requestedAt: Date;
+  format: 'json' | 'csv' | 'xml';
+  includeEvents: boolean;
+  includeMetrics: boolean;
+  includeAuditLogs: boolean;
+}
+
+export interface GDPRDataDeletionRequest {
+  userId: string;
+  requestedBy: string;
+  requestedAt: Date;
+  reason: string;
+  retentionOverride?: boolean; // For legal hold
+}
+
+export interface UserConsent {
+  userId: string;
+  consentType: string;
+  granted: boolean;
+  grantedAt?: Date;
+  revokedAt?: Date;
+  ipAddress: string;
+  userAgent: string;
+}
+
+export class GDPRComplianceManager {
+  /**
+   * Request data export (Right to Access - GDPR Article 15)
+   */
+  async requestDataExport(request: GDPRDataExportRequest): Promise<{
+    requestId: string;
+    estimatedCompletionTime: Date;
+  }> {
+    const requestId = this.generateRequestId();
+
+    // Log audit event
+    await auditLogger.log({
+      action: AuditAction.GDPR_DATA_EXPORT_REQUESTED,
+      severity: AuditSeverity.INFO,
+      userId: request.userId,
+      details: {
+        requestId,
+        format: request.format,
+        includeEvents: request.includeEvents,
+        includeMetrics: request.includeMetrics,
+        includeAuditLogs: request.includeAuditLogs,
+      },
+      result: 'success',
+    });
+
+    // In production: Queue export job
+    await this.queueExportJob(requestId, request);
+
+    // GDPR requires response within 30 days, we aim for 24 hours
+    const estimatedCompletion = new Date();
+    estimatedCompletion.setHours(estimatedCompletion.getHours() + 24);
+
+    return {
+      requestId,
+      estimatedCompletionTime: estimatedCompletion,
+    };
+  }
+
+  /**
+   * Execute data export
+   */
+  async executeDataExport(requestId: string): Promise<{
+    downloadUrl: string;
+    expiresAt: Date;
+  }> {
+    const request = await this.getExportRequest(requestId);
+
+    if (!request) {
+      throw new Error('Export request not found');
+    }
+
+    // Collect all user data
+    const userData = await this.collectUserData(request.userId, {
+      includeEvents: request.includeEvents,
+      includeMetrics: request.includeMetrics,
+      includeAuditLogs: request.includeAuditLogs,
+    });
+
+    // Format data
+    const formattedData = await this.formatExportData(userData, request.format);
+
+    // Store securely (encrypted, time-limited)
+    const downloadUrl = await this.storeExportFile(requestId, formattedData);
+
+    // Set expiration (7 days)
+    const expiresAt = new Date();
+    expiresAt.setDate(expiresAt.getDate() + 7);
+
+    // Log completion
+    await auditLogger.log({
+      action: AuditAction.GDPR_DATA_EXPORTED,
+      severity: AuditSeverity.INFO,
+      userId: request.userId,
+      details: { requestId },
+      result: 'success',
+    });
+
+    return { downloadUrl, expiresAt };
+  }
+
+  /**
+   * Request data deletion (Right to Erasure - GDPR Article 17)
+   */
+  async requestDataDeletion(request: GDPRDataDeletionRequest): Promise<{
+    requestId: string;
+    scheduledDeletionDate: Date;
+  }> {
+    const requestId = this.generateRequestId();
+
+    // Check for legal holds or retention requirements
+    const hasLegalHold = await this.checkLegalHold(request.userId);
+
+    if (hasLegalHold && !request.retentionOverride) {
+      throw new Error(
+        'Cannot delete data: Subject to legal hold or retention requirements'
+      );
+    }
+
+    // Log audit event
+    await auditLogger.log({
+      action: AuditAction.GDPR_DATA_DELETION_REQUESTED,
+      severity: AuditSeverity.CRITICAL,
+      userId: request.userId,
+      details: {
+        requestId,
+        reason: request.reason,
+        retentionOverride: request.retentionOverride,
+      },
+      result: 'success',
+    });
+
+    // GDPR allows 30 days for deletion, schedule for 30 days from now
+    const scheduledDeletion = new Date();
+    scheduledDeletion.setDate(scheduledDeletion.getDate() + 30);
+
+    // In production: Queue deletion job
+    await this.queueDeletionJob(requestId, request, scheduledDeletion);
+
+    return {
+      requestId,
+      scheduledDeletionDate: scheduledDeletion,
+    };
+  }
+
+  /**
+   * Execute data deletion
+   */
+  async executeDataDeletion(requestId: string): Promise<{
+    deletedRecords: {
+      events: number;
+      metrics: number;
+      auditLogs: number;
+      user: boolean;
+    };
+  }> {
+    const request = await this.getDeletionRequest(requestId);
+
+    if (!request) {
+      throw new Error('Deletion request not found');
+    }
+
+    // Delete user data (anonymize where required for audit trail)
+    const deletedRecords = {
+      events: await this.deleteUserEvents(request.userId),
+      metrics: await this.deleteUserMetrics(request.userId),
+      auditLogs: await this.anonymizeAuditLogs(request.userId),
+      user: await this.deleteUserAccount(request.userId),
+    };
+
+    // Log completion
+    await auditLogger.log({
+      action: AuditAction.GDPR_DATA_DELETED,
+      severity: AuditSeverity.CRITICAL,
+      userId: request.userId,
+      details: {
+        requestId,
+        deletedRecords,
+      },
+      result: 'success',
+    });
+
+    return { deletedRecords };
+  }
+
+  /**
+   * Record user consent
+   */
+  async recordConsent(consent: UserConsent): Promise<void> {
+    // In production: Store in database
+    // INSERT INTO user_consents (user_id, consent_type, granted, ...)
+
+    await auditLogger.log({
+      action: consent.granted
+        ? AuditAction.USER_CREATED
+        : AuditAction.USER_UPDATED,
+      severity: AuditSeverity.INFO,
+      userId: consent.userId,
+      details: {
+        consentType: consent.consentType,
+        granted: consent.granted,
+      },
+      result: 'success',
+    });
+  }
+
+  /**
+   * Check if user has given consent
+   */
+  async hasConsent(_userId: string, _consentType: string): Promise<boolean> {
+    // In production: Query database
+    // SELECT * FROM user_consents WHERE user_id = ? AND consent_type = ?
+    return false;
+  }
+
+  /**
+   * Get data retention policy for data type
+   */
+  getRetentionPolicy(dataType: string): {
+    retentionDays: number;
+    canDelete: boolean;
+  } {
+    const policies: Record<string, { retentionDays: number; canDelete: boolean }> = {
+      events: { retentionDays: 365, canDelete: true },
+      metrics: { retentionDays: 730, canDelete: true },
+      audit_logs: { retentionDays: 2555, canDelete: false }, // 7 years for SOC 2
+      user_data: { retentionDays: 365, canDelete: true },
+      financial: { retentionDays: 2555, canDelete: false }, // 7 years legal requirement
+    };
+
+    return policies[dataType] || { retentionDays: 365, canDelete: true };
+  }
+
+  /**
+   * Helper methods (would be implemented with actual database operations)
+   */
+
+  private generateRequestId(): string {
+    return `gdpr_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+  }
+
+  private async queueExportJob(
+    _requestId: string,
+    _request: GDPRDataExportRequest
+  ): Promise<void> {
+    // In production: Queue job in Redis/RabbitMQ
+  }
+
+  private async queueDeletionJob(
+    _requestId: string,
+    _request: GDPRDataDeletionRequest,
+    _scheduledDate: Date
+  ): Promise<void> {
+    // In production: Queue scheduled job
+  }
+
+  private async getExportRequest(
+    _requestId: string
+  ): Promise<GDPRDataExportRequest | null> {
+    // In production: Query database
+    return null;
+  }
+
+  private async getDeletionRequest(
+    _requestId: string
+  ): Promise<GDPRDataDeletionRequest | null> {
+    // In production: Query database
+    return null;
+  }
+
+  private async collectUserData(
+    _userId: string,
+    _options: { includeEvents: boolean; includeMetrics: boolean; includeAuditLogs: boolean }
+  ): Promise<any> {
+    // In production: Collect all user data from various tables
+    return {};
+  }
+
+  private async formatExportData(_data: any, _format: string): Promise<Buffer> {
+    // In production: Format as JSON/CSV/XML
+    return Buffer.from(JSON.stringify(_data));
+  }
+
+  private async storeExportFile(requestId: string, _data: Buffer): Promise<string> {
+    // In production: Store in S3 with encryption and signed URL
+    return `https://exports.llm-analytics.com/${requestId}`;
+  }
+
+  private async checkLegalHold(_userId: string): Promise<boolean> {
+    // In production: Check if user data is under legal hold
+    return false;
+  }
+
+  private async deleteUserEvents(_userId: string): Promise<number> {
+    // In production: DELETE FROM events WHERE user_id = ?
+    return 0;
+  }
+
+  private async deleteUserMetrics(_userId: string): Promise<number> {
+    // In production: DELETE FROM metrics WHERE user_id = ?
+    return 0;
+  }
+
+  private async anonymizeAuditLogs(_userId: string): Promise<number> {
+    // In production: UPDATE audit_logs SET user_email = 'anonymized@...', ...
+    // Cannot delete audit logs (compliance requirement), but can anonymize
+    return 0;
+  }
+
+  private async deleteUserAccount(_userId: string): Promise<boolean> {
+    // In production: DELETE FROM users WHERE user_id = ?
+    return true;
+  }
+}
+
+export const gdprManager = new GDPRComplianceManager();

package/dist/bundled-agents/analytics-hub-agents/src/config.ts

@@ -0,0 +1,81 @@
+/**
+ * Configuration management
+ */
+
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export const config = {
+  // Server configuration
+  port: parseInt(process.env.PORT || '8080', 10),
+  host: process.env.HOST || '0.0.0.0',
+  env: process.env.NODE_ENV || 'development',
+
+  // Database configuration (TimescaleDB)
+  database: {
+    host: process.env.DB_HOST || 'localhost',
+    port: parseInt(process.env.DB_PORT || '5432', 10),
+    database: process.env.DB_NAME || 'llm_analytics',
+    user: process.env.DB_USER || 'postgres',
+    password: process.env.DB_PASSWORD || 'postgres',
+    max: parseInt(process.env.DB_POOL_MAX || '20', 10),
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: 2000,
+  },
+
+  // Redis configuration
+  redis: {
+    host: process.env.REDIS_HOST || 'localhost',
+    port: parseInt(process.env.REDIS_PORT || '6379', 10),
+    password: process.env.REDIS_PASSWORD,
+    db: parseInt(process.env.REDIS_DB || '0', 10),
+    cluster: process.env.REDIS_CLUSTER === 'true',
+    nodes: process.env.REDIS_NODES
+      ? process.env.REDIS_NODES.split(',').map((node) => {
+          const [host, port] = node.split(':');
+          return { host, port: parseInt(port, 10) };
+        })
+      : [],
+  },
+
+  // Kafka configuration
+  kafka: {
+    brokers: process.env.KAFKA_BROKERS
+      ? process.env.KAFKA_BROKERS.split(',')
+      : ['localhost:9092'],
+    clientId: 'llm-analytics-hub-api',
+    groupId: 'llm-analytics-hub-api-group',
+    topic: process.env.KAFKA_TOPIC || 'llm-analytics-events',
+  },
+
+  // CORS configuration
+  cors: {
+    origin: process.env.CORS_ORIGIN || '*',
+  },
+
+  // Rate limiting
+  rateLimit: {
+    max: parseInt(process.env.RATE_LIMIT_MAX || '100', 10),
+    timeWindow: process.env.RATE_LIMIT_WINDOW || '1 minute',
+  },
+
+  // Logging
+  logging: {
+    level: process.env.LOG_LEVEL || 'info',
+    prettyPrint: process.env.NODE_ENV === 'development',
+  },
+
+  // Pagination
+  pagination: {
+    defaultLimit: parseInt(process.env.DEFAULT_PAGE_SIZE || '50', 10),
+    maxLimit: parseInt(process.env.MAX_PAGE_SIZE || '1000', 10),
+  },
+
+  // Cache TTL (seconds)
+  cache: {
+    metrics: parseInt(process.env.CACHE_METRICS_TTL || '300', 10), // 5 minutes
+    events: parseInt(process.env.CACHE_EVENTS_TTL || '60', 10), // 1 minute
+    predictions: parseInt(process.env.CACHE_PREDICTIONS_TTL || '600', 10), // 10 minutes
+  },
+};

package/dist/bundled-agents/analytics-hub-agents/src/contracts/consensus-agent.ts

@@ -0,0 +1,249 @@
+/**
+ * Consensus Agent Contract
+ *
+ * Defines inputs, outputs, validation rules, and boundaries for the Consensus Agent.
+ * This agent performs ANALYTICAL SYNTHESIS and CONSENSUS FORMATION across signals.
+ *
+ * Classification: ANALYTICAL SYNTHESIS / CONSENSUS / CROSS-SIGNAL AGGREGATION
+ *
+ * @module contracts/consensus-agent
+ */
+
+import { z } from 'zod';
+import { DecisionEventSchema } from './decision-event';
+
+// ============================================================================
+// AGENT METADATA
+// ============================================================================
+
+export const AGENT_ID = 'consensus-agent';
+export const AGENT_VERSION = '1.0.0';
+export const DECISION_TYPE = 'analytics_consensus_summary';
+
+// ============================================================================
+// INPUT SCHEMAS
+// ============================================================================
+
+/**
+ * Individual signal input for consensus computation
+ */
+export const SignalInputSchema = z.object({
+  /** Unique signal identifier */
+  signalId: z.string(),
+  /** Source layer (e.g., "observatory", "costops", "governance") */
+  sourceLayer: z.string(),
+  /** Signal value (numeric or structured) */
+  value: z.union([z.number(), z.object({}).passthrough()]),
+  /** Confidence of the signal (0-1) */
+  confidence: z.number().min(0).max(1),
+  /** Timestamp of signal generation */
+  timestamp: z.string().datetime(),
+  /** Optional metadata */
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Consensus Agent input schema
+ */
+export const ConsensusInputSchema = z.object({
+  /** Signals to analyze for consensus */
+  signals: z.array(SignalInputSchema).min(1),
+  /** Time range for analysis */
+  timeRange: z.object({
+    start: z.string().datetime(),
+    end: z.string().datetime(),
+  }),
+  /** Consensus computation options */
+  options: z.object({
+    /** Minimum agreement threshold to establish consensus (0-1) */
+    minAgreementThreshold: z.number().min(0).max(1).default(0.6),
+    /** Confidence weighting strategy */
+    confidenceWeighting: z.enum(['uniform', 'proportional', 'exponential']).default('proportional'),
+    /** Aggregation method for numeric signals */
+    aggregationMethod: z.enum(['mean', 'median', 'mode', 'weighted_mean']).default('weighted_mean'),
+    /** Include divergent signal analysis */
+    includeDivergentAnalysis: z.boolean().default(true),
+    /** Signal scope filter */
+    scopeFilter: z.array(z.string()).optional(),
+  }).default({}),
+  /** Execution reference for tracing */
+  executionRef: z.string().uuid().optional(),
+});
+
+export type SignalInput = z.infer<typeof SignalInputSchema>;
+export type ConsensusInput = z.infer<typeof ConsensusInputSchema>;
+
+// ============================================================================
+// OUTPUT SCHEMAS
+// ============================================================================
+
+/**
+ * Consensus Agent response schema
+ */
+export const ConsensusResponseSchema = z.object({
+  /** Whether consensus was achieved */
+  consensusAchieved: z.boolean(),
+  /** The decision event emitted */
+  decisionEvent: DecisionEventSchema,
+  /** Human-readable summary */
+  summary: z.string(),
+  /** Processing metadata */
+  processingMetadata: z.object({
+    signalsProcessed: z.number().int(),
+    computationTimeMs: z.number(),
+    method: z.string(),
+  }),
+});
+
+export type ConsensusResponse = z.infer<typeof ConsensusResponseSchema>;
+
+// ============================================================================
+// CLI CONTRACT
+// ============================================================================
+
+/**
+ * CLI invocation shape for the Consensus Agent
+ *
+ * @example
+ * ```bash
+ * # Analyze consensus from stdin
+ * cat signals.json | consensus-agent analyze
+ *
+ * # Synthesize with specific options
+ * consensus-agent synthesize --min-agreement 0.7 --method weighted_mean
+ *
+ * # Summarize consensus results
+ * consensus-agent summarize --format json
+ *
+ * # Inspect specific signal alignment
+ * consensus-agent inspect --signal-id signal-123
+ * ```
+ */
+export const CLI_CONTRACT = {
+  commands: ['analyze', 'synthesize', 'summarize', 'inspect'] as const,
+  flags: {
+    '--min-agreement': 'Minimum agreement threshold (0-1)',
+    '--method': 'Aggregation method (mean|median|mode|weighted_mean)',
+    '--confidence-weighting': 'Confidence weighting (uniform|proportional|exponential)',
+    '--format': 'Output format (json|yaml|table)',
+    '--signal-id': 'Specific signal ID to inspect',
+    '--time-range': 'Time range (ISO format: start,end)',
+    '--scope': 'Signal scope filter (comma-separated)',
+  },
+} as const;
+
+// ============================================================================
+// BOUNDARY DEFINITIONS
+// ============================================================================
+
+/**
+ * Explicit boundaries - what this agent MUST NOT do
+ */
+export const AGENT_BOUNDARIES = {
+  /** Actions this agent is PROHIBITED from performing */
+  PROHIBITED_ACTIONS: [
+    'Modify execution behavior',
+    'Enforce constraints or policies',
+    'Trigger workflows or retries',
+    'Execute other agents',
+    'Apply optimizations autonomously',
+    'Emit anomaly detections',
+    'Connect directly to SQL databases',
+    'Execute raw SQL queries',
+    'Intercept execution paths',
+    'Orchestrate agents',
+  ],
+
+  /** Systems this agent MUST NOT interact with directly */
+  PROHIBITED_INTEGRATIONS: [
+    'Google SQL (Postgres) - use ruvector-service only',
+    'Workflow execution engines',
+    'Policy enforcement systems',
+    'Auto-optimizer (except read-only consumption)',
+  ],
+
+  /** Data this agent MUST NOT persist directly */
+  NON_PERSISTABLE_DATA: [
+    'Raw signal values (temporary, in-memory only)',
+    'Intermediate computation states',
+    'Execution context beyond execution_ref',
+  ],
+} as const;
+
+/**
+ * Permitted actions for this agent
+ */
+export const AGENT_PERMISSIONS = {
+  /** Actions this agent MAY perform */
+  PERMITTED_ACTIONS: [
+    'Aggregate DecisionEvents across layers',
+    'Perform statistical and semantic analysis',
+    'Derive correlations, trends, and consensus views',
+    'Produce strategic or executive-level insights',
+    'Emit analytical DecisionEvents',
+    'Read from Observatory telemetry inputs',
+    'Read from CostOps cost/ROI inputs',
+    'Read from Governance Dashboard artifacts',
+  ],
+
+  /** Systems that MAY consume this agent\'s output */
+  PERMITTED_CONSUMERS: [
+    'LLM-Auto-Optimizer (read-only)',
+    'LLM-Governance-Dashboard',
+    'Executive reporting systems',
+    'Strategic analytics consumers',
+  ],
+} as const;
+
+// ============================================================================
+// ANALYTICS CLASSIFICATION
+// ============================================================================
+
+export const ANALYTICS_CLASSIFICATION = {
+  type: 'ANALYTICAL_SYNTHESIS',
+  subtype: 'CONSENSUS_FORMATION',
+  scope: 'CROSS_SIGNAL_AGGREGATION',
+  readOnly: true,
+  executionPath: 'OUTSIDE_CRITICAL_PATH',
+} as const;
+
+// ============================================================================
+// FAILURE MODES
+// ============================================================================
+
+export const FAILURE_MODES = {
+  /** Input validation failures */
+  VALIDATION_FAILURE: {
+    code: 'CONSENSUS_VALIDATION_FAILURE',
+    recoverable: true,
+    action: 'Return validation error, do not emit DecisionEvent',
+  },
+
+  /** Insufficient signals for consensus */
+  INSUFFICIENT_SIGNALS: {
+    code: 'CONSENSUS_INSUFFICIENT_SIGNALS',
+    recoverable: true,
+    action: 'Return partial result with low confidence, emit DecisionEvent with confidence=0',
+  },
+
+  /** ruvector-service connection failure */
+  PERSISTENCE_FAILURE: {
+    code: 'CONSENSUS_PERSISTENCE_FAILURE',
+    recoverable: false,
+    action: 'Log error, return failure response, do not emit DecisionEvent',
+  },
+
+  /** Computation timeout */
+  COMPUTATION_TIMEOUT: {
+    code: 'CONSENSUS_COMPUTATION_TIMEOUT',
+    recoverable: false,
+    action: 'Abort computation, return timeout error, do not emit DecisionEvent',
+  },
+
+  /** Internal computation error */
+  COMPUTATION_ERROR: {
+    code: 'CONSENSUS_COMPUTATION_ERROR',
+    recoverable: false,
+    action: 'Log error, return failure response, do not emit DecisionEvent',
+  },
+} as const;