Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
19.7 KB
Raw Blame
'use client'

import { apiGet } from './api'
import type { TraceApiQuery } from './governedTraceFilters'

export const GOVERNED_EVENT_FAMILIES = [
  'agent_run',
  'administrative',
  'infrastructure_telemetry',
] as const

export type GovernedEventFamily = (typeof GOVERNED_EVENT_FAMILIES)[number]

export type GovernedTraceEvent = {
  streamSequence: string
  eventFamily: GovernedEventFamily
  eventId: string
  schemaVersion: number
  occurredAt: string
  ingestedAt: string
  correlationRef: string | null
  sessionId: string | null
  actorKind: string | null
  actorSub: string | null
  serviceOrAgentSub: string | null
  initiatingHumanSub: string | null
  decisionActorSub: string | null
  actingAgentSub: string | null
  resourceAud: string | null
  effectiveScopes: string[]
  authorizationDecision: string | null
  tokenExchangeId: string | null
  eventType: string
  outcome: string | null
  targetType: string | null
  targetRef: string | null
  recipeNamespace: string | null
  recipeName: string | null
  hostRef: string | null
  operatorUserId?: string | null
  operatorPrincipalId?: string | null
  operatorPrincipalKind?: 'control_admin' | 'platform_user' | 'system' | 'unresolved'
  operatorDisplayName?: string | null
  delegatedActorSub?: string | null
  sourceKind?: string | null
  sourceService?: string | null
  serviceSub?: string | null
  targetUserId?: string | null
  targetUserSub?: string | null
  targetUserDisplayName?: string | null
  teamId?: string | null
  targetTeamDisplayName?: string | null
  telemetryType?: string | null
  reasonCode?: string | null
  clusterName?: string | null
  namespace?: string | null
  workloadKind?: string | null
  workloadRef?: string | null
  controller?: string | null
  payload: Record<string, unknown>
}

export type GovernedTracePage = {
  events: GovernedTraceEvent[]
  nextCursor: string | null
  capturedHighWatermark: string
}

export type GovernedTraceQuery = {
  [key: string]: string | readonly GovernedEventFamily[] | undefined
  cursor?: string
  families?: readonly GovernedEventFamily[]
  order?: 'oldest' | 'latest'
  occurredFrom?: string
  occurredTo?: string
}

export type TraceAttributionStatus = 'verified' | 'verified_late' | 'mixed' | 'unavailable'
export type AdministrativeIdentityStatus =
  | 'verified'
  | 'verified_late'
  | 'legacy'
  | 'system'
  | 'unavailable'
export type GovernedTracePrincipalKind = 'control_admin' | 'platform_user' | 'system' | 'unresolved'
export type PromptHistoryAvailability =
  | 'available'
  | 'disabled'
  | 'none'
  | 'expired'
  | 'unavailable'
export type GovernedToolKind = 'internal_tool' | 'mcp_server_tool' | 'workflow' | 'unclassified'

export type GovernedTraceTokenUsageSummary = {
  observedLlmCalls: number
  meteredCalls: number
  coverage: 'complete' | 'partial' | 'unavailable' | 'not_applicable'
  inputTokens: number
  outputTokens: number
  cacheReadTokens: number
  cacheWriteTokens: number
  cacheReporting: 'complete' | 'partial' | 'unavailable' | 'not_applicable'
  totalTokens: number
}

export type GovernedTraceSessionSummaryV1 = {
  hostRef: string
  sessionId: string
  origins: Array<'direct_chat' | 'channel_event' | 'api' | 'workflow_runtime'>
  firstOccurredAt: string
  lastOccurredAt: string
  runCount: number
  eventCount: number
  latestRunOutcome: 'started' | 'succeeded' | 'failed' | 'cancelled' | 'unknown' | null
  agent: {
    status: Exclude<TraceAttributionStatus, 'verified_late'>
    subject: string | null
    displayName: string | null
  }
  human: {
    status: TraceAttributionStatus
    subject: string | null
    userId: string | null
    displayName: string | null
    identityIssuer: string | null
  }
  tools: {
    totalCalls: number
    distinctTools: number
    byKind: Record<GovernedToolKind, number>
  }
  tokenUsage: GovernedTraceTokenUsageSummary
  approvals: {
    requested: number
    approved: number
    denied: number
    promptHistory: PromptHistoryAvailability
  }
}

