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

package/dist/bundled-agents/policy-engine-agents/src/integrations/shield/client.ts

@@ -0,0 +1,159 @@
+/**
+ * LLM-Shield Integration Client
+ * Integration with LLM-Shield for security scanning
+ */
+import axios, { AxiosInstance } from 'axios';
+import { config } from '@utils/config';
+import logger from '@utils/logger';
+
+export interface ShieldScanRequest {
+  prompt: string;
+  model?: string;
+  context?: Record<string, any>;
+}
+
+export interface ShieldScanResult {
+  safe: boolean;
+  threats: ShieldThreat[];
+  score: number;
+  scanTimeMs: number;
+}
+
+export interface ShieldThreat {
+  type: 'prompt_injection' | 'jailbreak' | 'data_exfiltration' | 'pii_leakage' | 'toxic_content';
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  confidence: number;
+  details: string;
+  location?: {
+    start: number;
+    end: number;
+  };
+}
+
+export class ShieldClient {
+  private client: AxiosInstance;
+  private enabled: boolean;
+
+  constructor() {
+    this.enabled = !!config.integrations.llmShieldUrl;
+
+    this.client = axios.create({
+      baseURL: config.integrations.llmShieldUrl,
+      timeout: 5000,
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'LLM-Policy-Engine/1.0',
+      },
+    });
+  }
+
+  /**
+   * Scan prompt for security threats
+   */
+  async scanPrompt(request: ShieldScanRequest): Promise<ShieldScanResult> {
+    if (!this.enabled) {
+      logger.debug('LLM-Shield integration disabled, skipping scan');
+      return {
+        safe: true,
+        threats: [],
+        score: 1.0,
+        scanTimeMs: 0,
+      };
+    }
+
+    const startTime = Date.now();
+
+    try {
+      const response = await this.client.post('/api/v1/scan', {
+        prompt: request.prompt,
+        model: request.model,
+        context: request.context,
+      });
+
+      const scanTimeMs = Date.now() - startTime;
+
+      const result: ShieldScanResult = {
+        safe: response.data.safe,
+        threats: response.data.threats || [],
+        score: response.data.score || 1.0,
+        scanTimeMs,
+      };
+
+      logger.info(
+        {
+          safe: result.safe,
+          threatCount: result.threats.length,
+          score: result.score,
+          scanTimeMs,
+        },
+        'LLM-Shield scan completed',
+      );
+
+      return result;
+    } catch (error) {
+      logger.error({ error }, 'LLM-Shield scan failed');
+
+      if (axios.isAxiosError(error)) {
+        if (error.code === 'ECONNREFUSED') {
+          logger.warn('LLM-Shield service unavailable, allowing request');
+          return {
+            safe: true,
+            threats: [],
+            score: 1.0,
+            scanTimeMs: Date.now() - startTime,
+          };
+        }
+      }
+
+      throw new Error(`Shield scan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Batch scan multiple prompts
+   */
+  async scanBatch(requests: ShieldScanRequest[]): Promise<ShieldScanResult[]> {
+    if (!this.enabled) {
+      return requests.map(() => ({
+        safe: true,
+        threats: [],
+        score: 1.0,
+        scanTimeMs: 0,
+      }));
+    }
+
+    try {
+      const response = await this.client.post('/api/v1/scan/batch', {
+        requests: requests.map((r) => ({
+          prompt: r.prompt,
+          model: r.model,
+          context: r.context,
+        })),
+      });
+
+      return response.data.results || [];
+    } catch (error) {
+      logger.error({ error }, 'LLM-Shield batch scan failed');
+      throw new Error(`Shield batch scan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Check Shield service health
+   */
+  async healthCheck(): Promise<boolean> {
+    if (!this.enabled) {
+      return false;
+    }
+
+    try {
+      const response = await this.client.get('/health');
+      return response.status === 200;
+    } catch (error) {
+      logger.error({ error }, 'LLM-Shield health check failed');
+      return false;
+    }
+  }
+}
+
+export const shieldClient = new ShieldClient();

package/dist/bundled-agents/policy-engine-agents/src/observability/metrics.ts

@@ -0,0 +1,220 @@
+/**
+ * Metrics Collection using Prometheus
+ * Production-grade metrics for monitoring and observability
+ */
+import { Counter, Gauge, Histogram, Registry, collectDefaultMetrics } from 'prom-client';
+import express, { Express } from 'express';
+import { config } from '@utils/config';
+import logger from '@utils/logger';
+
+export class MetricsCollector {
+  private registry: Registry;
+
+  public policyEvaluations: Counter;
+  public policyEvaluationDuration: Histogram;
+  public policyEvaluationErrors: Counter;
+  public activePolicies: Gauge;
+  public cacheHits: Counter;
+  public cacheMisses: Counter;
+  public dbQueries: Counter;
+  public dbQueryDuration: Histogram;
+  public apiRequests: Counter;
+  public apiRequestDuration: Histogram;
+  public apiErrors: Counter;
+
+  constructor() {
+    this.registry = new Registry();
+
+    collectDefaultMetrics({
+      register: this.registry,
+      prefix: 'llm_policy_engine_',
+    });
+
+    this.policyEvaluations = new Counter({
+      name: 'llm_policy_evaluations_total',
+      help: 'Total number of policy evaluations',
+      labelNames: ['decision', 'cached'],
+      registers: [this.registry],
+    });
+
+    this.policyEvaluationDuration = new Histogram({
+      name: 'llm_policy_evaluation_duration_ms',
+      help: 'Policy evaluation duration in milliseconds',
+      labelNames: ['decision'],
+      buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000],
+      registers: [this.registry],
+    });
+
+    this.policyEvaluationErrors = new Counter({
+      name: 'llm_policy_evaluation_errors_total',
+      help: 'Total number of policy evaluation errors',
+      labelNames: ['error_type'],
+      registers: [this.registry],
+    });
+
+    this.activePolicies = new Gauge({
+      name: 'llm_policy_active_policies',
+      help: 'Number of active policies',
+      registers: [this.registry],
+    });
+
+    this.cacheHits = new Counter({
+      name: 'llm_policy_cache_hits_total',
+      help: 'Total number of cache hits',
+      labelNames: ['layer'],
+      registers: [this.registry],
+    });
+
+    this.cacheMisses = new Counter({
+      name: 'llm_policy_cache_misses_total',
+      help: 'Total number of cache misses',
+      labelNames: ['layer'],
+      registers: [this.registry],
+    });
+
+    this.dbQueries = new Counter({
+      name: 'llm_policy_db_queries_total',
+      help: 'Total number of database queries',
+      labelNames: ['operation'],
+      registers: [this.registry],
+    });
+
+    this.dbQueryDuration = new Histogram({
+      name: 'llm_policy_db_query_duration_ms',
+      help: 'Database query duration in milliseconds',
+      labelNames: ['operation'],
+      buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2000],
+      registers: [this.registry],
+    });
+
+    this.apiRequests = new Counter({
+      name: 'llm_policy_api_requests_total',
+      help: 'Total number of API requests',
+      labelNames: ['method', 'path', 'status'],
+      registers: [this.registry],
+    });
+
+    this.apiRequestDuration = new Histogram({
+      name: 'llm_policy_api_request_duration_ms',
+      help: 'API request duration in milliseconds',
+      labelNames: ['method', 'path', 'status'],
+      buckets: [10, 50, 100, 250, 500, 1000, 2500, 5000, 10000],
+      registers: [this.registry],
+    });
+
+    this.apiErrors = new Counter({
+      name: 'llm_policy_api_errors_total',
+      help: 'Total number of API errors',
+      labelNames: ['method', 'path', 'error_type'],
+      registers: [this.registry],
+    });
+  }
+
+  /**
+   * Get registry for exporting
+   */
+  getRegistry(): Registry {
+    return this.registry;
+  }
+
+  /**
+   * Get metrics in Prometheus format
+   */
+  async getMetrics(): Promise<string> {
+    return this.registry.metrics();
+  }
+
+  /**
+   * Record policy evaluation
+   */
+  recordEvaluation(decision: string, durationMs: number, cached: boolean = false): void {
+    this.policyEvaluations.inc({ decision, cached: String(cached) });
+    this.policyEvaluationDuration.observe({ decision }, durationMs);
+  }
+
+  /**
+   * Record policy evaluation error
+   */
+  recordEvaluationError(errorType: string): void {
+    this.policyEvaluationErrors.inc({ error_type: errorType });
+  }
+
+  /**
+   * Set active policies count
+   */
+  setActivePolicies(count: number): void {
+    this.activePolicies.set(count);
+  }
+
+  /**
+   * Record cache hit
+   */
+  recordCacheHit(layer: 'L1' | 'L2'): void {
+    this.cacheHits.inc({ layer });
+  }
+
+  /**
+   * Record cache miss
+   */
+  recordCacheMiss(layer: 'L1' | 'L2'): void {
+    this.cacheMisses.inc({ layer });
+  }
+
+  /**
+   * Record database query
+   */
+  recordDbQuery(operation: string, durationMs: number): void {
+    this.dbQueries.inc({ operation });
+    this.dbQueryDuration.observe({ operation }, durationMs);
+  }
+
+  /**
+   * Record API request
+   */
+  recordApiRequest(method: string, path: string, status: number, durationMs: number): void {
+    this.apiRequests.inc({ method, path, status: String(status) });
+    this.apiRequestDuration.observe({ method, path, status: String(status) }, durationMs);
+  }
+
+  /**
+   * Record API error
+   */
+  recordApiError(method: string, path: string, errorType: string): void {
+    this.apiErrors.inc({ method, path, error_type: errorType });
+  }
+}
+
+export const metricsCollector = new MetricsCollector();
+
+/**
+ * Start metrics server
+ */
+export function startMetricsServer(port?: number): void {
+  const app: Express = express();
+  const metricsPort = port || config.observability.metricsPort;
+
+  app.get(config.observability.metricsPath, async (_req, res) => {
+    try {
+      res.set('Content-Type', metricsCollector.getRegistry().contentType);
+      const metrics = await metricsCollector.getMetrics();
+      res.send(metrics);
+    } catch (error) {
+      logger.error({ error }, 'Failed to export metrics');
+      res.status(500).send('Failed to export metrics');
+    }
+  });
+
+  app.get('/health', (_req, res) => {
+    res.json({ status: 'healthy' });
+  });
+
+  app.listen(metricsPort, () => {
+    logger.info(
+      {
+        port: metricsPort,
+        path: config.observability.metricsPath,
+      },
+      'Metrics server started',
+    );
+  });
+}

