Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { isRunnableLlmModelId } from '@clerum/llm-providers'
import type {
PluginWorkloadSdkCapabilityStatus,
RecipePhase,
StatusCondition,
WorkflowRecipeSpec,
} from '../types'
import { hasResolvableAgent } from '../workflow/agentResolution'
/**
* Validation + status projection for `spec.pluginWorkloadSdk`.
*
* Mirrors the webhookValidator pattern: pure functions with no Kubernetes
* client dependencies. The reconciler's `validateSpec` throws on any
* returned error (fail-closed), and `patchStatus` projects the validated
* capability into `status.pluginWorkloadSdk` + a `PluginWorkloadSdkCapability`
* condition so control-api can read it at runtime.
*/
export const DEFAULT_IDEMPOTENCY_KEY_PATTERN = '^[a-zA-Z0-9_-]{1,128}$'
/** Condition type owned by the Plugin Workload SDK reconcile pass. */
export const PLUGIN_WORKLOAD_SDK_CONDITION_TYPE = 'PluginWorkloadSdkCapability'
export const PLUGIN_WORKLOAD_SDK_PROVIDER_UNAVAILABLE_CONDITION_TYPE =
'PluginWorkloadSdkProviderUnavailable'
export const PLUGIN_WORKLOAD_SDK_POLICY_PENDING_CONDITION_TYPE = 'PluginWorkloadSdkPolicyPending'
/**
* WorkflowRecipe remains the CRD that carries Plugin Workload SDK, but an SDK
* workload is not a workflow. Keep the small set of workflow-only fields
* closed when the recipe has no executable steps. CEL is the first line of
* defence; this pure check preserves the same boundary for direct and
* mixed-version inputs that bypass admission.
*/
export const SDK_ONLY_WORKFLOW_FIELDS = ['triggers', 'scheduling', 'coordinatorImage'] as const
function rejectWildcards(field: string, values: string[] | undefined, errors: string[]): void {
for (const value of values ?? []) {
if (value.includes('*')) {
errors.push(`${field} entry "${value}" must not contain wildcards`)
}
}
}
function rejectInvalidModels(field: string, values: string[] | undefined, errors: string[]): void {
for (const value of values ?? []) {
if (!value.includes('*') && !isRunnableLlmModelId(value)) {
errors.push(`${field} entry "${value}" has an invalid runnable model id`)
}
}
}
/**
* Validate `spec.pluginWorkloadSdk` against the rules the CRD's OpenAPI/CEL
* layer cannot fully express:
*
* - at least one capability family must be declared
* - clientNotifications.allowedEventTypes must be non-empty
* - no wildcard `*` in allowedEventTypes, allowedModels, or allowedCallers
* - allowedCallers must reference existing workloads[].id entries
* - idempotencyKeyPattern must compile as a regex
*
* Returns a list of human-readable errors; empty when valid or when the
* capability is not declared.
*/
export function validatePluginWorkloadSdkSpec(spec: WorkflowRecipeSpec): string[] {
const sdk = spec.pluginWorkloadSdk
if (!sdk) return []
const errors: string[] = []
const hasWorkflowSteps = (spec.steps?.length ?? 0) > 0
if (!hasWorkflowSteps) {
if (!Array.isArray(spec.workloads) || spec.workloads.length === 0) {
errors.push('pluginWorkloadSdk SDK-only recipes require at least one spec.workloads entry')
}
const configuredWorkflowFields = SDK_ONLY_WORKFLOW_FIELDS.filter(field => {
switch (field) {
case 'triggers':
return spec.triggers !== undefined
case 'scheduling':
return spec.scheduling !== undefined
case 'coordinatorImage':
return spec.coordinatorImage !== undefined
}
})
if (configuredWorkflowFields.length > 0) {
errors.push(
'pluginWorkloadSdk without workflow steps cannot define triggers, scheduling, or coordinatorImage'
)
}
}
if (!sdk.promptBridge && !sdk.clientNotifications) {
errors.push(
'pluginWorkloadSdk must declare at least one capability family (promptBridge or clientNotifications)'
)
}
if (sdk.clientNotifications) {
const eventTypes = sdk.clientNotifications.allowedEventTypes
if (!Array.isArray(eventTypes) || eventTypes.length === 0) {
errors.push(
'pluginWorkloadSdk.clientNotifications.allowedEventTypes must contain at least one event type'
)
} else {
rejectWildcards('pluginWorkloadSdk.clientNotifications.allowedEventTypes', eventTypes, errors)
}
rejectWildcards(
'pluginWorkloadSdk.clientNotifications.allowedTargetRefs',
sdk.clientNotifications.allowedTargetRefs,
errors
)
}
rejectWildcards(
'pluginWorkloadSdk.promptBridge.allowedModels',
sdk.promptBridge?.allowedModels,
errors
)
rejectInvalidModels(
'pluginWorkloadSdk.promptBridge.allowedModels',
sdk.promptBridge?.allowedModels,
errors
)
if (spec.agent !== undefined) {
if (!spec.agent.provider) {
errors.push('spec.agent.provider is required when spec.agent is declared')
}
if (!isRunnableLlmModelId(spec.agent.model)) {
errors.push('spec.agent.model must be a valid runnable model id when spec.agent is declared')
}
}
// promptBridge issues real LLM calls, so the recipe must declare a resolvable
// agent (provider + model). A stepless SDK recipe uses spec.agent as the
// eager mcp-host bootstrap binding; a workflow may instead resolve a step
// agent. clientNotifications needs no provider, so this rule is scoped to
// promptBridge only.
if (sdk.promptBridge && !hasResolvableAgent(spec)) {
errors.push(
'pluginWorkloadSdk.promptBridge requires spec.agent or a step agent with provider + model'
)
}
rejectWildcards('pluginWorkloadSdk.allowedCallers', sdk.allowedCallers, errors)
const workloadIds = new Set((spec.workloads ?? []).map(w => w.id))
for (const caller of sdk.allowedCallers ?? []) {
if (!workloadIds.has(caller)) {
errors.push(
`pluginWorkloadSdk.allowedCallers entry "${caller}" does not reference any spec.workloads[].id`
)
}
}
if (sdk.idempotencyKeyPattern !== undefined) {
try {
new RegExp(sdk.idempotencyKeyPattern)
} catch {
errors.push(
`pluginWorkloadSdk.idempotencyKeyPattern "${sdk.idempotencyKeyPattern}" is not a valid regular expression`
)
}
}
return errors
}
export interface PluginWorkloadSdkStatusProjection {
/**
* Fresh owned conditions for the merge pass. `[]` clears stale owned
* conditions (capability removed from spec); `undefined` is never
* returned — the projection always decides.
*/
conditions: StatusCondition[]
/**
* Value for `status.pluginWorkloadSdk`. `null` clears the field via
* merge-patch; `undefined` leaves whatever is currently persisted.
*/
capability: PluginWorkloadSdkCapabilityStatus | null | undefined
}
export interface PluginWorkloadSdkBootstrapProofInput {
ready: true
contractVersion: 2 | 3
podUid: string
codexBinding?: {
connectionKey: string
catalogRevision: number
credentialRevision: number
model: string
bindingHash: string
}
subscriptionBinding?: {
connectionKey: string
catalogRevision: number
credentialRevision: number
model: string
bindingHash: string
}
provider?: string
model?: string
policyReady?: boolean
policyState?: string
policyReason?: string
policyRevision?: number
policyHash?: string
defaultTargetRef?: string
defaultProvider?: string
defaultModel?: string
clientNotificationsPolicyReady?: boolean
clientNotificationsPolicyState?: string
clientNotificationsPolicyReason?: string
verifiedAt: string
}
/**
* parseEagerSdkBootstrapProof always sets policyState (default `unknown`).
* A stale v2 Codex image or a missing binding must not render as `(active)`.
*/
function promptBridgePolicyPendingReason(
bootstrapProof: PluginWorkloadSdkBootstrapProofInput | undefined,
codexBindingPending: boolean
): string {
if (codexBindingPending) {
if (bootstrapProof?.contractVersion !== 3) {
return bootstrapProof?.provider === 'grok-subscription'
? 'execution_binding_missing'
: 'codex_bootstrap_contract_stale'
}
return (
bootstrapProof.policyReason ??
(bootstrapProof.provider === 'grok-subscription'
? 'execution_binding_missing'
: 'codex_execution_binding_missing')
)
}
return bootstrapProof?.policyReason ?? bootstrapProof?.policyState ?? 'unknown'
}
/**
* JSON merge-patch preserves omitted object members. Keep the status
* projection's derived metadata explicit so a validated record cannot leave
* stale bootstrap/policy identity behind after a degraded transition.
*/
const CLEARED_PLUGIN_WORKLOAD_SDK_METADATA = {
validatedAt: null,
bootstrapContractVersion: null,
bootstrapPodUid: null,
bootstrapProvider: null,
bootstrapModel: null,
policyRevision: null,
policyHash: null,
defaultTargetRef: null,
verifiedAt: null,
} as const
/**
* Project `spec.pluginWorkloadSdk` + feature flag + reconcile outcome into
* the status condition and capability record.
*
* - capability not declared → clear condition + clear status field
* - feature flag off → condition False/FeatureFlagDisabled, state 'disabled'
* (the CRD field is still accepted — runtime enforcement is what's gated)
* - reconcile failed → carry forward existing owned conditions untouched and
* leave the persisted capability as-is (a transient infra failure must not
* flip an already-validated capability)
* - eager host identity is ready but the operator prompt policy is absent or
* unusable → condition False/PolicyNotConfigured, state 'awaiting_policy'
* - reconcile succeeded with an active prompt policy → condition True/Validated,
* state 'validated'
*/
export function buildPluginWorkloadSdkStatus(args: {
spec: WorkflowRecipeSpec
existingConditions: StatusCondition[] | undefined
phase: RecipePhase
featureFlagEnabled: boolean
providerUnavailable?: boolean
policyPending?: boolean
teardownConfirmed?: boolean
bootstrapProof?: PluginWorkloadSdkBootstrapProofInput
now: string
/**
* The currently-persisted capability (recipe.status.pluginWorkloadSdk), used
* to CARRY FORWARD the stable `validatedAt` marker across steady-state
* throttle patches (issue #375 R1) instead of resetting it to `now`.
*/
existingCapability?: PluginWorkloadSdkCapabilityStatus | null
}): PluginWorkloadSdkStatusProjection {
const {
spec,
existingConditions,
phase,
featureFlagEnabled,
providerUnavailable,
policyPending,
teardownConfirmed,
bootstrapProof,
now,
existingCapability,
} = args
const sdk = spec.pluginWorkloadSdk
if (!sdk) {
return { conditions: [], capability: null }
}
const promptBridge = sdk.promptBridge !== undefined
const clientNotifications = sdk.clientNotifications !== undefined
// A failed reconcile must never be projected as a successful disable. In
// particular, the SDK kill-switch performs cleanup before this projection;
// if cleanup failed, reporting `disabled` could leave an old host reachable
// while claiming revocation completed.
if (phase === 'failed' && !(teardownConfirmed === true && !featureFlagEnabled)) {
const carried = (existingConditions ?? []).filter(
c => c.type === PLUGIN_WORKLOAD_SDK_CONDITION_TYPE
)
return { conditions: carried, capability: undefined }
}
if (!featureFlagEnabled) {
const message = 'Disabled (feature flag off)'
return {
conditions: [
{
type: PLUGIN_WORKLOAD_SDK_CONDITION_TYPE,
status: 'False',
reason: 'FeatureFlagDisabled',
message,
lastTransitionTime: now,
},
],
capability: {
state: 'disabled',
promptBridge,
clientNotifications,
message,
...CLEARED_PLUGIN_WORKLOAD_SDK_METADATA,
},
}
}
if (providerUnavailable) {
const message = 'Capability validated, but the configured provider is unavailable'
return {
conditions: [
{
type: PLUGIN_WORKLOAD_SDK_CONDITION_TYPE,
status: 'False',
reason: 'ProviderUnavailable',
message,
lastTransitionTime: now,
},
{
type: PLUGIN_WORKLOAD_SDK_PROVIDER_UNAVAILABLE_CONDITION_TYPE,
status: 'True',
reason: 'ProviderUnavailable',
message,
lastTransitionTime: now,
},
],
capability: {
state: 'degraded',
promptBridge,
clientNotifications,
message,
...CLEARED_PLUGIN_WORKLOAD_SDK_METADATA,
},
}
}
const clientNotificationsPolicyPending =
clientNotifications &&
bootstrapProof?.ready === true &&
bootstrapProof.clientNotificationsPolicyReady !== true
const codexBindingPending =
promptBridge &&
bootstrapProof?.provider === 'codex-subscription' &&
(bootstrapProof.policyReason === 'codex_execution_binding_missing' ||
bootstrapProof.contractVersion !== 3 ||
!bootstrapProof.codexBinding)
const grokBindingPending =
promptBridge &&
bootstrapProof?.provider === 'grok-subscription' &&
(bootstrapProof.policyReason === 'execution_binding_missing' ||
bootstrapProof.contractVersion !== 3 ||
!bootstrapProof.subscriptionBinding)
if (
policyPending ||
clientNotificationsPolicyPending ||
codexBindingPending ||
grokBindingPending
) {
const family =
promptBridge && (policyPending || codexBindingPending || grokBindingPending)
? 'promptBridge'
: 'clientNotifications'
const policyReason =
family === 'clientNotifications'
? (bootstrapProof?.clientNotificationsPolicyReason ??
bootstrapProof?.clientNotificationsPolicyState ??
'unknown')
: promptBridgePolicyPendingReason(bootstrapProof, codexBindingPending || grokBindingPending)
const message =
policyReason === 'grant_missing'
? `Plugin Workload SDK ${family} is awaiting an operator grant`
: `Plugin Workload SDK ${family} policy is not ready (${policyReason})`
return {
conditions: [
{
type: PLUGIN_WORKLOAD_SDK_CONDITION_TYPE,
status: 'False',
reason: 'PolicyNotConfigured',
message,
lastTransitionTime: now,
},
{
type: PLUGIN_WORKLOAD_SDK_POLICY_PENDING_CONDITION_TYPE,
status: 'True',
reason: policyReason,
message,
lastTransitionTime: now,
},
],
capability: {
state: 'awaiting_policy',
promptBridge,
clientNotifications,
message,
...CLEARED_PLUGIN_WORKLOAD_SDK_METADATA,
...(bootstrapProof
? {
bootstrapContractVersion: bootstrapProof.contractVersion,
bootstrapPodUid: bootstrapProof.podUid,
...(bootstrapProof.provider ? { bootstrapProvider: bootstrapProof.provider } : {}),
...(bootstrapProof.model ? { bootstrapModel: bootstrapProof.model } : {}),
verifiedAt: bootstrapProof.verifiedAt,
}
: {}),
},
}
}
if ((promptBridge || clientNotifications) && !bootstrapProof?.ready) {
const message = 'Plugin Workload SDK host readiness proof is not ready'
return {
conditions: [
{
type: PLUGIN_WORKLOAD_SDK_CONDITION_TYPE,
status: 'False',
reason: 'BootstrapNotReady',
message,
lastTransitionTime: now,
},
],
capability: {
state: 'degraded',
promptBridge,
clientNotifications,
message,
...CLEARED_PLUGIN_WORKLOAD_SDK_METADATA,
},
}
}
const families = [
promptBridge ? 'promptBridge' : undefined,
clientNotifications ? 'clientNotifications' : undefined,
]
.filter((f): f is string => f !== undefined)
.join(', ')
// issue #375 (R1): validatedAt is the stable "first reached validated" marker.
// On a steady-state throttle refresh (already validated, only verifiedAt
// advances) it must be CARRIED FORWARD, not reset to `now`. Stamp a fresh
// `now` ONLY on the real transition into validated — no prior capability, or a
// prior state other than 'validated', or a prior validated record that somehow
// lacked the marker.
const validatedAt =
existingCapability?.state === 'validated' && existingCapability.validatedAt
? existingCapability.validatedAt
: now
return {
conditions: [
{
type: PLUGIN_WORKLOAD_SDK_CONDITION_TYPE,
status: 'True',
reason: 'Validated',
message: `Capability validated (${families})`,
lastTransitionTime: now,
},
],
capability: {
state: 'validated',
promptBridge,
clientNotifications,
message: `Capability validated (${families})`,
...CLEARED_PLUGIN_WORKLOAD_SDK_METADATA,
validatedAt,
...(bootstrapProof
? {
bootstrapContractVersion: bootstrapProof.contractVersion,
bootstrapPodUid: bootstrapProof.podUid,
...(bootstrapProof.provider ? { bootstrapProvider: bootstrapProof.provider } : {}),
...(bootstrapProof.model ? { bootstrapModel: bootstrapProof.model } : {}),
verifiedAt: bootstrapProof.verifiedAt,
...(bootstrapProof.policyRevision !== undefined
? { policyRevision: bootstrapProof.policyRevision }
: {}),
...(bootstrapProof.policyHash !== undefined
? { policyHash: bootstrapProof.policyHash }
: {}),
...(bootstrapProof.defaultTargetRef !== undefined
? { defaultTargetRef: bootstrapProof.defaultTargetRef }
: {}),
}
: {}),
},
}
}