export type GovernedTraceSessionPage = {
  sessions: GovernedTraceSessionSummaryV1[]
  nextCursor: string | null
  capturedHighWatermark: string
}

export type GovernedTraceSessionRun = {
  runId: string
  startedAt: string
  endedAt: string | null
  outcome: string
  origin: 'direct_chat' | 'channel_event' | 'api' | 'workflow_runtime'
  eventCount: number
}

export type GovernedTraceToolUsage = {
  toolName: string
  toolKind: GovernedToolKind
  toolSourceRef: string | null
  totalCalls: number
  succeeded: number
  failed: number
  firstOccurredAt: string
  lastOccurredAt: string
}

export type GovernedTraceApproval = {
  approvalRequestId: string | null
  runId: string
  source: 'tool' | 'workflow'
  toolName: string | null
  toolKind: GovernedToolKind | null
  toolSourceRef: string | null
  requestedAt: string | null
  decidedAt: string | null
  state: 'requested' | 'approved' | 'denied' | 'unavailable'
  decisionActorSub: string | null
  observedExecution: 'succeeded' | 'failed' | 'not_observed'
  promptHistory: PromptHistoryAvailability
}

export type GovernedTraceInteraction = {
  streamSequence: string
  eventId: string
  runId: string
  eventType: string
  occurredAt: string
  outcome: string
  toolName: string | null
  toolKind: GovernedToolKind | null
  toolSourceRef: string | null
  approvalRequestId: string | null
  decision: string
  decisionActorSub: string | null
  safeFields: Record<string, string | number | boolean | null>
}

export type GovernedTraceTokenUsagePoint = {
  streamSequence: string
  eventId: string
  runId: string
  occurredAt: string
  provider: string
  model: string
  sourceKind: string
  iteration: number | null
  inputTokens: number
  outputTokens: number
  cacheReadTokens: number
  cacheWriteTokens: number
  cacheTokensReported: boolean
}

export type GovernedTraceTokenUsage = GovernedTraceTokenUsageSummary & {
  points: GovernedTraceTokenUsagePoint[]
  pointsTruncated: boolean
}

export type GovernedTraceSessionDetail = {
  summary: GovernedTraceSessionSummaryV1
  runs: GovernedTraceSessionRun[]
  tools: GovernedTraceToolUsage[]
  approvals: GovernedTraceApproval[]
  tokenUsage: GovernedTraceTokenUsage
  interactions: GovernedTraceInteraction[]
  nextCursor: string | null
  capturedHighWatermark: string
}

export type GovernedAdministrativeEventDetail = {
  eventId: string
  occurredAt: string
  ingestedAt: string
  action: string
  outcome: string
  operatorHuman: {
    status: AdministrativeIdentityStatus
    principalKind: GovernedTracePrincipalKind
    principalId: string | null
    subject: string | null
    userId: string | null
    displayName: string | null
    identityIssuer: string | null
  }
  delegatedActor: { subject: string | null }
  evidenceProducer: {
    sourceKind: string
    sourceService: string
    serviceSub: string
  }
  authorization: {
    resourceAud: string | null
    effectiveScopes: string[]
    tokenExchangeId: string | null
    decision: string | null
    decisionActorSub: string | null
    approvalRequestId: string | null
    operationId: string | null
    requestId: string | null
    relatedRunId: string | null
  }
  context: {
    environment: string | null
    namespace: string | null
    deploymentRef: string | null
    teamId: string | null
    teamDisplayName: string | null
  }
  provenance: {
    sourceAuditRef: string | null
    sourceAdapterKind: string | null
    sourceAdapterVersion: string | null
    codeDigest: string | null
    configDigest: string | null
    policyDigest: string | null
    authorizationRef: string | null
    effectRef: string | null
    preStateDigest: string | null
    postStateDigest: string | null
    payloadSha256: string
  }
  targetResource: { type: string; ref: string }
  targetHuman: {
    status: AdministrativeIdentityStatus
    principalKind: GovernedTracePrincipalKind
    principalId: string | null
    subject: string | null
    userId: string | null
    displayName: string | null
    identityIssuer: string | null
  }
  safeFields: Record<string, string | number | boolean | null>
}

