Skip to content

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

TypeScript

fix(control-api): preserve per-phase Host hook refs on hook upgrade

Jose Gabriel Ramirez Encinas42c9a434508c
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 86e53095b..092d6afee 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.737",
+ "version": "0.1.738",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.737",
+ "version": "0.1.738",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index d584b970e..2b01bf382 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.737",
+ "version": "0.1.738",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/services/__tests__/hostGuardrailRefs.test.ts b/control-api/src/services/__tests__/hostGuardrailRefs.test.ts
index 82d15949e..73ef15c2e 100644
--- a/control-api/src/services/__tests__/hostGuardrailRefs.test.ts
+++ b/control-api/src/services/__tests__/hostGuardrailRefs.test.ts
@@ -115,7 +115,7 @@ describe('hostGuardrailRefs', () => {
expect(store.get('b')!.spec.guardrails?.hooks).toEqual({})
})
- it('syncHookRefsInHosts sets the ref to exactly the new phases + digest', async () => {
+ it('syncHookRefsInHosts keeps the Host phases still supported, bumping the digest', async () => {
const { gateway, store } = gatewayWith([
// referenced today in preCall+moderate at the old digest.
host('a', {
@@ -131,13 +131,69 @@ describe('hostGuardrailRefs', () => {
'mcp-host'
)
const hooks = store.get('a')!.spec.guardrails?.hooks
- // moderate dropped, postCallSuccess added, new digest everywhere.
+ // moderate dropped (no longer supported); postCallSuccess NOT added (the Host
+ // never placed the hook there); new digest on what remains.
expect(hooks).toEqual({
preCall: [{ id: 'hook-x', digest: 'sha256:NEW' }],
- postCallSuccess: [{ id: 'hook-x', digest: 'sha256:NEW' }],
})
})
+ it('syncHookRefsInHosts does not re-add a phase the admin removed', async () => {
+ const { gateway, store } = gatewayWith([
+ // hook-x declares preCall+moderate; the admin removed it from moderate.
+ host('a', {
+ preCall: [{ id: 'other' }, { id: 'hook-x', digest: 'sha256:OLD' }],
+ moderate: [{ id: 'other' }],
+ }),
+ ])
+ await syncHookRefsInHosts(gateway, 'hook-x', ['preCall', 'moderate'], 'sha256:NEW', 'mcp-host')
+ expect(store.get('a')!.spec.guardrails?.hooks).toEqual({
+ preCall: [{ id: 'other' }, { id: 'hook-x', digest: 'sha256:NEW' }],
+ moderate: [{ id: 'other' }],
+ })
+ })
+
+ it('syncHookRefsInHosts keeps per-Host placements independent', async () => {
+ const { gateway, store } = gatewayWith([
+ host('a', { preCall: [{ id: 'hook-x', digest: 'sha256:OLD' }] }),
+ host('b', { moderate: [{ id: 'hook-x', digest: 'sha256:OLD' }] }),
+ ])
+ const touched = await syncHookRefsInHosts(
+ gateway,
+ 'hook-x',
+ ['preCall', 'moderate'],
+ 'sha256:NEW',
+ 'mcp-host'
+ )
+ expect(touched.sort()).toEqual(['a', 'b'])
+ expect(store.get('a')!.spec.guardrails?.hooks).toEqual({
+ preCall: [{ id: 'hook-x', digest: 'sha256:NEW' }],
+ })
+ expect(store.get('b')!.spec.guardrails?.hooks).toEqual({
+ moderate: [{ id: 'hook-x', digest: 'sha256:NEW' }],
+ })
+ })
+
+ it('syncHookRefsInHosts falls back to the new phases when none of the Host phases survive', async () => {
+ // Leaving the hook unreferenced would silently stop a guardrail the admin
+ // placed on this Host, so re-reference it at the upgraded hook's phases.
+ const { gateway, store } = gatewayWith([
+ host('a', { moderate: [{ id: 'hook-x', digest: 'sha256:OLD' }] }),
+ ])
+ await syncHookRefsInHosts(gateway, 'hook-x', ['preToolUse'], 'sha256:NEW', 'mcp-host')
+ expect(store.get('a')!.spec.guardrails?.hooks).toEqual({
+ preToolUse: [{ id: 'hook-x', digest: 'sha256:NEW' }],
+ })
+ })
+
+ it('syncHookRefsInHosts drops a digest when the upgrade has none', async () => {
+ const { gateway, store } = gatewayWith([
+ host('a', { preCall: [{ id: 'hook-x', digest: 'sha256:OLD' }] }),
+ ])
+ await syncHookRefsInHosts(gateway, 'hook-x', ['preCall'], undefined, 'mcp-host')
+ expect(store.get('a')!.spec.guardrails?.hooks).toEqual({ preCall: [{ id: 'hook-x' }] })
+ })
+
// ── lost-update guards ────────────────────────────────────────────────────
// Each write derives its map from a re-read taken INSIDE the write, so a ref
// another operation committed after our read survives. Deriving from the
diff --git a/control-api/src/services/hostGuardrailRefs.ts b/control-api/src/services/hostGuardrailRefs.ts
index 150a50476..1c5d1954a 100644
--- a/control-api/src/services/hostGuardrailRefs.ts
+++ b/control-api/src/services/hostGuardrailRefs.ts
@@ -127,10 +127,26 @@ export async function stripHookRefFromHosts(
return touched
}
+/** Phases (Host keys) under which `hooks` currently references `hookId`. */
+function phasesReferencing(hooks: Record<string, HookRef[]>, hookId: string): string[] {
+ return Object.keys(hooks).filter(
+ phase => Array.isArray(hooks[phase]) && hooks[phase].some(r => r?.id === hookId)
+ )
+}
+
/**
- * Coordinated upgrade: set the hook's reference on every referencing Host to
- * EXACTLY `lifecyclePoints` with the new `digest`, so the CR image bump and the
- * admin-pinned Host-ref digests move together. Returns the Host names touched.
+ * Coordinated upgrade: move the admin-pinned Host-ref digests together with the
+ * CR image bump, PRESERVING each Host's per-phase placement. mcp-host runs a
+ * hook only at the Host phases it is referenced under, so an admin's "Remove
+ * from <phase>" must survive an upgrade:
+ * - phases the Host references the hook under AND the upgraded hook still
+ * declares are kept, with the new `digest`;
+ * - phases the upgraded hook no longer declares are dropped;
+ * - phases the Host does not reference (e.g. removed by the admin, or newly
+ * declared by the upgrade) are NOT added.
+ * If none of the Host's phases survive the upgrade, the hook is re-referenced at
+ * the upgraded `lifecyclePoints` rather than silently left unreferenced (an
+ * installed guardrail that never runs). Returns the Host names touched.
*/
export async function syncHookRefsInHosts(
gateway: K8sGateway,
@@ -145,8 +161,11 @@ export async function syncHookRefsInHosts(
const name = host.metadata?.name
if (!name) continue
await mutateHostHooks(gateway, name, hostsNamespace, current => {
+ const declared = new Set(lifecyclePoints)
+ const kept = phasesReferencing(current, hookId).filter(phase => declared.has(phase))
+ const phases = kept.length > 0 ? kept : lifecyclePoints
const hooks = withoutHook(current, hookId)
- for (const phase of lifecyclePoints) {
+ for (const phase of phases) {
const arr = hooks[phase] ? [...hooks[phase]] : []
arr.push({ id: hookId, ...(digest ? { digest } : {}) })
hooks[phase] = arr