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

package/dist/bundled-agents/governance-dashboard-agents/src/infrastructure/decision-event-emitter.ts

@@ -0,0 +1,156 @@
+/**
+ * DecisionEvent Emitter
+ *
+ * Responsible for creating and emitting DecisionEvents to ruvector-service.
+ * Every agent invocation MUST emit exactly ONE DecisionEvent.
+ */
+
+import type {
+  DecisionEvent,
+  DecisionType,
+  Confidence,
+  ConstraintsApplied,
+} from '../contracts/decision-event.js';
+import { validateDecisionEvent } from '../contracts/decision-event.js';
+import {
+  computeInputsHash,
+  generateUUID,
+  getCurrentTimestamp,
+} from '../contracts/validation.js';
+import type { RuvectorClient } from './ruvector-client.js';
+
+/**
+ * Configuration for DecisionEvent emission
+ */
+export interface DecisionEventEmitterConfig {
+  /** RuVector client for persistence */
+  ruvectorClient: RuvectorClient;
+  /** Agent identifier */
+  agentId: string;
+  /** Agent version */
+  agentVersion: string;
+  /** Enable dry-run mode (no persistence) */
+  dryRun?: boolean;
+}
+
+/**
+ * Parameters for creating a DecisionEvent
+ */
+export interface CreateDecisionEventParams {
+  /** Type of decision */
+  decisionType: DecisionType;
+  /** Raw input (will be hashed) */
+  input: unknown;
+  /** Decision outputs */
+  outputs: Record<string, unknown>;
+  /** Confidence metrics */
+  confidence: Confidence;
+  /** Applied constraints */
+  constraintsApplied: ConstraintsApplied;
+  /** Execution reference (trace ID) */
+  executionRef: string;
+  /** Optional telemetry data */
+  telemetry?: {
+    latency_ms: number;
+    memory_mb?: number;
+    source_system?: string;
+  };
+}
+
+/**
+ * DecisionEvent Emitter
+ *
+ * Creates and persists DecisionEvents to ruvector-service.
+ */
+export class DecisionEventEmitter {
+  private readonly config: DecisionEventEmitterConfig;
+
+  constructor(config: DecisionEventEmitterConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Create and emit a DecisionEvent
+   *
+   * @param params - Parameters for the decision event
+   * @returns The created DecisionEvent
+   * @throws Error if validation or persistence fails
+   */
+  async emit(params: CreateDecisionEventParams): Promise<DecisionEvent> {
+    const event = this.createEvent(params);
+
+    // Validate the event against schema
+    const validatedEvent = validateDecisionEvent(event);
+
+    // Persist to ruvector-service (unless dry-run)
+    if (!this.config.dryRun) {
+      await this.persist(validatedEvent);
+    }
+
+    return validatedEvent;
+  }
+
+  /**
+   * Create a DecisionEvent without emitting
+   *
+   * Useful for testing or preview scenarios.
+   */
+  createEvent(params: CreateDecisionEventParams): DecisionEvent {
+    return {
+      id: generateUUID(),
+      agent_id: this.config.agentId,
+      agent_version: this.config.agentVersion,
+      decision_type: params.decisionType,
+      inputs_hash: computeInputsHash(params.input),
+      outputs: params.outputs,
+      confidence: params.confidence,
+      constraints_applied: params.constraintsApplied,
+      execution_ref: params.executionRef,
+      timestamp: getCurrentTimestamp(),
+      telemetry: params.telemetry,
+    };
+  }
+
+  /**
+   * Persist a DecisionEvent to ruvector-service
+   */
+  private async persist(event: DecisionEvent): Promise<void> {
+    await this.config.ruvectorClient.persistDecisionEvent(event);
+  }
+
+  /**
+   * Calculate overall confidence from component metrics
+   */
+  static calculateOverallConfidence(
+    coverage: number,
+    completeness: number
+  ): number {
+    // Weighted average: coverage is slightly more important
+    return coverage * 0.6 + completeness * 0.4;
+  }
+
+  /**
+   * Create a confidence object from component metrics
+   */
+  static createConfidence(
+    coverage: number,
+    completeness: number,
+    confidenceBand?: { lower: number; upper: number }
+  ): Confidence {
+    return {
+      coverage,
+      completeness,
+      confidence_band: confidenceBand,
+      overall: DecisionEventEmitter.calculateOverallConfidence(coverage, completeness),
+    };
+  }
+}
+
+/**
+ * Factory function to create a DecisionEventEmitter
+ */
+export function createDecisionEventEmitter(
+  config: DecisionEventEmitterConfig
+): DecisionEventEmitter {
+  return new DecisionEventEmitter(config);
+}

package/dist/bundled-agents/governance-dashboard-agents/src/infrastructure/execution-span-manager.ts

@@ -0,0 +1,213 @@
+/**
+ * Execution Span Manager
+ *
+ * Stateless utility functions for creating, managing, and finalizing
+ * execution spans. Each handler invocation constructs its own span tree.
+ *
+ * This module enforces the Foundational Execution Unit contract:
+ * - Every externally-invoked operation requires execution context
+ * - Repo-level spans wrap all agent executions
+ * - Agent-level spans are mandatory for every agent that executes
+ * - Artifacts are attached at the agent level only
+ * - No agent spans = execution is INVALID
+ */
+
+import { generateUUID, getCurrentTimestamp } from '../contracts/validation.js';
+import type { RepoSpan, AgentSpan, SpanArtifact } from '../contracts/execution-span.js';
+
+const REPO_NAME = 'llm-governance-dashboard';
+
+/**
+ * Execution context extracted from incoming request headers.
+ */
+export interface ExecutionContext {
+  execution_id: string;
+  parent_span_id: string;
+}
+
+/**
+ * Extract execution context from request headers.
+ * Returns null if required parent_span_id is missing.
+ *
+ * Required: x-parent-span-id
+ * execution_id: x-execution-id (preferred) or x-request-id (fallback)
+ */
+export function extractExecutionContext(
+  headers: Record<string, string | string[] | undefined>
+): ExecutionContext | null {
+  const parentSpanId = asString(headers['x-parent-span-id']);
+  if (!parentSpanId) {
+    return null;
+  }
+
+  const executionId = asString(headers['x-execution-id'])
+    ?? asString(headers['x-request-id']);
+  if (!executionId) {
+    return null;
+  }
+
+  return { execution_id: executionId, parent_span_id: parentSpanId };
+}
+
+/**
+ * Create a new repo-level span.
+ * Called once per handler invocation.
+ */
+export function createRepoSpan(ctx: ExecutionContext): RepoSpan {
+  return {
+    type: 'repo',
+    span_id: generateUUID(),
+    parent_span_id: ctx.parent_span_id,
+    execution_id: ctx.execution_id,
+    repo_name: REPO_NAME,
+    status: 'RUNNING',
+    start_time: getCurrentTimestamp(),
+    end_time: undefined,
+    agent_spans: [],
+  };
+}
+
+/**
+ * Create a new agent-level span.
+ * parent_span_id is always the repo span's span_id.
+ */
+export function createAgentSpan(
+  repoSpan: RepoSpan,
+  agentName: string
+): AgentSpan {
+  return {
+    type: 'agent',
+    span_id: generateUUID(),
+    parent_span_id: repoSpan.span_id,
+    agent_name: agentName,
+    repo_name: REPO_NAME,
+    status: 'RUNNING',
+    start_time: getCurrentTimestamp(),
+    end_time: undefined,
+    artifacts: [],
+  };
+}
+
+/**
+ * Attach an artifact (e.g. DecisionEvent) to an agent span.
+ * Artifacts MUST be attached at the agent level, never at repo level.
+ */
+export function attachArtifact(
+  agentSpan: AgentSpan,
+  artifactType: string,
+  data: Record<string, unknown>
+): void {
+  const artifact: SpanArtifact = {
+    artifact_id: generateUUID(),
+    artifact_type: artifactType,
+    data,
+  };
+  agentSpan.artifacts.push(artifact);
+}
+
+/**
+ * Finalize an agent span as COMPLETED.
+ */
+export function completeAgentSpan(agentSpan: AgentSpan): void {
+  agentSpan.status = 'COMPLETED';
+  agentSpan.end_time = getCurrentTimestamp();
+}
+
+/**
+ * Finalize an agent span as FAILED with error details.
+ */
+export function failAgentSpan(
+  agentSpan: AgentSpan,
+  error: { code: string; message: string; details?: Record<string, unknown> }
+): void {
+  agentSpan.status = 'FAILED';
+  agentSpan.end_time = getCurrentTimestamp();
+  agentSpan.error = error;
+}
+
+/**
+ * Finalize the repo span.
+ *
+ * ENFORCEMENT:
+ * - If no agent spans were emitted, status is FAILED (execution is INVALID)
+ * - If any agent span is FAILED, repo span is FAILED
+ * - Only COMPLETED if all agent spans are COMPLETED
+ * - All emitted spans are preserved regardless of status
+ */
+export function finalizeRepoSpan(repoSpan: RepoSpan): void {
+  repoSpan.end_time = getCurrentTimestamp();
+
+  if (repoSpan.agent_spans.length === 0) {
+    repoSpan.status = 'FAILED';
+    repoSpan.error = {
+      code: 'NO_AGENT_SPANS',
+      message: 'Execution completed without any agent spans. This is forbidden.',
+    };
+    return;
+  }
+
+  const hasFailedAgent = repoSpan.agent_spans.some(
+    (s) => s.status === 'FAILED'
+  );
+
+  if (hasFailedAgent) {
+    repoSpan.status = 'FAILED';
+    const failedAgents = repoSpan.agent_spans
+      .filter((s) => s.status === 'FAILED')
+      .map((s) => s.agent_name);
+    repoSpan.error = {
+      code: 'AGENT_EXECUTION_FAILED',
+      message: `Agent(s) failed: ${failedAgents.join(', ')}`,
+    };
+  } else {
+    repoSpan.status = 'COMPLETED';
+  }
+}
+
+/**
+ * Build the execution response envelope.
+ * This is the ONLY shape that handlers return for agent execution routes.
+ */
+export function buildExecutionResponse(
+  repoSpan: RepoSpan,
+  result?: Record<string, unknown>
+): {
+  execution_id: string;
+  repo_span: RepoSpan;
+  result?: Record<string, unknown>;
+} {
+  return {
+    execution_id: repoSpan.execution_id,
+    repo_span: repoSpan,
+    result,
+  };
+}
+
+/**
+ * Build a rejection response for when execution context is missing.
+ */
+export function buildContextRejectionResponse(): {
+  error: {
+    code: string;
+    message: string;
+    required_headers: string[];
+  };
+} {
+  return {
+    error: {
+      code: 'MISSING_EXECUTION_CONTEXT',
+      message:
+        'Execution rejected: parent_span_id is required. '
+        + 'This repo is a Foundational Execution Unit and must be invoked with execution context.',
+      required_headers: ['x-execution-id', 'x-parent-span-id'],
+    },
+  };
+}
+
+function asString(
+  value: string | string[] | undefined
+): string | undefined {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value) && value.length > 0) return value[0];
+  return undefined;
+}