package/dist/bundled-agents/policy-engine-agents/src/observability/tracing.ts

@@ -0,0 +1,251 @@
+/**
+ * Distributed Tracing using OpenTelemetry
+ * Production-grade tracing for request flow visibility
+ */
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { Resource } from '@opentelemetry/resources';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
+import { PgInstrumentation } from '@opentelemetry/instrumentation-pg';
+import { RedisInstrumentation as Redis4Instrumentation } from '@opentelemetry/instrumentation-redis-4';
+import { trace, Span, SpanStatusCode, Context, context } from '@opentelemetry/api';
+import { config } from '@utils/config';
+import logger from '@utils/logger';
+
+export class TracingService {
+  private provider: NodeTracerProvider | null = null;
+  private enabled: boolean;
+
+  constructor() {
+    this.enabled = config.observability.traceEnabled;
+  }
+
+  /**
+   * Initialize tracing
+   */
+  initialize(): void {
+    if (!this.enabled) {
+      logger.info('Tracing disabled');
+      return;
+    }
+
+    try {
+      const resource = new Resource({
+        [SemanticResourceAttributes.SERVICE_NAME]: 'llm-policy-engine',
+        [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
+        [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: config.nodeEnv,
+      });
+
+      this.provider = new NodeTracerProvider({
+        resource,
+      });
+
+      const jaegerExporter = new JaegerExporter({
+        endpoint: process.env.JAEGER_ENDPOINT || 'http://localhost:14268/api/traces',
+      });
+
+      this.provider.addSpanProcessor(new BatchSpanProcessor(jaegerExporter) as any);
+
+      this.provider.register();
+
+      registerInstrumentations({
+        instrumentations: [
+          new HttpInstrumentation({
+            requestHook: (span, request) => {
+              const headers = (request as any).headers;
+              span.setAttribute('http.request.id', headers?.['x-request-id'] || '');
+            },
+          }),
+          new ExpressInstrumentation(),
+          new PgInstrumentation({
+            enhancedDatabaseReporting: true,
+          }),
+          new Redis4Instrumentation(),
+        ],
+      });
+
+      logger.info('Tracing initialized successfully');
+    } catch (error) {
+      logger.error({ error }, 'Failed to initialize tracing');
+      this.enabled = false;
+    }
+  }
+
+  /**
+   * Create a new span
+   */
+  createSpan(name: string, attributes?: Record<string, any>): Span | null {
+    if (!this.enabled) {
+      return null;
+    }
+
+    const tracer = trace.getTracer('llm-policy-engine');
+    const span = tracer.startSpan(name, {
+      attributes: attributes || {},
+    });
+
+    return span;
+  }
+
+  /**
+   * Start a span with context
+   */
+  startSpan<T>(
+    name: string,
+    fn: (span: Span) => Promise<T>,
+    attributes?: Record<string, any>,
+  ): Promise<T> {
+    if (!this.enabled) {
+      const mockSpan = {
+        end: () => {},
+        setStatus: () => {},
+        setAttribute: () => {},
+        addEvent: () => {},
+      } as any;
+      return fn(mockSpan);
+    }
+
+    const tracer = trace.getTracer('llm-policy-engine');
+
+    return tracer.startActiveSpan(name, { attributes: attributes || {} }, async (span) => {
+      try {
+        const result = await fn(span);
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (error) {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: error instanceof Error ? error.message : String(error),
+        });
+        span.recordException(error as Error);
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /**
+   * Get current context
+   */
+  getCurrentContext(): Context {
+    return context.active();
+  }
+
+  /**
+   * Wrap a function with tracing
+   */
+  wrap<T extends (...args: any[]) => Promise<any>>(
+    name: string,
+    fn: T,
+    getAttributes?: (...args: Parameters<T>) => Record<string, any>,
+  ): T {
+    if (!this.enabled) {
+      return fn;
+    }
+
+    return (async (...args: Parameters<T>) => {
+      const attributes = getAttributes ? getAttributes(...args) : {};
+      return this.startSpan(name, () => fn(...args), attributes);
+    }) as T;
+  }
+
+  /**
+   * Add event to current span
+   */
+  addEvent(name: string, attributes?: Record<string, any>): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    const span = trace.getActiveSpan();
+    if (span) {
+      span.addEvent(name, attributes);
+    }
+  }
+
+  /**
+   * Set attribute on current span
+   */
+  setAttribute(key: string, value: string | number | boolean): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    const span = trace.getActiveSpan();
+    if (span) {
+      span.setAttribute(key, value);
+    }
+  }
+
+  /**
+   * Set multiple attributes on current span
+   */
+  setAttributes(attributes: Record<string, string | number | boolean>): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    const span = trace.getActiveSpan();
+    if (span) {
+      Object.entries(attributes).forEach(([key, value]) => {
+        span.setAttribute(key, value);
+      });
+    }
+  }
+
+  /**
+   * Record exception in current span
+   */
+  recordException(error: Error): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    const span = trace.getActiveSpan();
+    if (span) {
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error.message,
+      });
+    }
+  }
+
+  /**
+   * Shutdown tracing
+   */
+  async shutdown(): Promise<void> {
+    if (this.provider) {
+      await this.provider.shutdown();
+      logger.info('Tracing shutdown complete');
+    }
+  }
+}
+
+export const tracingService = new TracingService();
+
+/**
+ * Trace decorator for class methods
+ */
+export function Trace(spanName?: string, getAttributes?: (...args: any[]) => Record<string, any>) {
+  return function (
+    target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    const originalMethod = descriptor.value;
+    const name = spanName || `${target.constructor.name}.${propertyKey}`;
+
+    descriptor.value = async function (...args: any[]) {
+      const attributes = getAttributes ? getAttributes(...args) : {};
+      return tracingService.startSpan(name, () => originalMethod.apply(this, args), attributes);
+    };
+
+    return descriptor;
+  };
+}