Skip to content

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

TypeScript
21.6 KB
Raw Blame
/**
 * Service layer for `llm_allowed_models` — the operator-declared allowlist of
 * usable (provider, model) pairs (spec v2 §3-R3). This is the source of truth
 * that:
 *   - control-api enforces on write (Host spec validation, promptBridge grants),
 *   - is materialized to the `clerum-llm-allowed-models` ConfigMap in the
 *     `mcp-host` namespace for the runtime consumers (mcp-host, WRC).
 *
 * Semantics are fail-closed: a model is usable only if a row exists AND
 * `enabled = true`. A provider with no enabled rows is unusable.
 *
 * Every mutation appends a row to `llm_allowed_models_audit` (who/what/when),
 * mirroring the *_audit precedent in the repo. The (provider, model) unique
 * index surfaces as `LlmAllowedModelConflictError` so routes can answer 409.
 */
import { z } from 'zod'
import {
  type ImageInputCapability,
  normalizeImageInputCapability,
  parseImageInputCapability,
} from '@clerum/llm-providers'
import type { DbClient } from '../db.js'
import { pool } from '../db.js'

/** Catalog provenance (spec 09 §2.2). 'manual' = operator/seed; 'discovery' =
 *  auto-discovered (F2). The admin API only ever creates 'manual' rows. */
export type LlmAllowedModelSource = 'manual' | 'discovery'

export type LlmAllowedModel = {
  id: string
  provider: string
  model: string
  vendor: string | null
  display_name: string | null
  context_window_tokens: number | null
  enabled: boolean
  // Catalog lifecycle (F1, spec 09 §2.2). Additive, read-only through the admin
  // surface — discovery (F2) is the only writer of `discovery`/`*_at`/`stale`.
  source: LlmAllowedModelSource
  discovered_at: string | null
  last_seen_at: string | null
  stale: boolean
  /**
   * Model-level image-input capability + evidence (#654). ALWAYS normalized
   * through the shared contract: a NULL/malformed stored value reads as
   * `{ state: 'unknown' }`, never as affirmative support.
   */
  image_input: ImageInputCapability
  created_at: string
  updated_at: string
}

/** A single enabled model entry as materialized into the ConfigMap contract. */
export type AllowedModelEntry = {
  model: string
  displayName?: string
  contextWindowTokens?: number
  vendor?: string
  /**
   * Capability metadata for the runtime guard (#654). OMITTED when the row has
   * no stored metadata — consumers must treat absence as `{ state: 'unknown' }`
   * (the shared `normalizeImageInputCapability` does exactly that), which keeps
   * the ConfigMap byte-identical for allowlists that predate the field.
   */
  imageInput?: ImageInputCapability
}

/** Thrown when an insert/update collides with the (provider, model) unique index. */
export class LlmAllowedModelConflictError extends Error {
  constructor(message = 'a row for this provider/model already exists') {
    super(message)
    this.name = 'LlmAllowedModelConflictError'
  }
}

const PG_UNIQUE_VIOLATION = '23505'

function isUniqueViolation(error: unknown): boolean {
  return (
    typeof error === 'object' &&
    error !== null &&
    String((error as { code?: unknown }).code || '') === PG_UNIQUE_VIOLATION
  )
}

// Operator-declared context window. Guard the range so a typo cannot poison the
// context-window denominator (a 0 or negative would break compaction math; an
// absurd value would mask real limits). 20M covers every shipping model with
// margin (Gemini's 2M is today's largest).
export const MAX_CONTEXT_WINDOW_TOKENS = 20_000_000

const contextWindowField = z
  .number({ message: 'must be a number' })
  .int('must be an integer')
  .min(1, 'must be >= 1')
  .max(MAX_CONTEXT_WINDOW_TOKENS, `must be <= ${MAX_CONTEXT_WINDOW_TOKENS}`)

// Image-input capability (#654). Shape validity is owned by the SHARED contract
// (`parseImageInputCapability`), not by a second zod transcription: strict keys,
// the state enum, ISO-8601 UTC dates, and the rule that a supported/unsupported
// claim must carry evidence (plus `validUntil` when discovery-sourced) are all
// enforced there, so admin writes and runtime reads cannot drift apart.
//
// `.refine` narrows the unknown input to the parsed shape; a valid input is
// already key-complete and type-checked, so no transform is needed. The field is
// `.nullable()` on the UPDATE schema (null = explicit clear) and `.optional()`
// on both (absent = leave as-is / no evidence).
const IMAGE_INPUT_HINT =
  'image_input must be { state: "supported" | "unsupported" | "unknown", evidence?: ' +
  '{ source: "curated" | "discovery", reference: <public https URL or evidence:<id>>, ' +
  'checkedAt: <ISO-8601 UTC timestamp>, validUntil?: <later ISO-8601 UTC timestamp> } }. ' +
  'A supported/unsupported state requires evidence, and a discovery-sourced ' +
  'supported/unsupported state requires validUntil.'

