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

package/dist/bundled-agents/data-vault-agents/src/runtime/performance-budget.ts

@@ -0,0 +1,378 @@
+/**
+ * LLM-Data-Vault: Performance Budget Enforcement
+ *
+ * Phase 7 performance budget enforcement for agent executions.
+ * Ensures agents operate within defined resource constraints.
+ *
+ * BUDGETS:
+ * - MAX_TOKENS: 2500 (max tokens per response if applicable)
+ * - MAX_LATENCY_MS: 5000 (max execution time)
+ * - MAX_CALLS_PER_RUN: 5 (max external service calls per execution)
+ *
+ * @module runtime/performance-budget
+ */
+
+import {
+  DecisionEvent,
+  createDecisionEvent,
+  AppliedConstraint,
+} from '../contracts/index.js';
+
+/**
+ * Performance budget configuration
+ */
+export interface PerformanceBudget {
+  /** Maximum execution latency in milliseconds */
+  maxLatencyMs: number;
+  /** Maximum external service calls per execution */
+  maxCallsPerRun: number;
+  /** Maximum tokens per response (if applicable) */
+  maxTokens: number;
+}
+
+/**
+ * Default performance budgets for Phase 7 agents
+ */
+export const DEFAULT_BUDGETS: PerformanceBudget = {
+  maxLatencyMs: 5000,
+  maxCallsPerRun: 5,
+  maxTokens: 2500,
+};
+
+/**
+ * Budget violation reason
+ */
+export type BudgetViolationReason =
+  | 'latency_exceeded'
+  | 'calls_exceeded'
+  | 'tokens_exceeded';
+
+/**
+ * Budget check result
+ */
+export interface BudgetCheckResult {
+  withinBudget: boolean;
+  violation?: {
+    reason: BudgetViolationReason;
+    limit: number;
+    actual: number;
+    message: string;
+  };
+}
+
+/**
+ * Budget enforcer metrics
+ */
+export interface BudgetMetrics {
+  callCount: number;
+  startTime: number;
+  tokenCount: number;
+}
+
+/**
+ * Budget enforcement error
+ */
+export class BudgetExceededError extends Error {
+  public readonly reason: BudgetViolationReason;
+  public readonly limit: number;
+  public readonly actual: number;
+
+  constructor(reason: BudgetViolationReason, limit: number, actual: number) {
+    const messages: Record<BudgetViolationReason, string> = {
+      latency_exceeded: `Execution time ${actual}ms exceeded budget of ${limit}ms`,
+      calls_exceeded: `External calls ${actual} exceeded budget of ${limit}`,
+      tokens_exceeded: `Token count ${actual} exceeded budget of ${limit}`,
+    };
+    super(messages[reason]);
+    this.name = 'BudgetExceededError';
+    this.reason = reason;
+    this.limit = limit;
+    this.actual = actual;
+  }
+}
+
+/**
+ * Performance budget enforcer
+ *
+ * Tracks and enforces performance budgets during agent execution.
+ * Aborts execution if any budget is exceeded.
+ */
+export class BudgetEnforcer {
+  private readonly budget: PerformanceBudget;
+  private callCount: number = 0;
+  private tokenCount: number = 0;
+  private readonly startTime: number;
+  private aborted: boolean = false;
+  private abortReason?: BudgetViolationReason;
+
+  constructor(budget: PerformanceBudget = DEFAULT_BUDGETS) {
+    this.budget = { ...budget };
+    this.startTime = performance.now();
+  }
+
+  /**
+   * Get current budget configuration
+   */
+  getBudget(): PerformanceBudget {
+    return { ...this.budget };
+  }
+
+  /**
+   * Get current metrics
+   */
+  getMetrics(): BudgetMetrics {
+    return {
+      callCount: this.callCount,
+      startTime: this.startTime,
+      tokenCount: this.tokenCount,
+    };
+  }
+
+  /**
+   * Check if execution has been aborted
+   */
+  isAborted(): boolean {
+    return this.aborted;
+  }
+
+  /**
+   * Get abort reason if aborted
+   */
+  getAbortReason(): BudgetViolationReason | undefined {
+    return this.abortReason;
+  }
+
+  /**
+   * Record an external service call
+   * @throws {BudgetExceededError} if calls budget exceeded
+   */
+  recordCall(): void {
+    if (this.aborted) {
+      throw new BudgetExceededError(
+        this.abortReason!,
+        this.getLimitForReason(this.abortReason!),
+        this.getActualForReason(this.abortReason!)
+      );
+    }
+
+    this.callCount++;
+    if (this.callCount > this.budget.maxCallsPerRun) {
+      this.aborted = true;
+      this.abortReason = 'calls_exceeded';
+      throw new BudgetExceededError(
+        'calls_exceeded',
+        this.budget.maxCallsPerRun,
+        this.callCount
+      );
+    }
+  }
+
+  /**
+   * Record token usage
+   * @throws {BudgetExceededError} if token budget exceeded
+   */
+  recordTokens(count: number): void {
+    if (this.aborted) {
+      throw new BudgetExceededError(
+        this.abortReason!,
+        this.getLimitForReason(this.abortReason!),
+        this.getActualForReason(this.abortReason!)
+      );
+    }
+
+    this.tokenCount += count;
+    if (this.tokenCount > this.budget.maxTokens) {
+      this.aborted = true;
+      this.abortReason = 'tokens_exceeded';
+      throw new BudgetExceededError(
+        'tokens_exceeded',
+        this.budget.maxTokens,
+        this.tokenCount
+      );
+    }
+  }
+
+  /**
+   * Check current latency against budget
+   * @throws {BudgetExceededError} if latency budget exceeded
+   */
+  checkLatency(): void {
+    if (this.aborted) {
+      throw new BudgetExceededError(
+        this.abortReason!,
+        this.getLimitForReason(this.abortReason!),
+        this.getActualForReason(this.abortReason!)
+      );
+    }
+
+    const elapsed = performance.now() - this.startTime;
+    if (elapsed > this.budget.maxLatencyMs) {
+      this.aborted = true;
+      this.abortReason = 'latency_exceeded';
+      throw new BudgetExceededError(
+        'latency_exceeded',
+        this.budget.maxLatencyMs,
+        Math.round(elapsed)
+      );
+    }
+  }
+
+  /**
+   * Get elapsed time in milliseconds
+   */
+  getElapsedMs(): number {
+    return performance.now() - this.startTime;
+  }
+
+  /**
+   * Check all budgets without throwing
+   */
+  checkAll(): BudgetCheckResult {
+    const elapsed = Math.round(performance.now() - this.startTime);
+
+    // Check latency
+    if (elapsed > this.budget.maxLatencyMs) {
+      return {
+        withinBudget: false,
+        violation: {
+          reason: 'latency_exceeded',
+          limit: this.budget.maxLatencyMs,
+          actual: elapsed,
+          message: `Execution time ${elapsed}ms exceeded budget of ${this.budget.maxLatencyMs}ms`,
+        },
+      };
+    }
+
+    // Check calls
+    if (this.callCount > this.budget.maxCallsPerRun) {
+      return {
+        withinBudget: false,
+        violation: {
+          reason: 'calls_exceeded',
+          limit: this.budget.maxCallsPerRun,
+          actual: this.callCount,
+          message: `External calls ${this.callCount} exceeded budget of ${this.budget.maxCallsPerRun}`,
+        },
+      };
+    }
+
+    // Check tokens
+    if (this.tokenCount > this.budget.maxTokens) {
+      return {
+        withinBudget: false,
+        violation: {
+          reason: 'tokens_exceeded',
+          limit: this.budget.maxTokens,
+          actual: this.tokenCount,
+          message: `Token count ${this.tokenCount} exceeded budget of ${this.budget.maxTokens}`,
+        },
+      };
+    }
+
+    return { withinBudget: true };
+  }
+
+  /**
+   * Create an abort DecisionEvent for budget exceeded
+   */
+  createAbortEvent(params: {
+    agentId: string;
+    agentVersion: string;
+    inputsHash: string;
+    executionRef: string;
+    correlationId?: string;
+    tenantId?: string;
+    requestSource?: 'orchestrator' | 'inference_gateway' | 'policy_engine' | 'governance' | 'cli' | 'api';
+  }): DecisionEvent {
+    const result = this.checkAll();
+    const violation = result.violation;
+
+    const constraint: AppliedConstraint = {
+      type: 'budget_exceeded',
+      description: violation?.message ?? 'Performance budget exceeded',
+      severity: 'error',
+      metadata: violation
+        ? {
+            reason: violation.reason,
+            limit: violation.limit,
+            actual: violation.actual,
+          }
+        : undefined,
+    };
+
+    return createDecisionEvent({
+      agent_id: params.agentId,
+      agent_version: params.agentVersion,
+      decision_type: 'execution_aborted',
+      inputs_hash: params.inputsHash,
+      outputs: {
+        aborted: true,
+        reason: violation?.reason ?? 'budget_exceeded',
+        budget_limit: violation?.limit,
+        budget_actual: violation?.actual,
+        execution_time_ms: Math.round(this.getElapsedMs()),
+      },
+      confidence: { policy_match: 0 },
+      constraints_applied: [constraint],
+      execution_ref: params.executionRef,
+      correlation_id: params.correlationId,
+      tenant_id: params.tenantId,
+      request_source: params.requestSource,
+    });
+  }
+
+  /**
+   * Wrap an async operation with latency checking
+   */
+  async withLatencyCheck<T>(operation: () => Promise<T>): Promise<T> {
+    this.checkLatency();
+    const result = await operation();
+    this.checkLatency();
+    return result;
+  }
+
+  /**
+   * Wrap an external call with budget tracking
+   */
+  async trackCall<T>(operation: () => Promise<T>): Promise<T> {
+    this.recordCall();
+    this.checkLatency();
+    const result = await operation();
+    this.checkLatency();
+    return result;
+  }
+
+  private getLimitForReason(reason: BudgetViolationReason): number {
+    switch (reason) {
+      case 'latency_exceeded':
+        return this.budget.maxLatencyMs;
+      case 'calls_exceeded':
+        return this.budget.maxCallsPerRun;
+      case 'tokens_exceeded':
+        return this.budget.maxTokens;
+    }
+  }
+
+  private getActualForReason(reason: BudgetViolationReason): number {
+    switch (reason) {
+      case 'latency_exceeded':
+        return Math.round(this.getElapsedMs());
+      case 'calls_exceeded':
+        return this.callCount;
+      case 'tokens_exceeded':
+        return this.tokenCount;
+    }
+  }
+}
+
+/**
+ * Create a budget enforcer with custom limits
+ */
+export function createBudgetEnforcer(
+  overrides: Partial<PerformanceBudget> = {}
+): BudgetEnforcer {
+  return new BudgetEnforcer({
+    ...DEFAULT_BUDGETS,
+    ...overrides,
+  });
+}

