Skip to content

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

TypeScript
17.9 KB
Raw Blame
import { createHash } from 'node:crypto'
import type { DbClient } from '../../db.js'
import type { AgentRunEventSubmitterPrincipalV1 } from '../../middleware/tracingSubmitterAuth.js'
import {
  type WorkflowRunBinding,
  WorkflowRunBindingRepository,
} from '../workflowRunBindingRepository.js'
import type { AgentRunServerBindingV1, WorkflowAgentRunEventInputV1 } from './contracts.js'
import { canonicalTracingEnvironment } from './environment.js'
import type { AgentRunBindingResolver } from './routeSubmissionService.js'

const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
const TERMINAL_PHASES = new Set(['Succeeded', 'Failed', 'Canceled'])
const ACTOR_TYPES = new Set(['user', 'admin', 'autonomous', 'scheduled'])
const TASK_EVENT_SOURCE =
  /^task:([^:]{1,128}):(start|end|llm:[^:]+|tool:[^:]+|approval:[^:]+:[^:]+)$/

function nonEmptyString(value: unknown): string | null {
  return typeof value === 'string' && value.length > 0 && !value.includes('\u0000') ? value : null
}

function nullableString(value: unknown): string | null {
  return value === null || value === undefined ? null : nonEmptyString(value)
}

function timestamp(value: unknown): Date | null {
  if (value === null || value === undefined) return null
  const parsed = value instanceof Date ? value : new Date(String(value))
  return Number.isFinite(parsed.getTime()) ? parsed : null
}

function durationMs(value: unknown): number | null {
  if (value === null || value === undefined) return null
  const parsed = Number(value)
  return Number.isSafeInteger(parsed) && parsed >= 0 && parsed <= 86_400_000 ? parsed : null
}

function spanId(runId: string, kind: 'root' | 'end'): string {
  return createHash('sha256').update(`workflow-run:${runId}:${kind}`).digest('hex')
}

function terminalOutcome(phase: string): AgentRunServerBindingV1['outcome'] | null {
  if (phase === 'Succeeded') return 'succeeded'
  if (phase === 'Failed') return 'failed'
  if (phase === 'Canceled') return 'cancelled'
  return null
}

export class WorkflowRunBindingResolver implements AgentRunBindingResolver {
  private readonly workflowRunBindings: WorkflowRunBindingRepository

  constructor(
    db: Pick<DbClient, 'query'>,
    private readonly environment = canonicalTracingEnvironment()
  ) {
    this.workflowRunBindings = new WorkflowRunBindingRepository(db)
  }

  async resolve(
    principal: AgentRunEventSubmitterPrincipalV1,
    event: WorkflowAgentRunEventInputV1
  ): Promise<AgentRunServerBindingV1 | null> {
    return (await this.resolveMany(principal, [event]))[0] ?? null
  }

  async resolveMany(
    principal: AgentRunEventSubmitterPrincipalV1,
    events: readonly WorkflowAgentRunEventInputV1[]
  ): Promise<readonly (AgentRunServerBindingV1 | null)[]> {
    if (principal.kind !== 'wrc_internal_control') return events.map(() => null)

    const runIds = events
      .map(event => event.runId)
      .filter(runId => UUID_PATTERN.test(runId))
      .map(runId => runId.toLowerCase())
    const bindings = await this.workflowRunBindings.resolveMany(runIds)

    return events.map(event => {
      if (!UUID_PATTERN.test(event.runId)) return null
      const runId = event.runId.toLowerCase()
      const binding = bindings.get(runId)
      return binding ? this.bindingFromRow(binding, runId, event.eventType) : null
    })
  }