const imageInputField = z
  .unknown()
  .refine((value): value is ImageInputCapability => parseImageInputCapability(value) !== null, {
    message: IMAGE_INPUT_HINT,
  })

// `provider` becomes a Kubernetes ConfigMap `data` key in the materializer, so
// it MUST be a valid K8s key AND must never be an Object.prototype key
// (`__proto__`/`constructor`/`prototype`) that could poison the grouping map or
// jam every subsequent ConfigMap write (fail-open at the runtime boundary). The
// regex requires a leading/trailing alphanumeric (rejects `__proto__`), and the
// refine rejects the remaining reserved words. `model` is NOT so constrained —
// it is only ever an array value (model ids can contain `.`, `/`, `-`).
const RESERVED_OBJECT_KEYS: ReadonlySet<string> = new Set(['__proto__', 'constructor', 'prototype'])
const providerField = z
  .string()
  .trim()
  .min(1, 'provider is required')
  .max(200)
  .regex(
    /^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$/,
    'provider must be alphanumeric with optional dot/dash/underscore separators'
  )
  .refine(v => !RESERVED_OBJECT_KEYS.has(v), { message: 'provider name is reserved' })

export const createLlmAllowedModelSchema = z.object({
  provider: providerField,
  model: z.string().trim().min(1, 'model is required').max(400),
  vendor: z.string().trim().min(1).max(200).optional(),
  display_name: z.string().trim().min(1).max(400).optional(),
  context_window_tokens: contextWindowField.optional(),
  image_input: imageInputField.optional(),
  enabled: z.boolean().default(true),
})

// Update: every field optional, but reject an empty body so PUT always changes
// something. `.strict()` keeps unknown keys out (no silent typos). vendor,
// display_name and context_window_tokens accept null to explicitly clear them.
export const updateLlmAllowedModelSchema = z
  .object({
    provider: providerField,
    model: z.string().trim().min(1).max(400),
    vendor: z.string().trim().min(1).max(200).nullable(),
    display_name: z.string().trim().min(1).max(400).nullable(),
    context_window_tokens: contextWindowField.nullable(),
    image_input: imageInputField.nullable(),
    enabled: z.boolean(),
  })
  .partial()
  .strict()
  .refine(obj => Object.keys(obj).length > 0, { message: 'no fields to update' })

export type CreateLlmAllowedModelInput = z.infer<typeof createLlmAllowedModelSchema>
export type UpdateLlmAllowedModelInput = z.infer<typeof updateLlmAllowedModelSchema>

export type LlmAllowedModelAuditAction = 'create' | 'update' | 'disable' | 'delete'

/**
 * Canonical storage form for the capability column. `unknown` WITHOUT evidence
 * is "no evidence", which the column already represents as NULL: the admin API
 * always reads a row back normalized (a legacy row reads as `{ state: 'unknown' }`),
 * so an unchanged round-trip must not turn into a stored value and change the
 * materialized ConfigMap. Anything validated by `imageInputField` is stored
 * verbatim as canonical JSON text for the `jsonb` column.
 */
function imageInputToColumn(value: ImageInputCapability | null | undefined): string | null {
  if (value === null || value === undefined) return null
  if (value.state === 'unknown' && value.evidence === undefined) return null
  return JSON.stringify(value)
}

function toIso(raw: unknown): string {
  if (raw instanceof Date) return raw.toISOString()
  if (typeof raw === 'string') {
    const d = new Date(raw)
    return Number.isNaN(d.getTime()) ? raw : d.toISOString()
  }
  return String(raw)
}

function toNullableNumber(raw: unknown): number | null {
  if (raw === null || raw === undefined) return null
  if (typeof raw === 'number') return raw
  if (typeof raw === 'string') {
    const n = Number(raw)
    return Number.isFinite(n) ? n : null
  }
  if (typeof raw === 'bigint') return Number(raw)
  return null
}

function toNullableString(raw: unknown): string | null {
  if (raw === null || raw === undefined) return null
  return String(raw)
}