export type GovernedInfrastructureEventDetail = {
  eventId: string
  occurredAt: string
  ingestedAt: string
  telemetryType: string
  outcome: string
  reasonCode: string | null
  triggerKind: string
  source: {
    sourceKind: string
    sourceService: string
    controller: string
    sourceOccurrenceId: string
    sourceAdapterKind: string | null
    sourceAdapterVersion: string | null
  }
  scope: {
    environment: string
    clusterName: string
    namespace: string
    workloadKind: string
    workloadRef: string
    kubernetesKind: string
    kubernetesName: string
    kubernetesUid: string | null
    metadataGeneration: string | null
  }
  correlation: {
    operationId: string | null
    runId: string | null
    authorizationRef: string | null
    effectRef: string | null
  }
  interval: { start: string | null; end: string | null }
  capacity: {
    desiredReplicas: number | null
    observedReplicas: number | null
    readyReplicas: number | null
    cpuRequestCores: string | null
    cpuLimitCores: string | null
    memoryRequestBytes: string | null
    memoryLimitBytes: string | null
  }
  usage: { cpuUsageCoreSeconds: string | null; memoryUsageByteSeconds: string | null }
  integrity: {
    codeDigest: string | null
    configDigest: string | null
    policyDigest: string | null
    preStateDigest: string | null
    postStateDigest: string | null
    payloadSha256: string
  }
  safeFields: Record<string, string | number | boolean | null>
}

export type GovernedApprovalPromptHistory = {
  approvalRequestId: string
  availability: PromptHistoryAvailability
  prompt: null | {
    text: string
    capturedAt: string
    expiresAt: string
    keyVersion: string
    redactionSummary: { redacted: boolean; replacementCount: number }
  }
}

export type TracingOperationsHealth = 'healthy' | 'warning' | 'critical'
export type TracingOperationsSeverity = 'critical' | 'warning' | 'info'

export type TracingOperationsSnapshot = {
  generatedAt: string
  instanceStartedAt: string
  scope: 'control-api-instance'
  health: TracingOperationsHealth
  limits: {
    bodyBytes: number
    eventsPerRequest: number
    maxInFlight: number
    ingestPoolMax: number
    readPoolMax: number
    poolConnectionTimeoutMs: number
    ingestStatementTimeoutMs: number
    readStatementTimeoutMs: number
    recentErrorSeconds: number
  }
  ingestion: {
    acceptedEvents: number
    replayedEvents: number
    rejectedEvents: number
    conflictingEvents: number
    admissionRequests: number
    admissionRejected: number
    inFlight: number
  }
  pools: Array<{
    name: 'ingest' | 'read'
    active: number
    idle: number
    waiting: number
    rejectedSinceRestart: number
    statementTimeoutsSinceRestart: number
  }>
  errors: Array<{
    reason: string
    message: string
    severity: TracingOperationsSeverity
    countSinceRestart: number
    lastOccurredAt: string | null
    relatedSetting: string | null
    effectiveValue: number | null
    operatorAction: string
  }>
}

export type InfrastructureCostPeriod = 'day' | 'week' | 'month'

export type InfrastructureCostDimensions = {
  cloudProvider: 'gcp'
  cloudProjectId: string
  clusterLocation: string
  clusterName: string
  environment: string
  namespace: string
  workloadKind: string
  workloadRef: string
  currency: string
}

export type InfrastructureCostQuery = {
  period: InfrastructureCostPeriod
  anchorDate: string
  valuation: 'estimated' | 'billed' | 'variance'
  basis: 'requested_capacity' | 'gcp_request_allocation'
} & InfrastructureCostDimensions

export type InfrastructureCostScope = {
  dimensions: InfrastructureCostDimensions
  firstUtcDay: string
  lastUtcDay: string
  availableValuations: readonly ('estimated' | 'billed')[]
  latestAsOfUtc: string
  billingExportWatermark: string | null
  billingLagHours: number | null
}

export type InfrastructureCostScopeCatalog = {
  scopes: readonly InfrastructureCostScope[]
  truncated: boolean
}