  private bindingFromRow(
    row: WorkflowRunBinding,
    runId: string,
    eventType: WorkflowAgentRunEventInputV1['eventType']
  ): AgentRunServerBindingV1 | null {
    if (nullableString(row.runId)?.toLowerCase() !== runId) return null

    const recipeNamespace = nonEmptyString(row.recipeNamespace)
    const recipeName = nonEmptyString(row.recipeName)
    const phase = nonEmptyString(row.phase)
    const actorType = nonEmptyString(row.actorType)
    const startedAt = timestamp(row.startedAt)
    const completedAt = timestamp(row.completedAt)
    if (!recipeNamespace || !recipeName || !phase || !actorType || !ACTOR_TYPES.has(actorType)) {
      return null
    }

    const resolvedActorId = nullableString(row.actorId)
    if ((actorType === 'user' || actorType === 'admin') && !resolvedActorId) return null

    const rootSpanId = spanId(runId, 'root')
    let outcome: AgentRunServerBindingV1['outcome']
    let resolvedDurationMs: number | null = null
    if (eventType === 'run_start') {
      if (!startedAt || phase === 'Pending') return null
      outcome = 'started'
    } else if (eventType === 'run_end') {
      outcome = terminalOutcome(phase) ?? 'unknown'
      if (!TERMINAL_PHASES.has(phase) || !completedAt || outcome === 'unknown') return null
      resolvedDurationMs = durationMs(row.durationMs)
    } else {
      return null
    }

    return {
      runId,
      sessionId: null,
      spanId: eventType === 'run_start' ? rootSpanId : spanId(runId, 'end'),
      parentSpanId: eventType === 'run_start' ? null : rootSpanId,
      origin: 'workflow_runtime',
      identityIssuer: null,
      actorHumanSub: resolvedActorId,
      agentSub: `workflow-recipe:${recipeNamespace}/${recipeName}`,
      actorMedium: 'workflow',
      resourceAud: null,
      effectiveScopes: [],
      decision: 'not_applicable',
      decisionSourceKind: null,
      decisionSourceRef: null,
      approvalRequestId: nullableString(row.approvalRequestId),
      tokenExchangeId: null,
      environment: this.environment,
      tenantId: null,
      teamId: nullableString(row.usageTeamId) ?? nullableString(row.teamId),
      userId: resolvedActorId,
      recipeNamespace,
      recipeName,
      hostRef: null,
      outcome,
      durationMs: resolvedDurationMs,
    }
  }
}

export interface AuthoritativeHostReader {
  getResource(plural: 'hosts', name: string, namespace: string): Promise<unknown>
}

function hostIdentity(
  principal: Extract<AgentRunEventSubmitterPrincipalV1, { kind: 'mcp_host_runtime' }>,
  hostRef: string
): { name: string; namespace: string } | null {
  const segments = hostRef.split('/')
  if (segments.length === 1) {
    return nonEmptyString(segments[0])
      ? { name: segments[0]!, namespace: principal.recipeNamespace }
      : null
  }
  if (segments.length !== 2 || !nonEmptyString(segments[0]) || !nonEmptyString(segments[1])) {
    return null
  }
  return { namespace: segments[0]!, name: segments[1]! }
}

function directOutcome(event: WorkflowAgentRunEventInputV1): AgentRunServerBindingV1['outcome'] {
  if (event.eventType === 'run_start') return 'started'
  if (event.eventType === 'approval') {
    if (event.payload?.status === 'approved') return 'approved'
    if (event.payload?.status === 'denied') return 'denied'
  }
  if (event.payload?.status === 'cancelled') return 'cancelled'
  if (event.payload?.status === 'failed' || event.payload?.error_class) return 'failed'
  return 'succeeded'
}

function directApprovalStatus(
  event: WorkflowAgentRunEventInputV1
): 'requested' | 'approved' | 'denied' | null {
  if (event.eventType !== 'approval') return null
  if (!event.approvalRequestId || !UUID_PATTERN.test(event.approvalRequestId)) return null
  const source = /:approval:([^:]+):(requested|approved|denied)$/.exec(event.sourceEventId)
  if (source?.[1]?.toLowerCase() !== event.approvalRequestId.toLowerCase()) return null
  const sourceStatus = source[2]
  const payloadStatus = event.payload?.status
  return sourceStatus && payloadStatus === sourceStatus
    ? (sourceStatus as 'requested' | 'approved' | 'denied')
    : null
}

export class HostReferencedRunBindingResolver implements AgentRunBindingResolver {
  constructor(
    private readonly hostReader: AuthoritativeHostReader,
    private readonly db: Pick<DbClient, 'query'>,
    private readonly environment = canonicalTracingEnvironment()
  ) {}

  async resolve(
    principal: AgentRunEventSubmitterPrincipalV1,
    event: WorkflowAgentRunEventInputV1
  ): Promise<AgentRunServerBindingV1 | null> {
    return (await this.resolveMany(principal, [event]))[0] ?? null
  }

