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

package/dist/bundled-agents/auto-optimizer-agents/src/phase3/layer1/server-integration.ts

@@ -0,0 +1,267 @@
+/**
+ * Phase 3 Layer 1 Server Integration
+ *
+ * Integrates Phase 3 Layer 1 bootstrap and guards into the main server.
+ * This module provides middleware and hooks for the HTTP server.
+ *
+ * @module phase3/layer1/server-integration
+ */
+
+import { IncomingMessage, ServerResponse } from 'http';
+import {
+  AGENT_PHASE,
+  AGENT_LAYER,
+  Phase3Layer1Config,
+  bootstrapPhase3Layer1,
+  createExecutionGuard,
+  ExecutionGuard,
+  ExecutionGuardViolation,
+  checkRuVectorAvailability,
+  FAILURE_MODES,
+} from './index';
+
+// ============================================================================
+// Server State
+// ============================================================================
+
+let _phase3Config: Phase3Layer1Config | null = null;
+let _bootstrapComplete = false;
+let _bootstrapError: Error | null = null;
+
+// ============================================================================
+// Bootstrap Integration
+// ============================================================================
+
+/**
+ * Initialize Phase 3 Layer 1 for the server.
+ * MUST be called before server starts accepting requests.
+ *
+ * @throws Error if bootstrap fails (triggers crashloop)
+ */
+export async function initializePhase3Layer1(): Promise<Phase3Layer1Config> {
+  if (_bootstrapComplete && _phase3Config) {
+    return _phase3Config;
+  }
+
+  if (_bootstrapError) {
+    throw _bootstrapError;
+  }
+
+  try {
+    const result = await bootstrapPhase3Layer1();
+    if (!result.success || !result.config) {
+      const error = new Error(result.error || 'Bootstrap failed');
+      _bootstrapError = error;
+      throw error;
+    }
+    _phase3Config = result.config;
+    _bootstrapComplete = true;
+    return _phase3Config;
+  } catch (error) {
+    _bootstrapError = error as Error;
+    throw error;
+  }
+}
+
+/**
+ * Check if Phase 3 Layer 1 is initialized.
+ */
+export function isPhase3Initialized(): boolean {
+  return _bootstrapComplete && _phase3Config !== null;
+}
+
+/**
+ * Get the Phase 3 Layer 1 configuration.
+ * @throws Error if not initialized
+ */
+export function getPhase3Config(): Phase3Layer1Config {
+  if (!_phase3Config) {
+    throw new Error('Phase 3 Layer 1 not initialized. Call initializePhase3Layer1() first.');
+  }
+  return _phase3Config;
+}
+
+// ============================================================================
+// Request Context
+// ============================================================================
+
+/**
+ * Context attached to each request for Phase 3 Layer 1.
+ */
+export interface Phase3RequestContext {
+  /** Execution guard for this request */
+  guard: ExecutionGuard;
+  /** Request ID */
+  requestId: string;
+  /** Start timestamp */
+  startTime: number;
+  /** Phase identifier */
+  phase: typeof AGENT_PHASE;
+  /** Layer identifier */
+  layer: typeof AGENT_LAYER;
+}
+
+// WeakMap to store context per request
+const requestContexts = new WeakMap<IncomingMessage, Phase3RequestContext>();
+
+/**
+ * Create Phase 3 request context for an incoming request.
+ */
+export function createRequestContext(req: IncomingMessage): Phase3RequestContext {
+  const config = getPhase3Config();
+  const requestId = generateRequestId();
+  const guard = createExecutionGuard(config);
+
+  const context: Phase3RequestContext = {
+    guard,
+    requestId,
+    startTime: Date.now(),
+    phase: AGENT_PHASE,
+    layer: AGENT_LAYER,
+  };
+
+  requestContexts.set(req, context);
+  return context;
+}
+
+/**
+ * Get Phase 3 request context.
+ */
+export function getRequestContext(req: IncomingMessage): Phase3RequestContext | undefined {
+  return requestContexts.get(req);
+}
+
+/**
+ * Finalize request context and clean up.
+ */
+export function finalizeRequestContext(req: IncomingMessage): void {
+  const context = requestContexts.get(req);
+  if (context) {
+    try {
+      context.guard.finalize();
+    } catch (error) {
+      // Log but don't throw on finalization errors
+      console.error(JSON.stringify({
+        level: 'error',
+        message: 'request_context_finalization_error',
+        requestId: context.requestId,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        timestamp: new Date().toISOString(),
+      }));
+    }
+    requestContexts.delete(req);
+  }
+}
+
+// ============================================================================
+// Middleware
+// ============================================================================
+
+/**
+ * Phase 3 Layer 1 middleware for request handling.
+ * Wraps the request with execution guards.
+ *
+ * @param handler - The actual request handler
+ * @returns Wrapped handler with Phase 3 guards
+ */
+export function phase3Middleware(
+  handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    // Skip Phase 3 guards for health/ready endpoints
+    const path = req.url?.split('?')[0] || '/';
+    if (path === '/health' || path === '/ready') {
+      return handler(req, res);
+    }
+
+    // Create request context
+    const context = createRequestContext(req);
+
+    // Add Phase 3 headers to response
+    res.setHeader('X-Phase', AGENT_PHASE);
+    res.setHeader('X-Layer', AGENT_LAYER);
+    res.setHeader('X-Request-Id', context.requestId);
+
+    try {
+      // Check RuVector availability before processing
+      await checkRuVectorAvailability(getPhase3Config(), context.guard);
+
+      // Execute the actual handler
+      await handler(req, res);
+    } catch (error) {
+      if (error instanceof ExecutionGuardViolation) {
+        // Send guard violation response
+        sendGuardViolationResponse(res, error, context);
+      } else {
+        // Re-throw other errors
+        throw error;
+      }
+    } finally {
+      finalizeRequestContext(req);
+    }
+  };
+}
+
+/**
+ * Send a guard violation error response.
+ */
+function sendGuardViolationResponse(
+  res: ServerResponse,
+  error: ExecutionGuardViolation,
+  context: Phase3RequestContext
+): void {
+  const status = error.failureMode === FAILURE_MODES.RUVECTOR_UNAVAILABLE ? 503 : 422;
+
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'X-Phase': AGENT_PHASE,
+    'X-Layer': AGENT_LAYER,
+    'X-Request-Id': context.requestId,
+    'X-Failure-Mode': error.failureMode,
+  });
+
+  res.end(JSON.stringify({
+    error: {
+      code: error.failureMode,
+      message: error.message,
+      violation: error.violation,
+    },
+    phase: AGENT_PHASE,
+    layer: AGENT_LAYER,
+    request_id: context.requestId,
+    timestamp: new Date().toISOString(),
+  }));
+}
+
+// ============================================================================
+// Health Check Enhancements
+// ============================================================================
+
+/**
+ * Get Phase 3 Layer 1 health status.
+ */
+export function getPhase3HealthStatus(): {
+  phase3_initialized: boolean;
+  phase: string;
+  layer: string;
+  budgets: Record<string, number> | null;
+  ruvector_configured: boolean;
+} {
+  return {
+    phase3_initialized: _bootstrapComplete,
+    phase: AGENT_PHASE,
+    layer: AGENT_LAYER,
+    budgets: _phase3Config ? _phase3Config.budgets : null,
+    ruvector_configured: _phase3Config ? !!_phase3Config.ruvector.apiKey : false,
+  };
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+function generateRequestId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `p3l1-${timestamp}-${random}`;
+}