package/dist/bundled-agents/governance-dashboard-agents/src/infrastructure/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Infrastructure Module
+ *
+ * Provides shared infrastructure components for governance agents:
+ * - RuVector client for persistence
+ * - DecisionEvent emitter
+ * - Telemetry integration
+ */
+
+export * from './ruvector-client.js';
+export * from './decision-event-emitter.js';
+export * from './telemetry.js';
+export * from './execution-span-manager.js';

package/dist/bundled-agents/governance-dashboard-agents/src/infrastructure/ruvector-client.ts

@@ -0,0 +1,286 @@
+/**
+ * RuVector Service Client
+ *
+ * Client for persisting governance artifacts to ruvector-service.
+ * ruvector-service is backed by Google SQL (Postgres).
+ *
+ * IMPORTANT:
+ * - LLM-Governance-Dashboard NEVER connects directly to Google SQL
+ * - LLM-Governance-Dashboard NEVER executes SQL
+ * - All persistence occurs via ruvector-service client calls only
+ */
+
+import type { DecisionEvent } from '../contracts/decision-event.js';
+import type { UsageOversightOutput } from '../contracts/usage-oversight.js';
+
+/**
+ * Configuration for RuVector client
+ */
+export interface RuvectorClientConfig {
+  /** Base URL of ruvector-service */
+  baseUrl: string;
+  /** API key for authentication */
+  apiKey: string;
+  /** Request timeout in milliseconds */
+  timeoutMs?: number;
+  /** Retry configuration */
+  retry?: {
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+  };
+}
+
+/**
+ * Response from ruvector-service
+ */
+export interface RuvectorResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+/**
+ * RuVector Service Client
+ *
+ * Handles all persistence operations for governance agents.
+ */
+export class RuvectorClient {
+  private readonly config: RuvectorClientConfig;
+  private readonly defaultTimeout = 30000;
+  private readonly defaultRetry = {
+    maxRetries: 3,
+    initialDelayMs: 100,
+    maxDelayMs: 5000,
+  };
+
+  constructor(config: RuvectorClientConfig) {
+    this.config = {
+      ...config,
+      timeoutMs: config.timeoutMs ?? this.defaultTimeout,
+      retry: config.retry ?? this.defaultRetry,
+    };
+  }
+
+  /**
+   * Persist a DecisionEvent
+   *
+   * Every agent invocation MUST call this exactly once.
+   * Falls back gracefully if RuVector endpoint is unavailable.
+   */
+  async persistDecisionEvent(event: DecisionEvent): Promise<void> {
+    try {
+      await this.post('/api/v1/decision-events', event);
+    } catch (error: any) {
+      // Graceful degradation: log but don't fail the agent
+      // Phase 4 Layer 1: Emit signal but don't block execution
+      console.warn(`[RuVector] Failed to persist DecisionEvent ${event.id}: ${error.message}`);
+      console.warn(`[RuVector] Event data logged for recovery:`, JSON.stringify({
+        id: event.id,
+        agent_id: event.agent_id,
+        decision_type: event.decision_type,
+        timestamp: event.timestamp,
+      }));
+      // Re-throw only for critical errors (auth failures)
+      if (error.status === 401 || error.status === 403) {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Persist a Usage Oversight output
+   */
+  async persistUsageOversightOutput(
+    decisionEventId: string,
+    output: UsageOversightOutput
+  ): Promise<void> {
+    await this.post(`/api/v1/decision-events/${decisionEventId}/outputs`, {
+      output_type: 'usage_oversight',
+      data: output,
+    });
+  }
+
+  /**
+   * Query historical DecisionEvents
+   */
+  async queryDecisionEvents(query: {
+    agent_id?: string;
+    decision_type?: string;
+    organization_id?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<DecisionEvent[]> {
+    const params = new URLSearchParams();
+    Object.entries(query).forEach(([key, value]) => {
+      if (value !== undefined) {
+        params.append(key, String(value));
+      }
+    });
+
+    const response = await this.get<{ items: DecisionEvent[] }>(
+      `/api/v1/decision-events?${params.toString()}`
+    );
+
+    return response.data?.items ?? [];
+  }
+
+  /**
+   * Get a specific DecisionEvent
+   */
+  async getDecisionEvent(id: string): Promise<DecisionEvent | null> {
+    try {
+      const response = await this.get<DecisionEvent>(
+        `/api/v1/decision-events/${id}`
+      );
+      return response.data ?? null;
+    } catch (error: any) {
+      if (error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Health check for ruvector-service
+   */
+  async healthCheck(): Promise<{
+    healthy: boolean;
+    latencyMs: number;
+    details?: Record<string, unknown>;
+  }> {
+    const start = Date.now();
+    try {
+      await this.get<{ status: string }>('/health');
+      return {
+        healthy: true,
+        latencyMs: Date.now() - start,
+      };
+    } catch (error: any) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - start,
+        details: {
+          error: error.message,
+        },
+      };
+    }
+  }
+
+  /**
+   * Perform a GET request
+   */
+  private async get<T>(path: string): Promise<RuvectorResponse<T>> {
+    return this.request<T>('GET', path);
+  }
+
+  /**
+   * Perform a POST request
+   */
+  private async post<T>(path: string, data: unknown): Promise<RuvectorResponse<T>> {
+    return this.request<T>('POST', path, data);
+  }
+
+  /**
+   * Perform an HTTP request with retry logic
+   */
+  private async request<T>(
+    method: string,
+    path: string,
+    data?: unknown
+  ): Promise<RuvectorResponse<T>> {
+    const url = `${this.config.baseUrl}${path}`;
+    const retry = this.config.retry ?? this.defaultRetry;
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt <= retry.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(
+          () => controller.abort(),
+          this.config.timeoutMs
+        );
+
+        const response = await fetch(url, {
+          method,
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.config.apiKey}`,
+            'X-Client': 'governance-dashboard-agents',
+          },
+          body: data ? JSON.stringify(data) : undefined,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+          const errorBody = await response.json().catch(() => ({})) as { message?: string; code?: string };
+          throw Object.assign(new Error(errorBody.message || response.statusText), {
+            status: response.status,
+            code: errorBody.code,
+          });
+        }
+
+        const responseData = await response.json() as T;
+        return { success: true, data: responseData };
+      } catch (err) {
+        const error = err as Error & { status?: number };
+        lastError = error instanceof Error ? error : new Error(String(err));
+
+        // Don't retry on client errors (4xx)
+        if (error.status && error.status >= 400 && error.status < 500) {
+          throw error;
+        }
+
+        // Calculate delay for next retry
+        if (attempt < retry.maxRetries) {
+          const delay = Math.min(
+            retry.initialDelayMs * Math.pow(2, attempt),
+            retry.maxDelayMs
+          );
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+
+    throw lastError || new Error('Request failed after retries');
+  }
+}
+
+/**
+ * Create a RuVector client from environment variables
+ */
+export function createRuvectorClientFromEnv(): RuvectorClient {
+  const baseUrl = process.env.RUVECTOR_SERVICE_URL;
+  const apiKey = process.env.RUVECTOR_API_KEY;
+
+  if (!baseUrl) {
+    throw new Error('RUVECTOR_SERVICE_URL environment variable is required');
+  }
+
+  if (!apiKey) {
+    throw new Error('RUVECTOR_API_KEY environment variable is required');
+  }
+
+  return new RuvectorClient({
+    baseUrl,
+    apiKey,
+    timeoutMs: parseInt(process.env.RUVECTOR_TIMEOUT_MS ?? '30000', 10),
+  });
+}
+
+/**
+ * Factory function to create a RuVector client
+ */
+export function createRuvectorClient(
+  config: RuvectorClientConfig
+): RuvectorClient {
+  return new RuvectorClient(config);
+}