  async resolveMany(
    principal: AgentRunEventSubmitterPrincipalV1,
    events: readonly WorkflowAgentRunEventInputV1[]
  ): Promise<readonly (AgentRunServerBindingV1 | null)[]> {
    if (principal.kind !== 'mcp_host_runtime') return events.map(() => null)
    const structurallyValid = events.map(
      event =>
        UUID_PATTERN.test(event.runId) &&
        Boolean(event.origin) &&
        Boolean(event.hostRef) &&
        principal.hostRefs.includes(event.hostRef!) &&
        hostIdentity(principal, event.hostRef!) !== null &&
        TASK_EVENT_SOURCE.test(event.sourceEventId)
    )
    if (!structurallyValid.some(Boolean)) return events.map(() => null)
    const runIds = [
      ...new Set(
        events
          .filter((_, index) => structurallyValid[index])
          .map(event => event.runId.toLowerCase())
      ),
    ]
    const directBindingRows = await this.db.query(
      `SELECT run_id::text, host_ref, session_id, origin, identity_issuer,
              actor_human_sub, user_id::text, team_id::text
         FROM governed_run_attribution_bindings
        WHERE run_id = ANY($1::uuid[])`,
      [runIds]
    )
    const directBindings = new Map<
      string,
      {
        hostRef: string
        sessionId: string
        origin: string
        identityIssuer: string
        actorHumanSub: string
        userId: string | null
        teamId: string | null
      }
    >()
    for (const row of directBindingRows.rows as Array<Record<string, unknown>>) {
      directBindings.set(String(row.run_id).toLowerCase(), {
        hostRef: String(row.host_ref),
        sessionId: String(row.session_id),
        origin: String(row.origin),
        identityIssuer: String(row.identity_issuer),
        actorHumanSub: String(row.actor_human_sub),
        userId: row.user_id === null ? null : String(row.user_id),
        teamId: row.team_id === null ? null : String(row.team_id),
      })
    }
    const referencedHosts = [
      ...new Set(
        events.filter((_, index) => structurallyValid[index]).map(event => event.hostRef!)
      ),
    ]
    const hosts = new Map<string, unknown>()
    await Promise.all(
      referencedHosts.map(async hostRef => {
        const identity = hostIdentity(principal, hostRef)
        if (!identity) return
        try {
          hosts.set(
            hostRef,
            await this.hostReader.getResource('hosts', identity.name, identity.namespace)
          )
        } catch {
          // An absent or unreadable Host cannot establish tracing authority.
        }
      })
    )
    const parsed = events.map(event => {
      const match = TASK_EVENT_SOURCE.exec(event.sourceEventId)
      return { event, taskId: match?.[1] ?? null, occurrence: match?.[2] ?? null }
    })
    const rootSourceIds = [
      ...new Set(parsed.filter(item => item.taskId).map(item => `task:${item.taskId}:start`)),
    ]
    const existing =
      rootSourceIds.length === 0
        ? { rows: [] }
        : await this.db.query(
            `SELECT source_event_id, run_id::text, host_ref, origin, session_id
             FROM agent_run_events
            WHERE source_service = 'mcp-host'
              AND source_kind = 'mcp_host_runtime'
              AND event_type = 'run_start'
              AND source_event_id = ANY($1::text[])`,
            [rootSourceIds]
          )
    const roots = new Map<
      string,
      { runId: string; hostRef: string | null; origin: string; sessionId: string | null }
    >()
    for (const row of existing.rows as Array<Record<string, unknown>>) {
      roots.set(String(row.source_event_id), {
        runId: String(row.run_id).toLowerCase(),
        hostRef: row.host_ref === null ? null : String(row.host_ref),
        origin: String(row.origin),
        sessionId: row.session_id === null ? null : String(row.session_id),
      })
    }
    for (const item of parsed) {
      if (!item.taskId || item.occurrence !== 'start') continue
      const rootSourceId = `task:${item.taskId}:start`
      const candidate = {
        runId: item.event.runId.toLowerCase(),
        hostRef: item.event.hostRef ?? null,
        origin: item.event.origin ?? '',
        sessionId: item.event.sessionId?.trim() || null,
      }
      const current = roots.get(rootSourceId)
      if (!current) roots.set(rootSourceId, candidate)
    }
    return parsed.map((item, index) => {
      if (!structurallyValid[index]) return null
      if (!item.taskId || !item.occurrence) return null
      const root = roots.get(`task:${item.taskId}:start`)
      if (
        !root ||
        root.runId !== item.event.runId.toLowerCase() ||
        root.hostRef !== (item.event.hostRef ?? null) ||
        root.origin !== item.event.origin ||
        root.sessionId !== (item.event.sessionId?.trim() || null)
      )
        return null
      const host = item.event.hostRef ? hosts.get(item.event.hostRef) : undefined
      const directBinding = directBindings.get(item.event.runId.toLowerCase()) ?? null
      if (
        directBinding &&
        (directBinding.hostRef !== item.event.hostRef ||
          directBinding.sessionId !== (item.event.sessionId?.trim() || null) ||
          directBinding.origin !== item.event.origin)
      ) {
        return null
      }
      return host ? this.resolveWithHost(principal, item.event, host, directBinding) : null
    })
  }