package/dist/bundled-agents/data-vault-agents/src/ruvector-client/index.ts

@@ -0,0 +1,324 @@
+/**
+ * LLM-Data-Vault: RuVector Service Client
+ *
+ * Client for persisting DecisionEvents to ruvector-service.
+ * This is the ONLY persistence mechanism allowed for Data-Vault agents.
+ *
+ * CONSTITUTIONAL REQUIREMENT:
+ * - Data-Vault agents MUST NOT connect directly to Google SQL
+ * - Data-Vault agents persist data ONLY via ruvector-service client calls
+ *
+ * @module ruvector-client
+ */
+
+import { DecisionEvent, validateDecisionEvent } from '../contracts/index.js';
+
+/**
+ * RuVector service configuration
+ */
+export interface RuVectorConfig {
+  /** Service endpoint URL */
+  endpoint: string;
+  /** API key for authentication */
+  apiKey: string;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** Number of retry attempts */
+  retries?: number;
+  /** Retry backoff multiplier */
+  retryBackoff?: number;
+}
+
+/**
+ * RuVector persistence result
+ */
+export interface PersistResult {
+  success: boolean;
+  event_id?: string;
+  timestamp?: string;
+  error?: {
+    code: string;
+    message: string;
+    retryable: boolean;
+  };
+}
+
+/**
+ * RuVector query options
+ */
+export interface QueryOptions {
+  tenant_id?: string;
+  agent_id?: string;
+  decision_type?: string;
+  from_timestamp?: string;
+  to_timestamp?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * RuVector query result
+ */
+export interface QueryResult {
+  events: DecisionEvent[];
+  total_count: number;
+  has_more: boolean;
+}
+
+/**
+ * RuVector Service Client
+ *
+ * Provides async, non-blocking persistence for DecisionEvents.
+ */
+export class RuVectorClient {
+  private readonly config: Required<RuVectorConfig>;
+
+  constructor(config: RuVectorConfig) {
+    this.config = {
+      endpoint: config.endpoint,
+      apiKey: config.apiKey,
+      timeout: config.timeout ?? 5000,
+      retries: config.retries ?? 3,
+      retryBackoff: config.retryBackoff ?? 1.5,
+    };
+  }
+
+  /**
+   * Persist a DecisionEvent to ruvector-service
+   *
+   * This is an async, non-blocking write operation.
+   */
+  async persistDecisionEvent(event: DecisionEvent): Promise<PersistResult> {
+    // Validate event before persisting
+    const validatedEvent = validateDecisionEvent(event);
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt < this.config.retries; attempt++) {
+      try {
+        const response = await this.makeRequest('/api/v1/decision-events', {
+          method: 'POST',
+          body: JSON.stringify(validatedEvent),
+        });
+
+        if (response.ok) {
+          const result = await response.json() as { event_id: string; timestamp: string };
+          return {
+            success: true,
+            event_id: result.event_id,
+            timestamp: result.timestamp,
+          };
+        }
+
+        // Handle non-retryable errors
+        if (response.status >= 400 && response.status < 500) {
+          const errorBody = await response.json().catch(() => ({})) as { code?: string; message?: string };
+          return {
+            success: false,
+            error: {
+              code: errorBody.code ?? `HTTP_${response.status}`,
+              message: errorBody.message ?? response.statusText,
+              retryable: false,
+            },
+          };
+        }
+
+        // Retryable error
+        lastError = new Error(`HTTP ${response.status}: ${response.statusText}`);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+      }
+
+      // Wait before retry
+      if (attempt < this.config.retries - 1) {
+        const delay = Math.pow(this.config.retryBackoff, attempt) * 1000;
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+
+    return {
+      success: false,
+      error: {
+        code: 'PERSIST_FAILED',
+        message: lastError?.message ?? 'Unknown error',
+        retryable: true,
+      },
+    };
+  }
+
+  /**
+   * Batch persist multiple DecisionEvents
+   */
+  async persistBatch(events: DecisionEvent[]): Promise<PersistResult[]> {
+    // Validate all events
+    const validatedEvents = events.map(e => validateDecisionEvent(e));
+
+    try {
+      const response = await this.makeRequest('/api/v1/decision-events/batch', {
+        method: 'POST',
+        body: JSON.stringify({ events: validatedEvents }),
+      });
+
+      if (response.ok) {
+        const results = await response.json() as Array<{ event_id: string; timestamp: string }>;
+        return results.map(r => ({
+          success: true,
+          event_id: r.event_id,
+          timestamp: r.timestamp,
+        }));
+      }
+
+      const errorBody = await response.json().catch(() => ({})) as { code?: string; message?: string };
+      return events.map(() => ({
+        success: false,
+        error: {
+          code: errorBody.code ?? `HTTP_${response.status}`,
+          message: errorBody.message ?? response.statusText,
+          retryable: response.status >= 500,
+        },
+      }));
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return events.map(() => ({
+        success: false,
+        error: {
+          code: 'BATCH_PERSIST_FAILED',
+          message: errorMessage,
+          retryable: true,
+        },
+      }));
+    }
+  }
+
+  /**
+   * Query DecisionEvents (for audit/governance consumption)
+   */
+  async queryEvents(options: QueryOptions = {}): Promise<QueryResult> {
+    const params = new URLSearchParams();
+    if (options.tenant_id) params.set('tenant_id', options.tenant_id);
+    if (options.agent_id) params.set('agent_id', options.agent_id);
+    if (options.decision_type) params.set('decision_type', options.decision_type);
+    if (options.from_timestamp) params.set('from', options.from_timestamp);
+    if (options.to_timestamp) params.set('to', options.to_timestamp);
+    if (options.limit) params.set('limit', String(options.limit));
+    if (options.offset) params.set('offset', String(options.offset));
+
+    const response = await this.makeRequest(`/api/v1/decision-events?${params}`, {
+      method: 'GET',
+    });
+
+    if (!response.ok) {
+      throw new Error(`Query failed: HTTP ${response.status}`);
+    }
+
+    return response.json() as Promise<QueryResult>;
+  }
+
+  /**
+   * Get a single DecisionEvent by ID
+   */
+  async getEvent(eventId: string): Promise<DecisionEvent | null> {
+    const response = await this.makeRequest(`/api/v1/decision-events/${eventId}`, {
+      method: 'GET',
+    });
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new Error(`Get event failed: HTTP ${response.status}`);
+    }
+
+    return validateDecisionEvent(await response.json());
+  }
+
+  /**
+   * Health check
+   */
+  async healthCheck(): Promise<{ healthy: boolean; latency_ms: number }> {
+    const start = performance.now();
+
+    try {
+      const response = await this.makeRequest('/health', {
+        method: 'GET',
+      });
+
+      return {
+        healthy: response.ok,
+        latency_ms: performance.now() - start,
+      };
+    } catch {
+      return {
+        healthy: false,
+        latency_ms: performance.now() - start,
+      };
+    }
+  }
+
+  /**
+   * Make HTTP request to ruvector-service
+   */
+  private async makeRequest(
+    path: string,
+    options: RequestInit
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    try {
+      return await fetch(`${this.config.endpoint}${path}`, {
+        ...options,
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.config.apiKey}`,
+          'X-Service': 'llm-data-vault',
+          ...options.headers,
+        },
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+/**
+ * Create RuVector client from environment
+ *
+ * STANDARDIZED ENVIRONMENT VARIABLES (matching Google Secret Manager names):
+ * - RUVECTOR_SERVICE_URL: Service endpoint URL (required)
+ * - RUVECTOR_API_KEY: API key for authentication (required, from Secret Manager)
+ *
+ * NOTE: Legacy variable names (RUVECTOR_SERVICE_ENDPOINT, RUVECTOR_SERVICE_API_KEY)
+ * are supported for backward compatibility but deprecated.
+ */
+export function createRuVectorClient(): RuVectorClient {
+  // Use standardized names, fall back to legacy names for backward compatibility
+  const endpoint = process.env['RUVECTOR_SERVICE_URL']
+    ?? process.env['RUVECTOR_SERVICE_ENDPOINT'];
+  const apiKey = process.env['RUVECTOR_API_KEY']
+    ?? process.env['RUVECTOR_SERVICE_API_KEY'];
+
+  if (!endpoint) {
+    throw new Error('RUVECTOR_SERVICE_URL environment variable is required');
+  }
+  if (!apiKey) {
+    throw new Error('RUVECTOR_API_KEY environment variable is required (should come from Secret Manager)');
+  }
+
+  // Warn if using deprecated variable names
+  if (process.env['RUVECTOR_SERVICE_ENDPOINT'] && !process.env['RUVECTOR_SERVICE_URL']) {
+    console.warn('DEPRECATION WARNING: RUVECTOR_SERVICE_ENDPOINT is deprecated, use RUVECTOR_SERVICE_URL');
+  }
+  if (process.env['RUVECTOR_SERVICE_API_KEY'] && !process.env['RUVECTOR_API_KEY']) {
+    console.warn('DEPRECATION WARNING: RUVECTOR_SERVICE_API_KEY is deprecated, use RUVECTOR_API_KEY');
+  }
+
+  return new RuVectorClient({
+    endpoint,
+    apiKey,
+    timeout: parseInt(process.env['RUVECTOR_TIMEOUT'] ?? '5000', 10),
+    retries: parseInt(process.env['RUVECTOR_RETRIES'] ?? '3', 10),
+  });
+}

package/dist/bundled-agents/data-vault-agents/src/startup/index.ts

@@ -0,0 +1,17 @@
+/**
+ * LLM-Data-Vault: Startup Module
+ *
+ * Exports startup validation and configuration utilities.
+ *
+ * @module startup
+ */
+
+export {
+  validateEnvironment,
+  checkRuvectorHealth,
+  runStartupValidation,
+  setValidatedConfig,
+  getValidatedConfig,
+  type EnvironmentConfig,
+  type ValidationResult,
+} from './validation.js';