export type InfrastructureCostComponent = {
  componentKey: string
  resourceClass: string
  allocationBucket: string | null
  unitHours: string | null
  priceSnapshotId: string | null
  providerService: string | null
  providerSku: string | null
  billingViewVersion: string | null
  sourceRowCount: number | null
  sourceSha256: string
  billingExportWatermark: string | null
  grossAmount: string
  creditsAmount: string
  netAmount: string
  priceSourceRef?: string | null
  priceEffectiveFrom?: string | null
  priceUnitPrice?: string | null
}

export type InfrastructureCostSelection = {
  period: InfrastructureCostPeriod
  periodStartUtc: string
  periodEndUtc: string
  sourceDailyVersionHash: string
  dailyVersionVector: readonly { utcDay: string; id: string; rollupVersion: number }[]
  publicationState: 'provisional' | 'finalized'
  completenessStatus: 'complete' | 'partial' | 'unavailable'
  grossAmount: string
  creditsAmount: string
  netAmount: string
  overheadAmount: string
  unallocatedAmount: string
  unsupportedAmount: string
  valuationKind: 'estimated' | 'billed'
  selectedBasis: 'requested_capacity' | 'gcp_request_allocation'
  asOfUtc: string
  billingExportWatermark: string | null
  billingLagHours: number | null
  billingFreshnessStatus: 'fresh' | 'stale' | 'unavailable' | 'not_applicable'
  components: readonly InfrastructureCostComponent[]
}

export type InfrastructureCostResponse = {
  period: InfrastructureCostPeriod
  periodStartUtc: string
  periodEndUtc: string
  dimensions: InfrastructureCostDimensions
  requestedCapacity: InfrastructureCostSelection | null
  gcpRequestAllocation: InfrastructureCostSelection | null
  variance?: {
    netAmount: string
    billedBasis: 'gcp_request_allocation'
    estimateBasis: 'requested_capacity'
  }
}

function queryForTraceRead(query: GovernedTraceQuery): Record<string, string | undefined> {
  const encoded = Object.fromEntries(
    Object.entries(query).filter((entry): entry is [string, string] => typeof entry[1] === 'string')
  )
  return {
    ...encoded,
    cursor: query.cursor,
    families: query.families?.join(','),
    order: query.order,
    occurredFrom: query.occurredFrom,
    occurredTo: query.occurredTo,
  }
}

export async function getGovernedTraceEvents(
  path: string,
  query: GovernedTraceQuery = {},
  signal?: AbortSignal
): Promise<GovernedTracePage> {
  return apiGet(path, queryForTraceRead(query), { signal }) as Promise<GovernedTracePage>
}

export async function getGovernedTraceSessions(
  query: TraceApiQuery = {},
  signal?: AbortSignal
): Promise<GovernedTraceSessionPage> {
  return apiGet('/api/v1/admin/tracing/sessions', query, {
    signal,
  }) as Promise<GovernedTraceSessionPage>
}

export async function getGovernedTraceSessionDetail(
  hostRef: string,
  sessionId: string,
  query: TraceApiQuery = {},
  signal?: AbortSignal
): Promise<GovernedTraceSessionDetail> {
  return apiGet(
    `/api/v1/admin/tracing/sessions/${encodeURIComponent(hostRef)}/${encodeURIComponent(sessionId)}`,
    query,
    { signal }
  ) as Promise<GovernedTraceSessionDetail>
}

export async function getGovernedAdministrativeEventDetail(
  eventId: string,
  signal?: AbortSignal
): Promise<GovernedAdministrativeEventDetail> {
  return apiGet(
    `/api/v1/admin/tracing/administrative/${encodeURIComponent(eventId)}`,
    {},
    { signal }
  ) as Promise<GovernedAdministrativeEventDetail>
}

export async function getGovernedInfrastructureEventDetail(
  eventId: string,
  signal?: AbortSignal
): Promise<GovernedInfrastructureEventDetail> {
  return apiGet(
    `/api/v1/admin/tracing/infrastructure/${encodeURIComponent(eventId)}`,
    {},
    { signal }
  ) as Promise<GovernedInfrastructureEventDetail>
}

export async function getGovernedApprovalPromptHistory(
  approvalRequestId: string
): Promise<GovernedApprovalPromptHistory> {
  return apiGet(
    `/api/v1/admin/tracing/approvals/${encodeURIComponent(approvalRequestId)}/prompt-history`
  ) as Promise<GovernedApprovalPromptHistory>
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return Boolean(value && typeof value === 'object' && !Array.isArray(value))
}