  private resolveWithHost(
    principal: Extract<AgentRunEventSubmitterPrincipalV1, { kind: 'mcp_host_runtime' }>,
    event: WorkflowAgentRunEventInputV1,
    host: unknown,
    directBinding: {
      identityIssuer: string
      actorHumanSub: string
      userId: string | null
      teamId: string | null
    } | null
  ): AgentRunServerBindingV1 | null {
    if (!UUID_PATTERN.test(event.runId) || !event.origin || !event.hostRef) return null
    const hostRef = event.hostRef
    if (!principal.hostRefs.includes(hostRef)) return null
    if (event.eventType === 'approval' && directApprovalStatus(event) === null) return null
    if (
      event.eventType === 'tool_call' &&
      event.approvalRequestId &&
      !UUID_PATTERN.test(event.approvalRequestId)
    ) {
      return null
    }
    const identity = hostIdentity(principal, hostRef)
    if (!identity) return null
    const resource = host as {
      apiVersion?: string
      kind?: string
      metadata?: { name?: string; namespace?: string }
    }
    if (
      resource.apiVersion !== 'clerum.io/v1alpha1' ||
      resource.kind !== 'Host' ||
      resource.metadata?.name !== identity.name ||
      resource.metadata.namespace !== identity.namespace
    )
      return null
    const runId = event.runId.toLowerCase()
    const root = createHash('sha256').update(`host-run:${runId}:root`).digest('hex')
    const resolvedOutcome = directOutcome(event)
    const decision =
      event.eventType === 'approval'
        ? resolvedOutcome === 'approved'
          ? 'allow'
          : resolvedOutcome === 'denied'
            ? 'deny'
            : 'require_approval'
        : 'not_applicable'
    return {
      runId,
      sessionId: event.sessionId?.trim() || null,
      spanId:
        event.eventType === 'run_start'
          ? root
          : createHash('sha256').update(`host-run:${runId}:${event.sourceEventId}`).digest('hex'),
      parentSpanId: event.eventType === 'run_start' ? null : root,
      origin: event.origin,
      identityIssuer: directBinding?.identityIssuer ?? null,
      actorHumanSub: directBinding?.actorHumanSub ?? null,
      agentSub: `mcp-host:${hostRef}`,
      actorMedium:
        event.origin === 'channel_event'
          ? 'channel'
          : event.origin === 'direct_chat'
            ? 'desktop'
            : 'api',
      resourceAud: null,
      effectiveScopes: [],
      decision,
      // mcp-host emits this only after its authenticated legacy approval gate
      // validates the bound user/channel and applies the local state transition.
      // Native control-plane approvals use approval_resolution instead.
      decisionSourceKind: event.eventType === 'approval' ? 'legacy_gate' : null,
      decisionSourceRef: event.eventType === 'approval' ? event.sourceEventId : null,
      decisionActorSub:
        event.eventType === 'approval' &&
        (resolvedOutcome === 'approved' || resolvedOutcome === 'denied')
          ? (directBinding?.actorHumanSub ?? null)
          : null,
      approvalRequestId:
        (event.eventType === 'approval' || event.eventType === 'tool_call') &&
        event.approvalRequestId
          ? event.approvalRequestId.toLowerCase()
          : null,
      tokenExchangeId: null,
      environment: this.environment,
      tenantId: null,
      teamId: directBinding?.teamId ?? null,
      userId: directBinding?.userId ?? null,
      recipeNamespace: principal.recipeNamespace,
      recipeName: principal.recipeName,
      hostRef,
      outcome: resolvedOutcome,
      durationMs: null,
    }
  }
}

export class AgentRunBindingResolverChain implements AgentRunBindingResolver {
  constructor(private readonly resolvers: readonly AgentRunBindingResolver[]) {}

  async resolve(principal: AgentRunEventSubmitterPrincipalV1, event: WorkflowAgentRunEventInputV1) {
    return (await this.resolveMany(principal, [event]))[0] ?? null
  }

  async resolveMany(
    principal: AgentRunEventSubmitterPrincipalV1,
    events: readonly WorkflowAgentRunEventInputV1[]
  ): Promise<readonly (AgentRunServerBindingV1 | null | undefined)[]> {
    const unresolved = new Set(events.map((_, index) => index))
    const results: Array<AgentRunServerBindingV1 | null> = events.map(() => null)
    for (const resolver of this.resolvers) {
      if (unresolved.size === 0) break
      const pendingIndexes = [...unresolved]
      const pendingEvents = pendingIndexes.map(index => events[index]!)
      const resolved = resolver.resolveMany
        ? await resolver.resolveMany(principal, pendingEvents)
        : await Promise.all(pendingEvents.map(event => resolver.resolve(principal, event)))
      if (resolved.length !== pendingEvents.length)
        throw new Error('binding resolver batch mismatch')
      resolved.forEach((binding, offset) => {
        if (!binding) return
        const index = pendingIndexes[offset]!
        results[index] = binding
        unresolved.delete(index)
      })
    }
    return results
  }
}