Skip to content

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

TypeScript
9.7 KB
Raw Blame
import {
  CODEX_PROVIDER,
  CODEX_UNASSIGNED_CONNECTION_KEY,
  type CodexCatalogSnapshot,
  type CodexConfigMapView,
  type CodexExecutionProjection,
  GROK_PROVIDER,
  parseGrokAllowedModelsSnapshot,
  projectGrokExecution,
  snapshotForAssignedCodexGrant,
  toEligibleGrokPolicyBinding,
  toEligiblePolicyBinding,
} from '@clerum/codex-catalog-projection'
import type { WorkflowRecipeSpec } from '../types'
import {
  type CodexProvenance,
  projectRecipeCodexExecution,
  recipeToCodexHostSpec,
  resolveCodexAuthoritativeSpec,
} from './codexExecutionProjection'
import {
  type PluginWorkloadSdkCodexBindingProof,
  mintSdkOnlyCodexBindingProof,
} from './sdkOnlyCodexBinding'
import { mintSdkOnlyGrokBindingProof } from './sdkOnlyGrokBinding'

/*
 * ONE Codex verdict per reconcile pass.
 *
 * This seam has been fixed four times across four reviews, and every
 * fix converged one more dimension while leaving another live. The shape of
 * the bug never changed: two consumers answered the same question along
 * different paths, so `readOk` disagreed with `eligibility`, and then
 * `snapshotError` agreed while `provenance` did not.
 *
 * Converging one dimension at a time cannot end, because nothing forbids the
 * next dimension. So this module does not converge dimensions: it removes the
 * possibility of divergence. `projectCodexRecipeVerdict` computes the WHOLE
 * verdict once, from one captured set of inputs, and every consumer — control
 * scopes, scope uncertainty, the execution binding, the configure skip, the
 * Codex-proxy egress decision — reads a FIELD of the returned object.
 *
 * There is deliberately no derived boolean anyone can force, no second
 * projection, and no second read of the reconciler's live allowlist view
 * inside the same pass. The provenance-blind entry points are deleted rather
 * than deprecated, for the same reason `readOk` was deleted: a reachable
 * blind path is an invitation for the sibling to come back.
 */

export type CodexReconcileContext = {
  recipeUid: string
  recipeName: string
  runtimeScopeRecipeName: string
  claimedParent: boolean
  parentSpec: WorkflowRecipeSpec | null
  /**
   * Grant (connection key) the recipe is bound to via the
   * `clerum.io/codex-connection-ref` annotation on the authoritative recipe
   * (the runtime-scope parent when inherited). REQUIRED: an optional key with
   * a `?? unassigned` default at the call site is a silent fallback, and the
   * only producer (`bindCodexReconcileContext`) always fills it.
   */
  connectionKey: string
  /**
   * Canonical Grok grant key. Codex alias leftovers fail closed to
   * `unassigned` at the reader. Optional so existing Codex-only callers
   * keep compiling; missing is `unassigned` and cannot spend Grok.
   */
  grokConnectionKey?: string
}

/**
 * The allowlist refresh, captured once by the caller. Passing the view rather
 * than reading `this.codexView` inside is what keeps a concurrently-refreshed
 * snapshot from splitting one pass across two views (scope dimension).
 */
export type CodexAllowlistView = {
  configMap?: CodexConfigMapView
  snapshot: CodexCatalogSnapshot
}

export type CodexRecipeVerdict = {
  readonly provenance: CodexProvenance
  readonly provenanceReason: string
  readonly connectionKey: string
  /** Scope authority: eligibility, derivedScopes, egress, revisions. */
  readonly projection: CodexExecutionProjection
  /**
   * v3 execution binding for the agent this pod runs.
   *
   * Non-null ONLY when `projection.eligibility === 'eligible'` AND
   * `provenance === 'authoritative'`. A null under an eligible projection is a
   * DECISION (the host agent is not Codex, its model is not the eligible one,
   * or the revisions are out of range) — never uncertainty. That asymmetry is
   * the one the type cannot express, so it is asserted in the verdict tests.
   */
  readonly hostBinding: PluginWorkloadSdkCodexBindingProof | null
  readonly hostBindingReason: string
  readonly grokProjection: CodexExecutionProjection & { requiresGrokProxyEgress: boolean }
  readonly grokBinding: PluginWorkloadSdkCodexBindingProof | null
  readonly grokBindingReason: string
}

