@elevasis/core 0.1.0

package/src/operations/observability/types.ts

@@ -0,0 +1,463 @@
+import { LLMModel } from '../../execution/engine/llm/model-info'
+import type { ExecutionErrorCategory } from '../../execution/engine'
+import type { Database } from '../../supabase/database.types'
+
+// ============================================================================
+// Database Types
+// ============================================================================
+
+export type ExecutionMetricsRow = Database['public']['Tables']['execution_metrics']['Row']
+export type ExecutionMetricsInsert = Database['public']['Tables']['execution_metrics']['Insert']
+export type ExecutionMetricsUpdate = Database['public']['Tables']['execution_metrics']['Update']
+
+// ============================================================================
+// AI Call Tracking Types (SSOT)
+// ============================================================================
+
+export interface BaseAICall {
+  callSequence: number // 1, 2, 3... (execution-wide universal counter)
+  callType: 'agent-reasoning' | 'agent-completion' | 'workflow-step' | 'tool' | 'other'
+  model: LLMModel
+  inputTokens: number
+  outputTokens: number
+  costUsd: number // Cost in USD with full decimal precision
+  latencyMs: number
+  context?: AICallContext
+}
+
+export type AICallContext =
+  | AgentReasoningContext
+  | AgentCompletionContext
+  | WorkflowStepContext
+  | ToolCallContext
+  | OtherCallContext
+
+export interface AgentReasoningContext {
+  type: 'agent-reasoning'
+  iteration: number
+  actionsPlanned?: string[]
+  sessionId?: string
+  turnNumber?: number
+}
+
+export interface AgentCompletionContext {
+  type: 'agent-completion'
+  attempt: 1 | 2
+  validationFailed?: boolean
+  sessionId?: string
+  turnNumber?: number
+}
+
+export interface WorkflowStepContext {
+  type: 'workflow-step'
+  stepId: string
+  stepName?: string
+  stepSequence?: number
+}
+
+export interface ToolCallContext {
+  type: 'tool'
+  toolName: string
+  parentIteration?: number
+  parentStepId?: string
+}
+
+export interface OtherCallContext {
+  type: 'other'
+  description?: string
+  metadata?: Record<string, unknown>
+}
+
+export type AICallRecord = BaseAICall
+
+// ============================================================================
+// LLM Usage Data (from adapters)
+// ============================================================================
+
+/**
+ * Raw LLM usage data returned by adapters
+ * Used as input to AIUsageCollector.record()
+ */
+export interface LLMUsageData {
+  model: LLMModel
+  inputTokens: number
+  outputTokens: number
+  latencyMs: number
+  /** Actual cost from provider in USD (when available, e.g., OpenRouter) */
+  cost?: number
+}
+
+// ============================================================================
+// AI Usage Summary
+// ============================================================================
+
+export interface AIUsageSummary {
+  model: LLMModel
+  totalInputTokens: number
+  totalOutputTokens: number
+  totalTokens: number
+  totalCostUsd: number // Total cost in USD with full decimal precision
+  callCount: number
+  calls: AICallRecord[]
+}
+
+// ============================================================================
+// Execution Metrics
+// ============================================================================
+
+export interface ExecutionMetricsSummary {
+  durationMs?: number
+  automationSavingsUsd?: number // Automation savings in USD with full decimal precision
+}
+
+// ============================================================================
+// Resource Metrics Configuration
+// ============================================================================
+
+export interface ResourceMetricsConfig {
+  estimatedManualMinutes: number
+  hourlyLaborRateUsd: number // Hourly rate in USD (e.g., 75.00 for $75/hour)
+  confidenceLevel?: 'low' | 'medium' | 'high'
+  notes?: string
+}
+
+// ============================================================================
+// API Request/Response Types (Dashboard Observability)
+// ============================================================================
+
+/**
+ * Time range selector for dashboard metrics
+ */
+export type TimeRange = '1h' | '24h' | '7d' | '30d'
+
+/**
+ * ISO 8601 date range for API queries
+ */
+export interface TimeRangeDates {
+  startDate: string
+  endDate: string
+}
+
+/**
+ * Execution health metrics response
+ * Success rate, P95 duration, execution counts, and trend data
+ * trendData includes executionCount for throughput visualization (eliminates separate API call)
+ */
+export interface ExecutionHealthMetrics {
+  successRate: number
+  p95Duration: number
+  totalExecutions: number
+  trendData: Array<{
+    time: string
+    rate: number
+    successCount: number
+    errorCount: number
+    warningCount: number
+    executionCount: number
+  }>
+  statusCounts: { success: number; failed: number; pending: number; warning: number }
+  peakPeriod: string
+  granularity: 'hour' | 'day'
+}
+
+/**
+ * Error analysis metrics response
+ * Error categories and top failing resources
+ */
+export interface ErrorAnalysisMetrics {
+  totalErrors: number
+  errorsByCategory: Array<{
+    category: string
+    count: number
+    percentage: number
+  }>
+  topFailingResources: Array<{
+    resourceId: string
+    name: string
+    errorCount: number
+    failureRate: number
+  }>
+}
+
+/**
+ * Business impact metrics response
+ * ROI, labor savings, and cost analysis
+ */
+export interface BusinessImpactMetrics {
+  totalSavingsUsd: number
+  totalCostUsd: number
+  netSavingsUsd: number
+  roi: number
+}
+
+/**
+ * Cost breakdown metrics response
+ * Per-resource cost analysis
+ */
+export interface CostBreakdownMetrics {
+  resources: Array<{
+    resourceId: string
+    totalCostUsd: number
+    executionCount: number
+    avgCostUsd: number
+  }>
+}
+
+/**
+ * Detailed execution metrics response
+ * Full execution metrics with AI call breakdown
+ */
+export interface ExecutionMetricsDetail {
+  executionId: string
+  organizationId: string
+  resourceId: string
+  totalInputTokens: number
+  totalOutputTokens: number
+  totalCostUsd: number
+  aiCallCount: number
+  aiCalls: AICallRecord[]
+  durationMs?: number
+  automationSavingsUsd?: number
+  createdAt: string
+}
+
+/**
+ * Dashboard metrics response
+ * Aggregates core observability metrics in a single response
+ * Note: Throughput data is now included in executionHealth.trendData.executionCount
+ */
+export interface DashboardMetrics {
+  executionHealth: ExecutionHealthMetrics
+  costBreakdown: CostBreakdownMetrics
+  businessImpact: BusinessImpactMetrics
+  /** ISO timestamp of the currently active deployment, or null if none */
+  activeDeploymentDate: string | null
+  /** Deployment version of the active deployment, or null if none */
+  activeDeploymentVersion: string | null
+}
+
+// ============================================================================
+// Error Tracking Types
+// ============================================================================
+
+/**
+ * Error record for list view (ErrorBreakdownTable)
+ */
+export interface ErrorRecord {
+  id: string // execution_errors.id
+  timestamp: string // occurred_at
+  errorType: string // error_type
+  message: string // error_message
+  executionId: string // execution_id
+  resourceId: string // execution_logs.resource_id (via JOIN)
+  resourceName: string // execution_logs.resource_id (TODO: resolve via registry)
+  severity: 'critical' | 'warning' | 'info'
+  category: ExecutionErrorCategory // error_category (moved from metadata to dedicated column)
+  resolved: boolean // resolved flag (human acknowledgment, does not affect execution status)
+  resolvedAt: string | null // timestamp when resolved
+  resolvedBy: string | null // user ID who resolved
+}
+
+/**
+ * Full error detail for modal view (ErrorDetailsModal)
+ */
+export interface ErrorDetailFull extends ErrorRecord {
+  stackTrace?: string // error_stack_trace
+  retryAttempt?: number // metadata.retryAttempt
+  stepName?: string // metadata.stepName
+  stepSequence?: number // metadata.stepSequence
+  errorContext?: Record<string, unknown> // metadata.errorContext
+  executionContext?: Record<string, unknown> // metadata.executionContext
+}
+
+/**
+ * Error details API response (paginated)
+ */
+export interface ErrorDetailResponse {
+  errors: ErrorRecord[]
+  total: number
+  page: number
+  limit: number
+}
+
+/**
+ * Error distribution for analytics (pie/bar charts)
+ */
+export interface ErrorDistribution {
+  label: string // Error type, severity, or category
+  count: number // Number of occurrences
+  percentage: number // Percentage of total
+}
+
+/**
+ * Error trend data for time-series charts
+ */
+export interface ErrorTrend {
+  time: string // Time bucket (ISO timestamp)
+  errorCount: number // Total errors in bucket
+  criticalCount: number // Critical errors in bucket
+  warningCount: number // Warning errors in bucket
+  infoCount: number // Info errors in bucket
+}
+
+/**
+ * Failing resource data for health monitoring
+ */
+export interface FailingResource {
+  resourceId: string
+  resourceName: string // TODO: Resolve via registry
+  errorCount: number
+  criticalCount: number
+  warningCount: number
+  mostCommonError: string
+}
+
+// ============================================================================
+// Recent Executions by Resource Types (Dashboard)
+// ============================================================================
+
+/**
+ * Summary of executions for a single resource
+ * Used by RecentExecutionsByResource dashboard component
+ */
+export interface ResourceExecutionSummary {
+  resourceId: string // resource_id from execution_logs
+  resourceType: string // Inferred from resource definitions (resolved by frontend)
+  resourceName: string | null // From resource registry lookup (resolved by frontend)
+  lastExecution: string // ISO timestamp (MAX started_at)
+  totalExecutions: number // COUNT(*)
+  successCount: number // COUNT WHERE status='completed' OR status='warning'
+  failureCount: number // COUNT WHERE status='failed'
+  warningCount: number // COUNT WHERE status='warning' (subset of success)
+  successRate: number // (successCount / totalExecutions) * 100
+}
+
+/**
+ * Response from getRecentExecutionsByResource endpoint
+ */
+export interface RecentExecutionsByResourceResponse {
+  resources: ResourceExecutionSummary[]
+}
+
+// ============================================================================
+// Per-Resource Health Types (Dashboard Recent Activity)
+// ============================================================================
+
+/** Resource identifier for health queries */
+export interface ResourceIdentifier {
+  entityType: string // 'workflow' | 'agent'
+  entityId: string // Resource ID
+}
+
+/** Time-bucketed health data point */
+export interface ResourceHealthDataPoint {
+  time: string // ISO timestamp (bucket start)
+  success: number // Success count in bucket (completed + warning)
+  failure: number // Failure count in bucket
+  warning: number // Warning count in bucket (subset of success)
+  rate: number // Success rate (0-100)
+}
+
+/** Health data for a single resource */
+export interface ResourceHealth {
+  entityType: string
+  entityId: string
+  entityName: string | null
+  trendData: ResourceHealthDataPoint[]
+  summary: {
+    total: number
+    successRate: number
+  }
+}
+
+/** Batch request for multiple resources */
+export interface ResourcesHealthRequest {
+  resources: ResourceIdentifier[]
+  startDate: string // ISO datetime
+  endDate: string // ISO datetime
+  granularity: 'hour' | 'day'
+}
+
+/** Batch response with all requested resources */
+export interface ResourcesHealthResponse {
+  resources: ResourceHealth[]
+}
+
+// ============================================================================
+// Cost Analytics Types (Time-Series)
+// ============================================================================
+
+/**
+ * Cost trend data point for time-series charts
+ * Represents a single time bucket (hour or day)
+ */
+export interface CostTrendDataPoint {
+  time: string // ISO timestamp (bucket start)
+  totalCostUsd: number
+  executionCount: number
+  avgCostPerExecution: number
+}
+
+/**
+ * Cost trends response (time-series data)
+ */
+export interface CostTrendsResponse {
+  trendData: CostTrendDataPoint[]
+  granularity: 'hour' | 'day'
+  totalCostUsd: number
+  totalExecutions: number
+}
+
+/**
+ * Cost summary response with MTD and projections
+ */
+export interface CostSummaryResponse {
+  current: {
+    totalCostUsd: number
+    executionCount: number
+  }
+  previous: {
+    totalCostUsd: number
+    executionCount: number
+  }
+  mtd: {
+    totalCostUsd: number
+    daysElapsed: number
+  }
+  projection: {
+    monthlyCostUsd: number
+    confidence: 'low' | 'medium' | 'high'
+  }
+  trend: {
+    changePercent: number
+    direction: 'up' | 'down' | 'flat'
+  }
+}
+
+/**
+ * Cost by model data for model-level breakdown
+ */
+export interface CostByModelData {
+  model: string
+  totalCostUsd: number
+  callCount: number
+  totalInputTokens: number
+  totalOutputTokens: number
+  avgCostPerCall: number
+}
+
+/**
+ * Cost by model response
+ */
+export interface CostByModelResponse {
+  models: CostByModelData[]
+  totalCostUsd: number
+  totalCallCount: number
+}
+
+// ============================================================================
+// Collector Classes
+// ============================================================================
+
+export { AIUsageCollector } from './ai-usage-collector'
+export { MetricsCollector } from './metrics-collector'