function toNullableIso(raw: unknown): string | null {
  if (raw === null || raw === undefined) return null
  return toIso(raw)
}

function rowToModel(row: Record<string, unknown>): LlmAllowedModel {
  return {
    id: String(row.id),
    provider: String(row.provider),
    model: String(row.model),
    vendor: toNullableString(row.vendor),
    display_name: toNullableString(row.display_name),
    context_window_tokens: toNullableNumber(row.context_window_tokens),
    enabled: Boolean(row.enabled),
    // Defensive default: any non-'discovery' value (incl. NULL/legacy) reads as
    // 'manual', matching the column DEFAULT and the CHECK constraint.
    source: row.source === 'discovery' ? 'discovery' : 'manual',
    discovered_at: toNullableIso(row.discovered_at),
    last_seen_at: toNullableIso(row.last_seen_at),
    stale: Boolean(row.stale),
    // NULL / malformed / legacy → `{ state: 'unknown' }` (never affirmative).
    image_input: normalizeImageInputCapability(row.image_input),
    created_at: toIso(row.created_at),
    updated_at: toIso(row.updated_at),
  }
}

const MODEL_COLUMNS = `
  id, provider, model, vendor, display_name,
  context_window_tokens, enabled, source, discovered_at, last_seen_at, stale,
  image_input, created_at, updated_at
`

async function writeAudit(
  db: DbClient,
  entry: {
    actor: string
    action: LlmAllowedModelAuditAction
    provider: string
    model: string
    detail?: unknown
  }
): Promise<void> {
  await db.query(
    `INSERT INTO llm_allowed_models_audit (actor, action, provider, model, detail)
     VALUES ($1, $2, $3, $4, $5)`,
    [
      entry.actor,
      entry.action,
      entry.provider,
      entry.model,
      entry.detail === undefined ? null : JSON.stringify(entry.detail),
    ]
  )
}

/** All rows (enabled + disabled) so UI pickers can flag disabled entries. */
export async function listAllowedModels(db: DbClient = pool): Promise<LlmAllowedModel[]> {
  const result = await db.query(
    `SELECT ${MODEL_COLUMNS}
       FROM llm_allowed_models
      ORDER BY provider ASC, model ASC`
  )
  return (result.rows as Record<string, unknown>[]).map(rowToModel)
}

/**
 * Stale AND enabled rows — models the Fase 4 sync flagged as vanished from the
 * external catalog (`stale=true`) while leaving `enabled` intact, so they still
 * ship in the runtime allowlist ConfigMap and keep working. The operator-
 * attention feed (Fase 5) is the sole consumer: it enumerates these and reports
 * the ones still referenced as `stale_model_referenced` — an ACTIONABLE item
 * whose remedy is the impact-gated PUT that disables the model.
 *
 * The `AND enabled` filter is load-bearing for that contract. A `stale` model
 * that is ALREADY disabled but still referenced (a dangling reference left after
 * a force-disable) is NOT actionable through this feed — its suggested action
 * ("disable it") is already done — so surfacing it would make the feed never
 * converge to zero after the very action it asked for. That "disabled + still
 * referenced" state is a distinct, diagnostic-only concern (a future
 * `dangling_reference` kind, designed separately); it is not lost here — it stays
 * derivable via `computeModelImpact`. Deterministic ordering keeps the feed
 * stable across calls.
 */
export async function listStaleAllowedModels(db: DbClient = pool): Promise<LlmAllowedModel[]> {
  const result = await db.query(
    `SELECT ${MODEL_COLUMNS}
       FROM llm_allowed_models
      WHERE stale AND enabled
      ORDER BY provider ASC, model ASC`
  )
  return (result.rows as Record<string, unknown>[]).map(rowToModel)
}

export async function getAllowedModel(
  id: string,
  db: DbClient = pool
): Promise<LlmAllowedModel | null> {
  const result = await db.query(
    `SELECT ${MODEL_COLUMNS} FROM llm_allowed_models WHERE id = $1 LIMIT 1`,
    [id]
  )
  const row = result.rows[0] as Record<string, unknown> | undefined
  return row ? rowToModel(row) : null
}