export function projectCodexRecipeVerdict(input: {
  ownSpec: WorkflowRecipeSpec
  context: CodexReconcileContext
  hostAgent: { provider: string; model: string } | undefined
  view: CodexAllowlistView
  /**
   * WRC_GROK_SUBSCRIPTION_ENABLED. REQUIRED so the local master switch is part
   * of the one Grok verdict: off is a DECISION (`ineligible`/`wrc_flag_off`),
   * so scopes, grok-proxy egress and the bootstrap binding cannot follow an
   * eligible Control API annotation while the pod env is withheld.
   */
  grokSubscriptionEnabled: boolean
  log?: {
    warn(msg: string, fields?: Record<string, unknown>): void
    debug(msg: string, fields?: Record<string, unknown>): void
  }
}): CodexRecipeVerdict {
  const { context, view } = input
  const resolved = resolveCodexAuthoritativeSpec({
    recipeName: context.recipeName,
    runtimeScopeRecipeName: context.runtimeScopeRecipeName,
    claimedParent: context.claimedParent,
    ownSpec: input.ownSpec,
    parentSpec: context.parentSpec,
  })
  const snapshot = snapshotForAssignedCodexGrant(
    context.connectionKey,
    view.configMap,
    view.snapshot
  )
  const projection = projectRecipeCodexExecution(resolved.spec, snapshot, resolved.provenance)
  const grokKey = context.grokConnectionKey ?? CODEX_UNASSIGNED_CONNECTION_KEY
  const grokSnapshot = parseGrokAllowedModelsSnapshot(view.configMap, grokKey)
  const grokRaw = projectGrokExecution(recipeToCodexHostSpec(resolved.spec), grokSnapshot)
  const grokProjection = !input.grokSubscriptionEnabled
    ? {
        ...grokRaw,
        eligibleTargets: [],
        derivedScopes: [],
        requiresGrokProxyEgress: false,
        eligibility: 'ineligible' as const,
        reason: 'wrc_flag_off',
        driftHashInput: JSON.stringify({
          eligibleTargets: [],
          derivedScopes: [],
          eligibility: 'ineligible',
        }),
      }
    : resolved.provenance === 'authoritative'
      ? grokRaw
      : {
          ...grokRaw,
          eligibleTargets: [],
          derivedScopes: [],
          requiresGrokProxyEgress: false,
          eligibility: 'uncertain' as const,
          reason: 'provenance_uncertain',
        }

  const hostBinding = mintCodexHostBinding({
    hostAgent: input.hostAgent,
    connectionKey: context.connectionKey,
    view,
    projection,
    log: input.log,
  })
  const grokBinding = mintGrokHostBinding({
    hostAgent: input.hostAgent,
    grokKey,
    view,
    grokProjection,
    log: input.log,
  })

  if (
    projection.eligibility === 'uncertain' &&
    resolved.provenance !== 'authoritative' &&
    input.hostAgent?.provider === CODEX_PROVIDER
  ) {
    input.log?.warn('Codex provenance is undecidable; withholding scope and binding', {
      recipeName: context.recipeName,
      connectionKey: context.connectionKey,
      provenanceReason: resolved.reason,
      reason: projection.reason,
    })
  }

  return {
    provenance: resolved.provenance,
    provenanceReason: resolved.reason,
    connectionKey: context.connectionKey,
    projection,
    grokProjection,
    hostBinding: hostBinding.binding,
    hostBindingReason: hostBinding.reason,
    grokBinding: grokBinding.binding,
    grokBindingReason: grokBinding.reason,
  }
}

function mintCodexHostBinding(input: {
  hostAgent: { provider: string; model: string } | undefined
  connectionKey: string
  view: CodexAllowlistView
  projection: CodexExecutionProjection
  log?: { debug(msg: string, fields?: Record<string, unknown>): void }
}): { binding: PluginWorkloadSdkCodexBindingProof | null; reason: string } {
  if (input.projection.eligibility !== 'eligible') {
    return { binding: null, reason: input.projection.reason }
  }
  if (!input.hostAgent || input.hostAgent.provider !== CODEX_PROVIDER) {
    return { binding: null, reason: 'host_agent_not_codex' }
  }
  const minted = toEligiblePolicyBinding(
    input.view.configMap,
    input.connectionKey,
    input.hostAgent.model
  )
  if (
    !minted.binding ||
    minted.binding.catalogRevision < 1 ||
    minted.binding.credentialRevision < 1
  ) {
    const withheld = minted.binding ? 'revision_out_of_range' : minted.reason
    input.log?.debug('Codex execution binding withheld', {
      model: input.hostAgent.model,
      connectionKey: input.connectionKey,
      reason: withheld,
    })
    return { binding: null, reason: withheld }
  }
  return { binding: mintSdkOnlyCodexBindingProof(minted.binding), reason: minted.reason }
}

function mintGrokHostBinding(input: {
  hostAgent: { provider: string; model: string } | undefined
  grokKey: string
  view: CodexAllowlistView
  grokProjection: CodexExecutionProjection
  log?: { debug(msg: string, fields?: Record<string, unknown>): void }
}): { binding: PluginWorkloadSdkCodexBindingProof | null; reason: string } {
  if (input.grokKey === CODEX_UNASSIGNED_CONNECTION_KEY) {
    return { binding: null, reason: 'unassigned' }
  }
  if (input.grokProjection.eligibility !== 'eligible') {
    return { binding: null, reason: input.grokProjection.reason }
  }
  if (!input.hostAgent || input.hostAgent.provider !== GROK_PROVIDER) {
    return { binding: null, reason: 'host_agent_not_grok' }
  }
  const minted = toEligibleGrokPolicyBinding(
    input.view.configMap,
    input.grokKey,
    input.hostAgent.model
  )
  if (
    !minted.binding ||
    minted.binding.catalogRevision < 1 ||
    minted.binding.credentialRevision < 1
  ) {
    const withheld = minted.binding ? 'revision_out_of_range' : minted.reason
    input.log?.debug('Grok execution binding withheld', {
      model: input.hostAgent.model,
      connectionKey: input.grokKey,
      reason: withheld,
    })
    return { binding: null, reason: withheld }
  }
  return { binding: mintSdkOnlyGrokBindingProof(minted.binding), reason: minted.reason }
}