package/src/operations/observability/utils.ts

@@ -0,0 +1,77 @@
+/**
+ * Time range utility functions
+ * Converts TimeRange enum to ISO 8601 date strings and labels
+ */
+
+import type { TimeRange, TimeRangeDates } from './types'
+
+/**
+ * Convert TimeRange to start and end ISO 8601 date strings
+ * @param range - Time range enum (1h, 24h, 7d, 30d)
+ * @returns Object with startDate and endDate as ISO 8601 strings
+ */
+export function getTimeRangeDates(range: TimeRange): TimeRangeDates {
+  const end = new Date()
+  const start = new Date()
+
+  switch (range) {
+    case '1h':
+      start.setHours(start.getHours() - 1)
+      break
+    case '24h':
+      start.setHours(start.getHours() - 24)
+      break
+    case '7d':
+      start.setDate(start.getDate() - 7)
+      break
+    case '30d':
+      start.setDate(start.getDate() - 30)
+      break
+  }
+
+  return {
+    startDate: start.toISOString(),
+    endDate: end.toISOString()
+  }
+}
+
+/**
+ * Get a human-readable label for a time range
+ * @param range - Time range enum
+ * @returns Human-readable label
+ */
+export function getTimeRangeLabel(range: TimeRange): string {
+  switch (range) {
+    case '1h':
+      return 'Last 1 hour'
+    case '24h':
+      return 'Last 24 hours'
+    case '7d':
+      return 'Last 7 days'
+    case '30d':
+      return 'Last 30 days'
+  }
+}
+
+/**
+ * Format a time-bucket timestamp for chart axis labels
+ * @param timestamp - ISO 8601 timestamp string
+ * @param granularity - 'hour' renders as "HH:MM" (24h), 'day' renders as "Mon DD"
+ * @returns Formatted time string for display
+ */
+export function formatBucketTime(timestamp: string, granularity: 'hour' | 'day'): string {
+  const date = new Date(timestamp)
+
+  if (granularity === 'hour') {
+    return date.toLocaleTimeString('en-US', {
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: false
+    })
+  }
+
+  return date.toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric'
+  })
+}