export async function createAllowedModel(
  input: CreateLlmAllowedModelInput,
  actor: string,
  db: DbClient = pool
): Promise<LlmAllowedModel> {
  try {
    const result = await db.query(
      `INSERT INTO llm_allowed_models
         (provider, model, vendor, display_name, context_window_tokens, image_input, enabled)
       VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7)
       RETURNING ${MODEL_COLUMNS}`,
      [
        input.provider,
        input.model,
        input.vendor ?? null,
        input.display_name ?? null,
        input.context_window_tokens ?? null,
        imageInputToColumn(input.image_input),
        input.enabled,
      ]
    )
    const created = rowToModel(result.rows[0] as Record<string, unknown>)
    await writeAudit(db, {
      actor,
      action: 'create',
      provider: created.provider,
      model: created.model,
      detail: input,
    })
    return created
  } catch (error) {
    if (isUniqueViolation(error)) throw new LlmAllowedModelConflictError()
    throw error
  }
}

export async function updateAllowedModel(
  id: string,
  input: UpdateLlmAllowedModelInput,
  actor: string,
  db: DbClient = pool
): Promise<LlmAllowedModel | null> {
  // Read the existing row first: we need its (provider, model) for the audit
  // row and its `enabled` to classify a disable vs a plain update.
  const existing = await getAllowedModel(id, db)
  if (!existing) return null

  // Build the SET list dynamically from whichever fields were provided. Keys
  // come from the zod-validated, `.strict()` schema — never raw request input —
  // so this is a fixed allowlist of column names, not caller-controlled SQL.
  const columnByField: Record<keyof UpdateLlmAllowedModelInput, string> = {
    provider: 'provider',
    model: 'model',
    vendor: 'vendor',
    display_name: 'display_name',
    context_window_tokens: 'context_window_tokens',
    image_input: 'image_input',
    enabled: 'enabled',
  }
  // Evidence belongs to the (provider, model) pair it was checked against, so a
  // RENAME invalidates it — unless the same request carries fresh evidence for
  // the new pair. Without this, a curated `supported` for model A would silently
  // authorize images for model B after an operator renamed the row.
  const renamed =
    (input.provider !== undefined && input.provider !== existing.provider) ||
    (input.model !== undefined && input.model !== existing.model)
  const sets: string[] = []
  const params: unknown[] = []
  let idx = 1
  for (const [field, column] of Object.entries(columnByField) as [
    keyof UpdateLlmAllowedModelInput,
    string,
  ][]) {
    const value = input[field]
    if (value === undefined) continue
    // `image_input` is `jsonb`; cast explicitly like the repo's other jsonb
    // writes (`llmCatalogSync`, `pluginWorkloadSdkDb`) rather than relying on
    // parameter-type inference.
    sets.push(field === 'image_input' ? `${column} = $${idx++}::jsonb` : `${column} = $${idx++}`)
    params.push(field === 'image_input' ? imageInputToColumn(input.image_input) : value)
  }
  if (renamed && input.image_input === undefined) sets.push('image_input = NULL')
  if (sets.length === 0) return existing

  sets.push(`updated_at = NOW()`)
  params.push(id)

  let updated: LlmAllowedModel | null
  try {
    const result = await db.query(
      `UPDATE llm_allowed_models
          SET ${sets.join(', ')}
        WHERE id = $${idx}
      RETURNING ${MODEL_COLUMNS}`,
      params
    )
    const row = result.rows[0] as Record<string, unknown> | undefined
    updated = row ? rowToModel(row) : null
  } catch (error) {
    if (isUniqueViolation(error)) throw new LlmAllowedModelConflictError()
    throw error
  }
  if (!updated) return null

  const action: LlmAllowedModelAuditAction =
    input.enabled === false && existing.enabled ? 'disable' : 'update'
  await writeAudit(db, {
    actor,
    action,
    provider: updated.provider,
    model: updated.model,
    detail: input,
  })
  return updated
}

export async function deleteAllowedModel(
  id: string,
  actor: string,
  db: DbClient = pool
): Promise<boolean> {
  // Read the (provider, model) first so the audit row records what was removed;
  // a missing row is a no-op (route 404s).
  const existing = await getAllowedModel(id, db)
  if (!existing) return false
  const result = await db.query(`DELETE FROM llm_allowed_models WHERE id = $1`, [id])
  const deleted = (result.rowCount ?? 0) > 0
  if (deleted) {
    await writeAudit(db, {
      actor,
      action: 'delete',
      provider: existing.provider,
      model: existing.model,
      detail: { id },
    })
  }
  return deleted
}

/**
 * True when (provider, model) exists AND is enabled — the fail-closed gate used
 * by Host spec validation and the promptBridge grant cross-check.
 */