function isFiniteNumber(value: unknown): value is number {
  return typeof value === 'number' && Number.isFinite(value) && value >= 0
}

function isTimestamp(value: unknown): value is string {
  return typeof value === 'string' && Number.isFinite(Date.parse(value))
}

function isTracingOperationsSnapshot(value: unknown): value is TracingOperationsSnapshot {
  if (!isRecord(value) || value.scope !== 'control-api-instance') return false
  if (!['healthy', 'warning', 'critical'].includes(String(value.health))) return false
  if (!isTimestamp(value.generatedAt) || !isTimestamp(value.instanceStartedAt)) return false
  if (!isRecord(value.limits) || !isRecord(value.ingestion)) return false
  const limitKeys = [
    'bodyBytes',
    'eventsPerRequest',
    'maxInFlight',
    'ingestPoolMax',
    'readPoolMax',
    'poolConnectionTimeoutMs',
    'ingestStatementTimeoutMs',
    'readStatementTimeoutMs',
    'recentErrorSeconds',
  ]
  const ingestionKeys = [
    'acceptedEvents',
    'replayedEvents',
    'rejectedEvents',
    'conflictingEvents',
    'admissionRequests',
    'admissionRejected',
    'inFlight',
  ]
  if (!limitKeys.every(key => isFiniteNumber(value.limits[key]))) return false
  if (!ingestionKeys.every(key => isFiniteNumber(value.ingestion[key]))) return false
  if (!Array.isArray(value.pools) || value.pools.length !== 2) return false
  if (!Array.isArray(value.errors) || value.errors.length > 10) return false
  const poolNames = new Set<string>()
  const poolsValid = value.pools.every(pool => {
    if (!isRecord(pool) || !['ingest', 'read'].includes(String(pool.name))) return false
    poolNames.add(String(pool.name))
    return [
      'active',
      'idle',
      'waiting',
      'rejectedSinceRestart',
      'statementTimeoutsSinceRestart',
    ].every(key => isFiniteNumber(pool[key]))
  })
  if (!poolsValid || poolNames.size !== 2) return false
  const reasons = [
    'unsupported_content_type',
    'invalid_json',
    'body_too_large',
    'batch_too_large',
    'capacity_exhausted',
    'event_rejected',
    'idempotency_conflict',
    'submission_failed',
    'pool_rejected',
    'statement_timeout',
    'attribution_binding_unavailable',
    'attribution_binding_conflict',
    'prompt_history_disabled',
    'prompt_history_key_unavailable',
    'prompt_history_rejected',
  ]
  return value.errors.every(error => {
    if (!isRecord(error) || !reasons.includes(String(error.reason))) return false
    if (!['critical', 'warning', 'info'].includes(String(error.severity))) return false
    if (typeof error.message !== 'string' || typeof error.operatorAction !== 'string') return false
    if (!isFiniteNumber(error.countSinceRestart)) return false
    if (error.lastOccurredAt !== null && !isTimestamp(error.lastOccurredAt)) return false
    if (error.relatedSetting !== null && typeof error.relatedSetting !== 'string') return false
    return error.effectiveValue === null || isFiniteNumber(error.effectiveValue)
  })
}

export async function getTracingOperationsSnapshot(
  signal?: AbortSignal
): Promise<TracingOperationsSnapshot> {
  const value = await apiGet('/api/v1/admin/tracing/operations', {}, { signal })
  if (!isTracingOperationsSnapshot(value)) {
    throw new Error('Control API returned an invalid tracing operations snapshot.')
  }
  return value
}

export function isTraceCostsUnavailable(error: unknown): boolean {
  return Boolean(
    error &&
    typeof error === 'object' &&
    'status' in error &&
    (error as { status?: unknown }).status === 501
  )
}

export async function getInfrastructureTraceCosts(
  query: InfrastructureCostQuery
): Promise<InfrastructureCostResponse> {
  return apiGet(
    '/api/v1/admin/tracing/costs/infrastructure',
    query
  ) as Promise<InfrastructureCostResponse>
}

export async function getInfrastructureCostScopes(): Promise<InfrastructureCostScopeCatalog> {
  return apiGet(
    '/api/v1/admin/tracing/costs/infrastructure/scopes'
  ) as Promise<InfrastructureCostScopeCatalog>
}