Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Shared types for the Skill Mapper.
*/
import type { LlmProviderId } from '@clerum/llm-providers'
/**
* McpServer transport configuration.
*/
export interface McpServerTransport {
type: 'sse' | 'streamableHttp' | 'stdio'
url?: string
port?: number
}
/**
* Reference to a key within a Kubernetes Secret.
*/
export interface McpServerSecretRef {
name: string
key: string
}
/**
* OAuth broker configuration for an mcp-server (auth.type === 'oauth').
*
* Present iff `spec.auth.type === 'oauth'`. control-api owns the OAuth flow and
* resolves tokens per connection just-in-time; HCC does NOT mount the token as
* env (invariant O4 stays intact — this type only lets the controller type the
* discriminator; the runtime token carril is mcp-host's, not HCC's).
*/
export interface McpServerOAuth {
id: string
// Baked-carril only. Full control-api adapter set — must mirror the
// mcpserver.yaml `oauth.provider` enum, control-api `providers.ts`
// `OAuthProvider`, and workflow-recipes `OAuthProvider`. U2 (spec 06) added
// monday/clickup/vercel. The sourced carriles (`spec.oauth.source: 'remote'`
// — spec 02 — and `'generic'` — spec 01 S3) carry NO provider and instead
// pin their own endpoints/knobs; those fields are deliberately NOT modelled
// here because HCC reads only `grantScope` (deriveAuthKind) and `bearerInBody`
// from the oauth block (the CR is spread verbatim into the inventory in
// k8sClient, so unmodelled sourced fields pass through untyped and unread —
// the token carril is mcp-host's/control-api's, never HCC's). A generic/remote
// CR therefore flows through HCC with `provider` absent at runtime; no HCC
// read dereferences it. Do not "fix" this by adding 'generic'/'remote' to the
// provider union — they are carriles, not providers (Option A, spec 01 DEC-28).
provider:
| 'salesforce'
| 'slack'
| 'notion'
| 'microsoft-graph'
| 'google'
| 'monday'
| 'clickup'
| 'vercel'
clientIdRef: McpServerSecretRef
clientSecretRef: McpServerSecretRef
scopes?: string[]
backgroundAccess?: boolean
grantScope?: 'user' | 'context'
// Remote transport quirk (mini-spec 19 §D-8, CRD IMM-6): true iff the resource
// advertises `bearer_methods_supported:["body"]`, so mcp-host must present the
// access token in the request body, not the Authorization header. Non-secret;
// HCC only projects it to the inventory (as AuthorizedMcpServerInfo.bearerInBody).
bearerInBody?: boolean
}
/**
* McpServer authentication configuration.
*/
export interface McpServerAuth {
type: 'none' | 'bearer' | 'basic' | 'apiKey' | 'oauth'
secretRef?: string
secretKey?: string
}
/**
* A single environment variable (name/value pair).
*/
export interface McpServerEnvVar {
name: string
value: string
}
/**
* Mapping from a secret key to an environment variable name.
*/
export interface McpServerSecretKeyMapping {
secretKey: string
envVar: string
}
/**
* Secret-backed environment variables configuration.
*/
export interface McpServerEnvSecret {
name: string
keys: McpServerSecretKeyMapping[]
}
/**
* McpServer operational configuration.
*/
export interface McpServerConfig {
readOnly?: boolean
loggers?: string
telemetry?: 'enabled' | 'disabled'
}
/**
* Maps CRD fields to env var names specific to each MCP server image.
* The reconciler reads structured CRD fields and sets the named env vars.
*/
export interface McpServerEnvMapping {
transport?: string
httpHost?: string
httpPort?: string
healthCheckHost?: string
healthCheckPort?: string
readOnly?: string
loggers?: string
telemetry?: string
}
/**
* McpServer health check configuration.
*/
export interface McpServerHealthCheck {
port?: number
}
/**
* McpServer resource requests/limits.
*/
export interface McpServerResources {
requests?: { memory?: string; cpu?: string }
limits?: { memory?: string; cpu?: string }
}
/**
* External egress binding — allows an MCP server to reach an external API.
*/
export interface EgressBinding {
egressClass?: 'exact-host' | 'public-web'
dns?: string
cidr?: string
port?: number
protocol?: 'TCP' | 'UDP'
}
/**
* McpServer CRD spec.
*/
export interface McpServerSecurityContext {
runAsUser?: number
runAsGroup?: number
fsGroup?: number
addCapabilities?: string[]
}
export interface McpServerSpec {
// Ownership contract:
// - managed:true or omitted => HCC owns the runtime.
// - managed:false => WRC owns the runtime; HCC only exposes discovery/status.
contextRef: string
description?: string
image: string
imagePullPolicy?: 'Always' | 'IfNotPresent' | 'Never'
// Codex P2 fix (PR #101): K8s LocalObjectReference shape, not raw strings.
// Producers (mcpDelegation, registry install) normalize to objects at the CRD
// write boundary so HCC consumes this directly without double-wrapping.
imagePullSecrets?: Array<{ name: string }>
command?: string[]
args?: string[]
transport: McpServerTransport
auth?: McpServerAuth
// OAuth broker config; present iff auth.type === 'oauth'. Typing only — HCC
// does NOT mount the resolved token as env (O4 stays intact).
oauth?: McpServerOAuth
serverConfig?: McpServerConfig
envMapping?: McpServerEnvMapping
env?: McpServerEnvVar[]
envSecret?: McpServerEnvSecret
healthCheck?: McpServerHealthCheck
resources?: McpServerResources
security?: McpServerSecurityContext
enabled?: boolean
managed?: boolean
egressBindings?: EgressBinding[]
/** Remote MCP server config. When present, HCC creates an nginx egress proxy instead of deploying the vendor image. */
// Codex P1 fix (PR #101): authHeaders enables forwarding credential secrets
// as upstream Authorization/API-key headers on proxied requests. Values use
// ${ENV_VAR} placeholders interpolated at pod startup by nginx's official
// /etc/nginx/templates/ envsubst pattern (env vars sourced from envSecret).
remote?: {
baseUrl: string
authHeaders?: Array<{ header: string; valueTemplate: string }>
}
}
/**
* McpServer CRD (full internal representation used by the reconciler).
*/
export interface McpServerCRD {
name: string
namespace: string
uid?: string
generation?: number
annotations?: Record<string, string>
labels?: Record<string, string>
spec: McpServerSpec
status?: McpServerCrdStatus
}
export interface McpServerCondition {
type: string
status: 'True' | 'False' | 'Unknown'
reason?: string
message?: string
lastTransitionTime?: string
observedGeneration?: number
}
export interface McpServerResolvedEgressIP {
dns: string
ips: string[]
resolvedAt: string
}
export interface McpServerCrdStatus {
resolvedEgressIPs?: McpServerResolvedEgressIP[]
conditions?: McpServerCondition[]
}
// ─── SharedFileSystem CRD ──────────────────────────────────────────────────
/**
* POSIX identity applied to the SharedFileSystem PVC by the controller's root
* init container and inherited by the per-SFS workspace-files-controller pod.
*/
export interface SharedFileSystemSecurity {
runAsUser?: number
runAsGroup?: number
fsGroup?: number
}
/**
* SharedFileSystem CRD spec. Always lives in the mcp-host namespace.
*/
export interface SharedFileSystemSpec {
size?: string
storageClassName?: string
accessModes?: string[]
annotations?: Record<string, string>
directories?: string[]
security?: SharedFileSystemSecurity
/** Default true. When false, HCC deletes the PVC when the SharedFileSystem is removed. */
retainOnDelete?: boolean
}
export type SharedFileSystemPhase =
'Provisioning' | 'Initializing' | 'Ready' | 'Degraded' | 'Failed'
export interface SharedFileSystemCondition {
type: string
status: 'True' | 'False' | 'Unknown'
reason?: string
message?: string
lastTransitionTime?: string
}
export interface SharedFileSystemStatus {
phase?: SharedFileSystemPhase
pvcName?: string
capacity?: string
storageClassName?: string
serviceName?: string
mountedByContexts?: { namespace: string; name: string }[]
conditions?: SharedFileSystemCondition[]
}
export interface SharedFileSystemCRD {
name: string
namespace: string
spec: SharedFileSystemSpec
status?: SharedFileSystemStatus
}
// ─── GlobalFileSystem CRD ────────────────────────────────────────────────────
//
// The single cluster-wide governed drive (gfs). DISTINCT from SharedFileSystem:
// gfs is one broker-mediated drive (gfsc writer + reader replicas + permission
// store) in the `gfs` namespace, NOT a per-team RO workspace. Mirrors the SFS
// CRD shape only; the semantics come from the gfs spec.
export interface GlobalFileSystemStorage {
/** PVC requested storage, e.g. "500Gi". */
size?: string
/** v1: standard-rwo (RWO). RWX is a deferred escalation. */
storageClassName?: string
/** Defaults to ["ReadWriteOnce"] in v1. */
accessModes?: string[]
}
export interface GlobalFileSystemLayout {
/**
* Absolute seed paths (e.g. "/org", "/system/published-workflow-artifacts").
* Materialized as gfs_resources rows by control-api (the governance plane owns
* the permission store — CC6), NOT by the reconciler/init container.
*/
rootDirectories?: string[]
}
export interface GlobalFileSystemSecurity {
runAsUser?: number
fsGroup?: number
}
export interface GlobalFileSystemSpec {
storage?: GlobalFileSystemStorage
layout?: GlobalFileSystemLayout
security?: GlobalFileSystemSecurity
/** Read-only reader replicas. Default 2. The writer is always exactly 1. */
readerReplicas?: number
/** Default true. When false, HCC deletes the PVC when the gfs is removed. */
retainOnDelete?: boolean
}
export type GlobalFileSystemPhase =
'Provisioning' | 'Initializing' | 'Ready' | 'Degraded' | 'Failed'
export interface GlobalFileSystemCondition {
type: string
status: 'True' | 'False' | 'Unknown'
reason?: string
message?: string
lastTransitionTime?: string
}
export interface GlobalFileSystemStatus {
phase?: GlobalFileSystemPhase
pvcName?: string
serviceName?: string
/** In-cluster base URL of the gfsc Service, e.g. http://gfsc.gfs.svc.cluster.local:8087. */
serviceUrl?: string
conditions?: GlobalFileSystemCondition[]
}
export interface GlobalFileSystemCRD {
name: string
namespace: string
spec: GlobalFileSystemSpec
status?: GlobalFileSystemStatus
}
// ─── Context CRD ────────────────────────────────────────────────────────────
/**
* Reference from a Context to a SharedFileSystem. SharedFileSystems always
* live in the mcp-host namespace in v1; the namespace field is reserved for
* forward compat.
*/
export interface ContextSharedFileSystemRef {
name: string
mountPath: string
}
export type ContextSharedFileSystemPhase = 'Resolving' | 'Mounted' | 'MissingTarget' | 'Failed'
export interface ContextSharedFileSystemStatus {
name: string
mountPath: string
phase: ContextSharedFileSystemPhase
pvcName?: string
message?: string
}
/**
* Context CRD spec — defines which MCP servers a host can access and which
* SharedFileSystems should be mounted RO into mcp-host pods that use it.
*/
export interface ContextSpec {
contextId: string
description?: string
/** List of McpServer names accessible within this context. */
mcpServers: string[]
/** Optional SharedFileSystem references (multi-mount). */
sharedFileSystems?: ContextSharedFileSystemRef[]
}
export interface ContextStatus {
sharedFileSystems?: ContextSharedFileSystemStatus[]
}
/**
* Context CRD.
*/
export interface ContextCRD {
name: string
namespace: string
uid?: string
generation?: number
spec: ContextSpec
status?: ContextStatus
}
// ─── Host CRD ───────────────────────────────────────────────────────────────
export interface HostModelSpec {
provider?: LlmProviderId
name?: string
connectionRef?: string
}
export interface HostAllowedModel {
provider?: string
model?: string
}
export interface HostLlmPolicyFallback {
provider?: string
model?: string
credentialSlot?: string
}
export interface HostLlmPolicySpec {
fallbacks?: HostLlmPolicyFallback[]
}
export interface HostDesktopSpec {
browser?: boolean
x11?: boolean
}
export interface HostLifecycleSpec {
/**
* Enable the stateless agent lifecycle: mcp-host persists session state to
* SQLite on the workspace PVC and HCC may scale the Deployment to 0 while
* status.lifecycle.state is `suspended`. Default false.
*/
stateless?: boolean
}
export type HostWorkflowControlScope =
| 'workflow:list'
| 'workflow:read'
| 'workflow:trigger'
| 'workflow:approval:resolve'
| 'workflow:approval:decide'
export type DerivedPlatformScope = 'llm:codex:execute' | 'llm:grok:execute'
// The full effective runtime control scope set minted into an mcp-host control
// JWT: the user-declarable workflow-control scopes PLUS every HCC-derived scope
// — `oauth:user-token` (see {@link HostRuntimeControlScope}) and the codex
// `llm:codex:execute` derive. Both derives can co-occur on one Host, so this
// must be their union, not either alone.
export type EffectiveMcpHostControlScope = HostRuntimeControlScope | DerivedPlatformScope
export interface HostWorkflowControlSpec {
scopes?: HostWorkflowControlScope[]
}
/**
* Runtime control scopes minted into an mcp-host's control JWT. This is the
* DERIVED superset of the user-declarable {@link HostWorkflowControlScope}:
* HCC appends `oauth:user-token` for a Host runtime that fronts an enabled
* `auth.type: oauth` mcp-server, so the mcp-host can call control-api's OAuth
* user-token broker on that connection's behalf.
*
* `oauth:user-token` is HCC-derived and MUST NEVER be user-declarable: it is
* deliberately absent from {@link HostWorkflowControlScope} and from the Host
* CRD `spec.workflowControl.scopes` enum. HCC computes it per reconcile from
* the referenced Context's McpServer allow-list; nothing writes it back to the
* Host CR.
*/
export type HostRuntimeControlScope = HostWorkflowControlScope | 'oauth:user-token'
/**
* A single installed-hook reference inside Host.spec.guardrails.hooks[phase].
* `id` is the LlmHook CR name (llm-hooks namespace); `digest` is the expected
* image digest mcp-host binds against status.observedDigest (§8.2).
*/
export interface HostGuardrailHookRef {
id: string
digest?: string
}
/**
* Host.spec.guardrails.hooks — installed LlmHook references grouped by
* lifecycle phase. Only the hook `id`s matter to HCC: they form the
* Host→LlmHook reverse index that drives the shared hook pod's NetworkPolicy
* ingress set (guardrails phase-4 design §5).
*/
export interface HostGuardrailHooks {
preToolUse?: HostGuardrailHookRef[]
postToolUse?: HostGuardrailHookRef[]
preCall?: HostGuardrailHookRef[]
moderate?: HostGuardrailHookRef[]
postCallSuccess?: HostGuardrailHookRef[]
onError?: HostGuardrailHookRef[]
}
/**
* Host.spec.guardrails — additive, opt-in guardrail policy (guardrails spec
* §5). HCC only reads `hooks` (for the reverse index); the loosely-typed
* `rules`/`builtins`/ceiling fields are owned by mcp-host/control-api.
*/
export interface HostGuardrailsSpec {
hooks?: HostGuardrailHooks
rules?: unknown[]
builtins?: unknown[]
minInstalledHookTrustLevel?: 'low' | 'mid' | 'high'
approvalPolicies?: string[]
capabilityCeiling?: string[]
}
export interface HostSpec {
host: string
contextRef: string
secretRef?: string
channels?: string[]
model?: HostModelSpec
allowedModels?: HostAllowedModel[]
llmPolicy?: HostLlmPolicySpec
approval?: Record<string, unknown>
desktop?: HostDesktopSpec
lifecycle?: HostLifecycleSpec
workflowControl?: HostWorkflowControlSpec
guardrails?: HostGuardrailsSpec
}
export type HostLifecycleState = 'active' | 'draining' | 'suspended'
export interface HostCondition {
type: string
status: 'True' | 'False' | 'Unknown'
reason?: string
message?: string
lastTransitionTime?: string
}
/**
* Durable lifecycle state persisted in the Host status subresource. HCC
* derives Deployment replicas from `state` on every reconcile, so a suspended
* Host survives HCC restarts and periodic resyncs (the state lives in the
* CRD, not in HCC memory).
*/
export interface HostLifecycleStatus {
state: HostLifecycleState
/**
* Highest observed Host generation whose wake trigger has been handled.
* Written by HCC itself when it handles a wake (statelessLifecycleExecutor:
* the wake fast-path and the pre-scale-down wake guard); other lifecycle
* writes preserve it.
*/
wakeHandledGeneration: number
/** Human-readable rejection or temporary suspension-block reason. */
reason?: string
}
export interface HostCrdStatus {
lifecycle?: HostLifecycleStatus
conditions?: HostCondition[]
}
export interface HostCRD {
name: string
namespace: string
generation?: number
/**
* metadata.uid — the Kubernetes-assigned stable identity of THIS Host object.
* A same-name Host deleted and recreated gets a fresh uid, so uid (not name or
* generation) is what distinguishes a genuine deletion from a same-name
* recreation on every destructive path (#827). Undefined for snapshots that
* predate uid capture; identity fences treat "unknown" conservatively.
*/
uid?: string
/**
* metadata.resourceVersion of the CR at the time it was read. Preserved by
* readFreshHost so the heartbeat-path status writers can pass it back as an
* optimistic-concurrency precondition: a stale write is rejected 409 and
* retried against a fresh read. Undefined for watch-cache snapshots that
* never carried it -- those writers read fresh before writing.
*/
resourceVersion?: string
/**
* Host CR metadata annotations. Carries the control-api-projected
* `clerum.io/wake-requested` monotonic wake generation consumed by the
* HCC wake fast-path (Stage 4.3).
*/
annotations?: Record<string, string>
spec: HostSpec
status?: HostCrdStatus
}
// ─── CommunicationChannel CRD ──────────────────────────────────────────────
//
// HCC only inspects `spec.hostRef` to count CCs per Host (see #281). The full
// CC schema (telegram[], email[], slack[] adapter configs) is owned by the
// per-Host channel-reader pod's own CC watch and never enters HCC's model.
export interface CommunicationChannelSpec {
hostRef: string
credentialsSecretRef?: { name: string }
}
export interface CommunicationChannelCRD {
name: string
namespace: string
spec: CommunicationChannelSpec
}
export interface HostChannelReaderStatus {
/** True when the host has ≥1 CommunicationChannel. */
expected: boolean
/** True when the channel-reader Deployment exists and has ≥1 ready replica. */
ready: boolean
/** Human-readable status message for the channel-reader component. */
message?: string
}
export interface HostRuntimeStatus {
deployed: boolean
ready: boolean
message?: string
/** Readiness status of the per-Host channel-reader Deployment. Populated best-effort; absent until the first reconcile that reaches the channel-reader step. */
channelReader?: HostChannelReaderStatus
}
// ─── API Response Types ─────────────────────────────────────────────────────
// These types represent what the skill-mapper returns to consumers (mcp-host).
// They intentionally strip deployment internals (image, envMapping, envSecret,
// resources, healthCheck, serverConfig) and add operator-known status info.
/**
* Deployment status of an MCP server, known only by the skill-mapper operator.
*/
export interface McpServerStatus {
/** Whether the Deployment resource exists in the cluster. */
deployed: boolean
/** Whether the Deployment has at least one ready replica. */
ready: boolean
/**
* Whether this readiness observation is current and authoritative — HCC can
* tie the status to the current McpServer identity and generation. Omitted
* when the status source cannot make that guarantee; false means discovery
* is authoritative but runtime status has not yet been re-established after
* controller startup.
*/
authoritative?: boolean
/** Human-readable status message. */
message?: string
}
/**
* Curated MCP server info for API consumers (mcp-host).
* Contains only what a client needs to connect to the server,
* plus deployment status that only the operator knows.
*/
export interface McpServerInfo {
name: string
description?: string
contextRef: string
transport: McpServerTransport
auth?: McpServerAuth
// OAuth broker config; present iff auth.type === 'oauth'. Discovery metadata
// only — mcp-host dispatches the per-connection partition from `authKind`
// (derived separately), not from this field, which currently has no consumer.
// HCC does NOT mount the resolved token as env (O4 stays intact).
oauth?: McpServerOAuth
enabled: boolean
status: McpServerStatus
}
/**
* API response for listing McpServers.
*/
export interface McpServersResponse {
servers: McpServerInfo[]
contextRef: string
timestamp: string
}
/**
* API error response.
*/
export interface ErrorResponse {
error: string
message: string
}
// ─── LlmHook CRD ─────────────────────────────────────────────────────────────
//
// An installed guardrail hook mcp-host calls over the /v1 protocol (guardrails
// spec §8). host-context-controller reconciles `image`-target hooks into a
// shared Deployment+Service+NetworkPolicy in the llm-hooks namespace
// (digest-dedup: hooks sharing a pod key co-locate on one pod, routed by
// spec.path). `service` and `remote` targets deploy no workload (status-only).
/** External egress a hook pod is permitted (looser CRD shape than McpServer). */
export interface LlmHookEgressBinding {
toFQDN?: string
cidr?: string
ports?: number[]
}
/** Security context overrides for a hook pod. */
export interface LlmHookSecurity {
addCapabilities?: string[]
}
/** In-cluster image hook target — the only target HCC deploys a workload for. */
export interface LlmHookImageTarget {
ref: string
port: number
imagePullSecrets?: string[]
envSecret?: string
egressBindings?: LlmHookEgressBinding[]
security?: LlmHookSecurity
}
/** Existing in-cluster Service target — status-only, nothing deployed. */
export interface LlmHookServiceTarget {
name: string
namespace: string
port: number
}
/** External HTTPS endpoint target — status-only, nothing deployed. */
export interface LlmHookRemoteTarget {
baseUrl: string
authHeadersSecret?: string
}
export interface LlmHookTarget {
image?: LlmHookImageTarget
service?: LlmHookServiceTarget
remote?: LlmHookRemoteTarget
}
export type LlmHookLifecyclePoint = 'preCall' | 'moderate' | 'postCallSuccess' | 'onError'
export type LlmHookCapability =
'may_deny' | 'may_rewrite' | 'may_substitute_result' | 'may_add_context'
export interface LlmHookSpec {
target: LlmHookTarget
path?: string
lifecyclePoints: LlmHookLifecyclePoint[]
order?: number
failMode?: 'open' | 'closed'
timeoutMs?: number
onUnavailable?: {
mode?: 'strict' | 'breaker'
failureThreshold?: number
cooldownMs?: number
}
capabilities?: LlmHookCapability[]
config?: Record<string, unknown>
}
export interface LlmHookCondition {
type: string
status: 'True' | 'False' | 'Unknown'
reason?: string
message?: string
lastTransitionTime?: string
observedGeneration?: number
}
export interface LlmHookStatus {
observedDigest?: string
readyReplicas?: number
lastReconciled?: string
conditions?: LlmHookCondition[]
}
export interface LlmHookCRD {
name: string
namespace: string
uid?: string
generation?: number
annotations?: Record<string, string>
labels?: Record<string, string>
spec: LlmHookSpec
status?: LlmHookStatus
}