package/dist/bundled-agents/auto-optimizer-agents/src/phase3/layer1/signals.ts

@@ -0,0 +1,334 @@
+/**
+ * Phase 3 Layer 1 Signal Definitions
+ *
+ * Defines the signal schemas for DecisionEvents emitted by Phase 3 Layer 1 agents.
+ * All signals MUST include confidence scores and references.
+ *
+ * @module phase3/layer1/signals
+ */
+
+import { DecisionEvent, AppliedConstraint, RecommendationCategory } from '../../contracts';
+import { Phase3SignalType, AGENT_PHASE, AGENT_LAYER } from './config';
+
+// ============================================================================
+// Base Signal Schema
+// ============================================================================
+
+/**
+ * Base interface for all Phase 3 Layer 1 signals.
+ * Extends DecisionEvent with Phase 3 specific fields.
+ */
+export interface Phase3Signal extends DecisionEvent {
+  /** Phase identifier */
+  phase: typeof AGENT_PHASE;
+  /** Layer identifier */
+  layer: typeof AGENT_LAYER;
+  /** Signal-specific payload */
+  signal_payload: SignalPayload;
+  /** References to supporting data/events */
+  references: SignalReference[];
+}
+
+// ============================================================================
+// Signal Payloads
+// ============================================================================
+
+export type SignalPayload =
+  | ExecutionStrategyPayload
+  | OptimizationPayload
+  | IncidentPayload;
+
+/**
+ * Payload for execution_strategy_signal.
+ * Emitted when routing or coordinating execution across agents.
+ */
+export interface ExecutionStrategyPayload {
+  signal_type: 'execution_strategy_signal';
+  /** Strategy being recommended */
+  strategy: {
+    /** Strategy identifier */
+    id: string;
+    /** Strategy name */
+    name: string;
+    /** Strategy description */
+    description: string;
+    /** Target agent or service */
+    target: string;
+    /** Strategy parameters */
+    parameters: Record<string, unknown>;
+  };
+  /** Routing information */
+  routing: {
+    /** Source agent */
+    from_agent: string;
+    /** Target agents */
+    to_agents: string[];
+    /** Routing reason */
+    reason: string;
+  };
+  /** Strategy confidence */
+  strategy_confidence: number;
+  /** Expected outcome description */
+  expected_outcome: string;
+  /** Estimated tokens for execution */
+  estimated_tokens: number;
+  /** Estimated latency in milliseconds */
+  estimated_latency_ms: number;
+}
+
+/**
+ * Payload for optimization_signal.
+ * Emitted when proposing optimization opportunities.
+ */
+export interface OptimizationPayload {
+  signal_type: 'optimization_signal';
+  /** Optimization opportunity */
+  opportunity: {
+    /** Opportunity identifier */
+    id: string;
+    /** Opportunity category */
+    category: 'cost' | 'latency' | 'quality' | 'throughput' | 'reliability';
+    /** Current value */
+    current_value: number;
+    /** Proposed value */
+    proposed_value: number;
+    /** Improvement percentage */
+    improvement_pct: number;
+    /** Implementation complexity */
+    complexity: 'low' | 'medium' | 'high';
+  };
+  /** Impact analysis */
+  impact: {
+    /** Affected services */
+    affected_services: string[];
+    /** Risk level */
+    risk_level: 'low' | 'medium' | 'high';
+    /** Rollback capability */
+    reversible: boolean;
+  };
+  /** Optimization confidence */
+  optimization_confidence: number;
+  /** Supporting metrics */
+  metrics: Record<string, number>;
+}
+
+/**
+ * Payload for incident_signal.
+ * Emitted when detecting or escalating incidents.
+ */
+export interface IncidentPayload {
+  signal_type: 'incident_signal';
+  /** Incident details */
+  incident: {
+    /** Incident identifier */
+    id: string;
+    /** Incident type */
+    type: 'anomaly' | 'degradation' | 'threshold_breach' | 'error_spike' | 'availability';
+    /** Severity level */
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    /** Affected components */
+    affected_components: string[];
+    /** First detected timestamp */
+    first_detected: string;
+    /** Current status */
+    status: 'detected' | 'acknowledged' | 'escalated' | 'resolved';
+  };
+  /** Escalation information */
+  escalation: {
+    /** Escalation recommended */
+    recommended: boolean;
+    /** Escalation target */
+    target?: string;
+    /** Escalation reason */
+    reason?: string;
+    /** Urgency level */
+    urgency: 'low' | 'medium' | 'high' | 'immediate';
+  };
+  /** Detection confidence */
+  detection_confidence: number;
+  /** Recommended actions (NOT final decisions) */
+  recommended_actions: string[];
+}
+
+// ============================================================================
+// Signal Reference
+// ============================================================================
+
+/**
+ * Reference to supporting data or events.
+ * Required for all Phase 3 signals.
+ */
+export interface SignalReference {
+  /** Reference type */
+  type: 'decision_event' | 'telemetry' | 'metric' | 'log' | 'external';
+  /** Reference identifier */
+  id: string;
+  /** Reference source */
+  source: string;
+  /** Timestamp */
+  timestamp: string;
+  /** Relevance score (0-1) */
+  relevance: number;
+}
+
+// ============================================================================
+// Signal Builder Functions
+// ============================================================================
+
+export interface BuildSignalParams {
+  agentId: string;
+  agentVersion: string;
+  executionRef: string;
+  inputsHash: string;
+  signalType: Phase3SignalType;
+  payload: SignalPayload;
+  confidence: number;
+  constraintsApplied: AppliedConstraint[];
+  references: SignalReference[];
+}
+
+/**
+ * Build a Phase 3 Layer 1 signal.
+ * Validates all required fields and enforces signal constraints.
+ *
+ * @throws Error if signal validation fails
+ */
+export function buildPhase3Signal(params: BuildSignalParams): Phase3Signal {
+  // Validate confidence is within bounds
+  if (params.confidence < 0 || params.confidence > 1) {
+    throw new Error('Signal confidence must be between 0 and 1');
+  }
+
+  // Validate references are provided
+  if (params.references.length === 0) {
+    throw new Error('Phase 3 signals MUST include at least one reference');
+  }
+
+  // Validate payload signal_type matches signalType
+  if (params.payload.signal_type !== params.signalType) {
+    throw new Error(`Payload signal_type '${params.payload.signal_type}' does not match signalType '${params.signalType}'`);
+  }
+
+  const signal: Phase3Signal = {
+    // DecisionEvent fields
+    agent_id: params.agentId,
+    agent_version: params.agentVersion,
+    decision_type: params.signalType,
+    inputs_hash: params.inputsHash,
+    outputs: {
+      // Signal outputs are recommendations, NOT decisions
+      recommendations: [{
+        recommendation_id: `${params.signalType}-${Date.now()}`,
+        rank: 1,
+        category: mapSignalToCategory(params.signalType),
+        title: getSignalTitle(params.payload),
+        description: getSignalDescription(params.payload),
+        proposed_changes: [],
+        expected_impact: {
+          cost_change_pct: 0,
+          latency_change_pct: 0,
+          quality_change_pct: 0,
+          confidence: params.confidence,
+        },
+        complexity: 'medium',
+        risk: 'medium',
+        confidence: params.confidence,
+        evidence: params.references.map(ref => ({
+          type: mapReferenceToEvidence(ref.type),
+          source: ref.source,
+          data_points: { reference_id: ref.id },
+          strength: ref.relevance,
+        })),
+        rollout_strategy: {
+          type: 'gradual',
+          rollback_criteria: {
+            max_error_rate_increase_pct: 5,
+            max_latency_increase_pct: 10,
+            min_quality_threshold: 0.8,
+            monitoring_duration_minutes: 30,
+          },
+        },
+      }],
+    },
+    confidence: params.confidence,
+    constraints_applied: params.constraintsApplied,
+    execution_ref: params.executionRef,
+    timestamp: new Date().toISOString(),
+
+    // Phase 3 specific fields
+    phase: AGENT_PHASE,
+    layer: AGENT_LAYER,
+    signal_payload: params.payload,
+    references: params.references,
+  };
+
+  return signal;
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function mapSignalToCategory(signalType: Phase3SignalType): RecommendationCategory {
+  switch (signalType) {
+    case 'execution_strategy_signal':
+      return 'traffic_routing';
+    case 'optimization_signal':
+      return 'cost_optimization';
+    case 'incident_signal':
+      return 'quality_improvement';
+  }
+}
+
+function getSignalTitle(payload: SignalPayload): string {
+  switch (payload.signal_type) {
+    case 'execution_strategy_signal':
+      return `Execution Strategy: ${payload.strategy.name}`;
+    case 'optimization_signal':
+      return `Optimization Opportunity: ${payload.opportunity.category}`;
+    case 'incident_signal':
+      return `Incident Detected: ${payload.incident.type}`;
+  }
+}
+
+function getSignalDescription(payload: SignalPayload): string {
+  switch (payload.signal_type) {
+    case 'execution_strategy_signal':
+      return payload.strategy.description;
+    case 'optimization_signal':
+      return `${payload.opportunity.improvement_pct.toFixed(1)}% improvement in ${payload.opportunity.category}`;
+    case 'incident_signal':
+      return `${payload.incident.severity} severity ${payload.incident.type} affecting ${payload.incident.affected_components.join(', ')}`;
+  }
+}
+
+function mapReferenceToEvidence(refType: SignalReference['type']): 'historical_data' | 'benchmark' | 'a_b_test' | 'simulation' | 'industry_standard' {
+  switch (refType) {
+    case 'decision_event':
+      return 'historical_data';
+    case 'telemetry':
+      return 'historical_data';
+    case 'metric':
+      return 'benchmark';
+    case 'log':
+      return 'historical_data';
+    case 'external':
+      return 'industry_standard';
+  }
+}
+
+// ============================================================================
+// Signal Type Guards
+// ============================================================================
+
+export function isExecutionStrategySignal(payload: SignalPayload): payload is ExecutionStrategyPayload {
+  return payload.signal_type === 'execution_strategy_signal';
+}
+
+export function isOptimizationSignal(payload: SignalPayload): payload is OptimizationPayload {
+  return payload.signal_type === 'optimization_signal';
+}
+
+export function isIncidentSignal(payload: SignalPayload): payload is IncidentPayload {
+  return payload.signal_type === 'incident_signal';
+}