Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Operator-attention feed (spec Fase 5, Pieza C — `GET /admin/attention`).
*
* The Fase 4 catalog-sync cron marks models `stale=true` when they vanish from
* the external catalog WITHOUT disabling them (`enabled` stays intact → they
* remain in the runtime allowlist ConfigMap and keep working). That
* non-destructive default is only safe if the operator is told to act. This
* module produces that persistent alert: the set of ACTIONABLE attention items.
*
* TODAY there is exactly one item kind — a `stale` AND `enabled` model that is
* STILL referenced by some Host/grant, so the operator must decide to disable it
* (through the Fase 3 impact-gated PUT). Two cases produce NO item: a `stale`
* model that nobody references (nothing to act on), and a `stale` model that is
* ALREADY disabled (its suggested action is already done — the enabled filter
* lives in `listStaleAllowedModels`, so those rows never reach this module). A
* disabled-but-still-referenced model is a distinct diagnostic concern (a future
* `dangling_reference` kind), not an actionable attention item.
*
* The `kind` discriminator is an OPEN string union on purpose: future phases add
* item kinds (e.g. a re-appeared model, a pricing gap) without breaking the
* frontend, which switches on `kind`.
*
* REFERENCE LOGIC IS NOT RECONSTRUCTED HERE (regla D4). The "who references
* (provider, model)" enumeration is `computeModelImpact` (Fase 3,
* `llmModelImpact.ts`) verbatim — the SAME module the `?force` write-gate uses.
* This module only enumerates the stale set and calls it once per stale model.
*
* FAIL-LOUD (coherent with the Fase 3 safety gate). `computeModelImpact` rejects
* if any Host LIST fails, and this module does NOT catch: a partial feed that
* silently drops a referenced-model warning is exactly the under-report the
* whole phase exists to prevent, so the endpoint answers 500 rather than a
* truncated list. One un-verifiable model tumbles the whole endpoint.
*
* COST. `computeModelImpact` is invoked once per stale model; each call is
* O(#hostNamespaces) K8s LISTs + one grant query. To keep the K8s cost flat as
* the stale set grows, the Host LISTs are MEMOIZED per namespace across the loop
* (`memoizeHostLists`): the apiserver is hit once per namespace for the whole
* request instead of once per (stale model × namespace). Grant queries stay
* per-model (O(#stale) Postgres reads) — a batched query would be a new SQL
* surface, and grants are the cheap side. The memoization preserves fail-loud:
* a rejected LIST promise is cached and re-thrown on the next await, so the loop
* still aborts on the first namespace that fails.
*/
import {
type GrantModelReference,
type HostModelReference,
type ModelImpactSources,
computeModelImpact,
modelImpactHasReferences,
} from './llmModelImpact.js'
/** The only attention kind today; the union is open for future kinds. */
export const ATTENTION_KIND_STALE_MODEL_REFERENCED = 'stale_model_referenced'
/**
* A `stale` AND `enabled` catalog model that is still referenced by a live
* Host/grant — the operator must disable it (impact-gated PUT) to converge. An
* already-disabled stale model is filtered out upstream (`listStaleAllowedModels`)
* and never produces this item. Carries the same `hostsAffected`/`grantsAffected`
* shape the Fase 3 impact body uses, so the frontend renders both surfaces
* identically.
*/
export interface StaleModelReferencedItem {
kind: typeof ATTENTION_KIND_STALE_MODEL_REFERENCED
provider: string
model: string
displayName?: string
hostsAffected: HostModelReference[]
grantsAffected: GrantModelReference[]
}
/** Extensible union — one member today, more kinds in later phases. */
export type AttentionItem = StaleModelReferencedItem
/** The `GET /admin/attention` response contract consumed by the UI banner. */
export interface AttentionReport {
items: AttentionItem[]
/** ISO-8601 instant the feed was computed (for a "as of" label in the UI). */
generatedAt: string
}
/** Minimal stale-model shape this module needs (subset of `LlmAllowedModel`). */
export interface StaleModelInput {
provider: string
model: string
display_name: string | null
}
/**
* Wrap `sources` so each namespace's Host LIST runs at most once per request.
* Caches the PROMISE (not the resolved array) so a rejection is memoized too and
* still propagates on every await — the fail-loud guarantee is preserved.
*/
function memoizeHostLists(sources: ModelImpactSources): ModelImpactSources {
const hostListByNamespace = new Map<string, Promise<unknown[]>>()
return {
hostNamespaces: sources.hostNamespaces,
listHostsInNamespace: namespace => {
let cached = hostListByNamespace.get(namespace)
if (!cached) {
cached = sources.listHostsInNamespace(namespace)
hostListByNamespace.set(namespace, cached)
}
return cached
},
listGrantsForModel: sources.listGrantsForModel,
}
}
/**
* Build the attention feed from the stale set. Enumerates each stale model's
* live references via `computeModelImpact` (regla D4 — no reconstruction) and
* emits an item ONLY when there is at least one reference (actionable). Lets any
* LIST rejection propagate (fail-loud → the route answers 500).
*/
export async function computeAttention(
staleModels: StaleModelInput[],
sources: ModelImpactSources
): Promise<AttentionReport> {
const memoizedSources = memoizeHostLists(sources)
const items: AttentionItem[] = []
for (const staleModel of staleModels) {
const impact = await computeModelImpact(staleModel.provider, staleModel.model, memoizedSources)
if (!modelImpactHasReferences(impact)) continue
const item: StaleModelReferencedItem = {
kind: ATTENTION_KIND_STALE_MODEL_REFERENCED,
provider: impact.provider,
model: impact.model,
hostsAffected: impact.hostsAffected,
grantsAffected: impact.grantsAffected,
}
// display_name is nullable in the catalog; only surface it when present so
// the UI can fall back to the raw model id without a null check.
if (staleModel.display_name) item.displayName = staleModel.display_name
items.push(item)
}
return { items, generatedAt: new Date().toISOString() }
}