export async function isModelAllowed(
  provider: string,
  model: string,
  db: DbClient = pool
): Promise<boolean> {
  const result = await db.query(
    `SELECT 1 FROM llm_allowed_models
      WHERE provider = $1 AND model = $2 AND enabled
      LIMIT 1`,
    [provider, model]
  )
  return result.rows.length > 0
}

/** Enabled model names for one provider (for the grant allowedModels check). */
export async function listEnabledModelNamesForProvider(
  provider: string,
  db: DbClient = pool
): Promise<string[]> {
  const result = await db.query(
    `SELECT model FROM llm_allowed_models
      WHERE provider = $1 AND enabled
      ORDER BY model ASC`,
    [provider]
  )
  return (result.rows as Record<string, unknown>[]).map(row => String(row.model))
}

/**
 * Full allowlist state for one `(provider, model)`: `{ enabled, stale }`, or
 * `null` when no row exists. Fase 6 (soft quarantine of `stale` models) reads
 * this on the operator write path so the gate can WARN — never block — when an
 * `enabled` but `stale` model (vanished from the external catalog, Fase 4) is
 * assigned to something NEW. `isModelAllowed` stays the boolean fail-closed gate
 * (unchanged callers, unchanged semantics); this is strictly additive.
 */
export async function getModelAllowlistState(
  provider: string,
  model: string,
  db: DbClient = pool
): Promise<{ enabled: boolean; stale: boolean } | null> {
  const result = await db.query(
    `SELECT enabled, stale FROM llm_allowed_models
      WHERE provider = $1 AND model = $2
      LIMIT 1`,
    [provider, model]
  )
  const row = result.rows[0] as Record<string, unknown> | undefined
  if (!row) return null
  return { enabled: Boolean(row.enabled), stale: Boolean(row.stale) }
}

/**
 * Enabled model names for one provider WITH their `stale` flag (Fase 6 grant
 * gate). Same `enabled`-only filter as `listEnabledModelNamesForProvider`; adds
 * `stale` so the grant write gate can warn on a NEW assignment of an enabled-but-
 * stale model without a second round-trip. A `stale` model is still `enabled`, so
 * it still appears here — quarantine is a warning, not a de-listing (R3.7).
 */
export async function listEnabledModelsWithStaleForProvider(
  provider: string,
  db: DbClient = pool
): Promise<Array<{ model: string; stale: boolean }>> {
  const result = await db.query(
    `SELECT model, stale FROM llm_allowed_models
      WHERE provider = $1 AND enabled
      ORDER BY model ASC`,
    [provider]
  )
  return (result.rows as Record<string, unknown>[]).map(row => ({
    model: String(row.model),
    stale: Boolean(row.stale),
  }))
}

/**
 * Enabled rows grouped by provider, shaped for the ConfigMap materializer.
 * Only providers with at least one enabled row appear. Deterministic ordering
 * (provider then model) keeps the materialized content hash stable.
 */
export async function listEnabledGroupedByProvider(
  db: DbClient = pool
): Promise<Record<string, AllowedModelEntry[]>> {
  const result = await db.query(
    `SELECT provider, model, vendor, display_name, context_window_tokens, image_input
       FROM llm_allowed_models
      WHERE enabled
        AND NOT (provider = 'codex-subscription' AND stale)
      ORDER BY provider ASC, model ASC`
  )
  // Null-prototype map so a stray/legacy `provider` value equal to an
  // Object.prototype key (`__proto__`/`constructor`/`prototype`) can never
  // resolve to an inherited member and break the `??=` grouping. New rows are
  // already rejected at write time (providerField), but seed/legacy data reads
  // through here too.
  const grouped: Record<string, AllowedModelEntry[]> = Object.create(null)
  for (const raw of result.rows as Record<string, unknown>[]) {
    const provider = String(raw.provider)
    const entry: AllowedModelEntry = { model: String(raw.model) }
    const displayName = toNullableString(raw.display_name)
    if (displayName) entry.displayName = displayName
    const contextWindow = toNullableNumber(raw.context_window_tokens)
    if (contextWindow !== null) entry.contextWindowTokens = contextWindow
    const vendor = toNullableString(raw.vendor)
    if (vendor) entry.vendor = vendor
    // Projected only when the row actually carries metadata: absence stays
    // absence so an allowlist without capabilities materializes byte-identically
    // to the pre-#654 ConfigMap (consumers normalize absence to `unknown`).
    if (raw.image_input !== null && raw.image_input !== undefined) {
      entry.imageInput = normalizeImageInputCapability(raw.image_input)
    }
    ;(grouped[provider] ??= []).push(entry)
  }
  return grouped
}