Skip to content

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

TypeScript

test(np08): close cross-context review gaps

Alfredo Lopez1f3559b6398c
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 7df555478..00cb1f8ab 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -765,7 +765,11 @@ The former caller-selected Context and global `/auth` routes are retired with
HTTP 410; the remaining global v1 inventory is metadata-only transitional
surface for the separately reviewed mcp-proxy PR2 and is not used by mcp-host.
-Polling interval: 30 seconds (configurable via `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL`)
+Polling interval: 30 seconds (configurable via `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL`).
+In cluster mode it must remain strictly below the 60-second
+`HCC_AUTHORITY_MAX_STALENESS_MS` ceiling; mcp-host rejects an invalid relation at
+startup rather than allowing the fleet to flap between successful polls and
+authority revocation.
On each poll, mcp-host compares new server list with previous state and:
@@ -810,26 +814,27 @@ The HTTP response is held open until the agent finishes processing. The response
### Configuration
-| Variable | Default | Description |
-| ------------------------------------- | ---------------- | ----------------------------------------------- |
-| `CLERUM_DEV_MODE` | `false` | Enable dev mode |
-| `CLERUM_HOST_NAME` | - | Host CRD name (production, required) |
-| `CLERUM_NAMESPACE` | `"default"` | Kubernetes namespace |
-| `CLERUM_SERVER_PORT` | `8080` | HTTP server port |
-| `CLERUM_CONTEXT_MAPPER_URL` | auto | Context-mapper service URL |
-| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | `30000` | Poll interval (ms) |
-| `CLERUM_MODEL_PROVIDER` | auto-detected | `"openai"`, `"claude"`, `"zai"`, or `"bailian"` |
-| `CLERUM_MODEL_NAME` | provider default | Specific model name |
-| `OPENAI_API_KEY` | - | OpenAI key (dev mode) |
-| `CLAUDE_API_KEY` | - | Claude key (dev mode) |
-| `ZAI_API_KEY` | - | ZAI/z.ai key (dev mode) |
-| `BAILIAN_API_KEY` | - | Bailian/DashScope key (dev mode) |
-| `CLERUM_HOST_CONFIG` | - | JSON host config (dev mode) |
-| `CLERUM_MCP_SERVERS` | - | JSON MCP server array (dev mode) |
-| `CLERUM_AGENT_TASK_DELAY` | `100` | Delay between tasks (ms) |
-| `CLERUM_AGENT_MAX_TASK_DURATION` | `300000` | Max task duration (ms) |
-| `CLERUM_AGENT_MAX_TOOL_CALLS` | `50` | Max tool calls per task |
-| `CLERUM_AGENT_MAX_QUEUE_SIZE` | `100` | Max pending queue size |
+| Variable | Default | Description |
+| ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
+| `CLERUM_DEV_MODE` | `false` | Enable dev mode |
+| `CLERUM_HOST_NAME` | - | Host CRD name (production, required) |
+| `CLERUM_NAMESPACE` | `"default"` | Kubernetes namespace |
+| `CLERUM_SERVER_PORT` | `8080` | HTTP server port |
+| `CLERUM_CONTEXT_MAPPER_URL` | auto | Context-mapper service URL |
+| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | `30000` | Poll interval (ms) |
+| `HCC_AUTHORITY_MAX_STALENESS_MS` | `60000` | Maximum retained HCC authority (ms); must be greater than the poll interval in cluster mode |
+| `CLERUM_MODEL_PROVIDER` | auto-detected | `"openai"`, `"claude"`, `"zai"`, or `"bailian"` |
+| `CLERUM_MODEL_NAME` | provider default | Specific model name |
+| `OPENAI_API_KEY` | - | OpenAI key (dev mode) |
+| `CLAUDE_API_KEY` | - | Claude key (dev mode) |
+| `ZAI_API_KEY` | - | ZAI/z.ai key (dev mode) |
+| `BAILIAN_API_KEY` | - | Bailian/DashScope key (dev mode) |
+| `CLERUM_HOST_CONFIG` | - | JSON host config (dev mode) |
+| `CLERUM_MCP_SERVERS` | - | JSON MCP server array (dev mode) |
+| `CLERUM_AGENT_TASK_DELAY` | `100` | Delay between tasks (ms) |
+| `CLERUM_AGENT_MAX_TASK_DURATION` | `300000` | Max task duration (ms) |
+| `CLERUM_AGENT_MAX_TOOL_CALLS` | `50` | Max tool calls per task |
+| `CLERUM_AGENT_MAX_QUEUE_SIZE` | `100` | Max pending queue size |
### Dependencies
diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.json
index a1cd7f004..e10918442 100644
--- a/host-context-controller/package-lock.json
+++ b/host-context-controller/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-host-context-controller",
- "version": "0.1.229",
+ "version": "0.1.230",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-host-context-controller",
- "version": "0.1.229",
+ "version": "0.1.230",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/host-context-controller/package.json b/host-context-controller/package.json
index 93c3c7e54..5206c61af 100644
--- a/host-context-controller/package.json
+++ b/host-context-controller/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-host-context-controller",
- "version": "0.1.229",
+ "version": "0.1.230",
"description": "Host Context Controller - provides McpServer CRDs to mcp-host via REST API",
"main": "dist/main.js",
"engines": {
diff --git a/host-context-controller/src/mcpApiAuthentication.test.ts b/host-context-controller/src/mcpApiAuthentication.test.ts
index 290e954e2..e6f306364 100644
--- a/host-context-controller/src/mcpApiAuthentication.test.ts
+++ b/host-context-controller/src/mcpApiAuthentication.test.ts
@@ -83,6 +83,7 @@ describe('McpApiAuthenticator', () => {
it.each([
{ mcpCapabilities: [] },
+ { mcpCapabilities: ['mcp:credential:write'] },
{ mcpCapabilities: [MCP_CREDENTIAL_READ_CAPABILITY, 'extra'] },
{ host_uid: undefined },
{ hostRefs: ['host-a', 'host-b'] },
diff --git a/host-context-controller/src/mcpAuthorization.test.ts b/host-context-controller/src/mcpAuthorization.test.ts
index a7c50f80d..7cb1605cb 100644
--- a/host-context-controller/src/mcpAuthorization.test.ts
+++ b/host-context-controller/src/mcpAuthorization.test.ts
@@ -77,6 +77,11 @@ class FakeStore implements McpAuthorizationStore {
hostSequence: Array<AuthorityHost | null> | null = null
contextSequence: Array<AuthorityContext | null> | null = null
serverSequence: Array<AuthorityMcpServer | null> | null = null
+ hostObjects: Map<string, AuthorityHost | null> | null = null
+ contextObjects: Map<string, AuthorityContext | null> | null = null
+ serverObjects: Map<string, AuthorityMcpServer | null> | null = null
+ secretMetadataObjects: Map<string, AuthoritySecretMetadata | null> | null = null
+ secretObjects: Map<string, AuthoritySecret | null> | null = null
hostReads = 0
contextReads = 0
serverReads = 0
@@ -84,34 +89,39 @@ class FakeStore implements McpAuthorizationStore {
contextObject: AuthorityContext | null = context
serverObject: AuthorityMcpServer | null = server
- async readHost() {
+ async readHost(name: string) {
this.hostReads += 1
+ if (this.hostObjects) return this.hostObjects.get(name) ?? null
return this.hostSequence
? this.hostSequence[Math.min(this.hostReads - 1, this.hostSequence.length - 1)]
: this.hostObject
}
- async readContext() {
+ async readContext(name: string) {
this.contextReads += 1
+ if (this.contextObjects) return this.contextObjects.get(name) ?? null
return this.contextSequence
? this.contextSequence[Math.min(this.contextReads - 1, this.contextSequence.length - 1)]
: this.contextObject
}
- async readMcpServer() {
+ async readMcpServer(name: string) {
this.serverReads += 1
+ if (this.serverObjects) return this.serverObjects.get(name) ?? null
return this.serverSequence
? this.serverSequence[Math.min(this.serverReads - 1, this.serverSequence.length - 1)]
: this.serverObject
}
- async readSecretMetadata() {
+ async readSecretMetadata(name: string) {
this.secretMetadataReads += 1
+ if (this.secretMetadataObjects) return this.secretMetadataObjects.get(name) ?? null
const value =
this.secretMetadataSequence[
Math.min(this.secretMetadataReads - 1, this.secretMetadataSequence.length - 1)
]
return value ? { name: value.name, namespace: value.namespace, metadata: value.metadata } : null
}
- async readSecret() {
+ async readSecret(name: string) {
this.secretValueReads += 1
+ if (this.secretObjects) return this.secretObjects.get(name) ?? null
return this.secretSequence[Math.min(this.secretValueReads - 1, this.secretSequence.length - 1)]
}
}
@@ -133,50 +143,62 @@ async function expectCredentialFailure(
describe('McpAuthorizationService', () => {
it('keeps two Host/Context grant sets disjoint in both directions', async () => {
- const storeA = new FakeStore()
- const storeB = new FakeStore()
- storeB.hostObject = {
+ const hostB: AuthorityHost = {
name: 'host-b',
namespace: 'mcp-host',
metadata: meta('host-uid-b', '11'),
contextRef: 'context-b',
}
- storeB.contextObject = contextB
- storeB.serverObject = serverB
- storeB.secretMetadataSequence = [
- {
- name: 'server-b-auth',
- namespace: 'mcp-server',
- metadata: meta('secret-uid-b', '41'),
- },
- ]
- storeB.secretSequence = [
- {
- name: 'server-b-auth',
- namespace: 'mcp-server',
- metadata: meta('secret-uid-b', '41'),
- data: { token: Buffer.from('credential-b').toString('base64') },
- },
- ]
+ const secretB: AuthoritySecret = {
+ name: 'server-b-auth',
+ namespace: 'mcp-server',
+ metadata: meta('secret-uid-b', '41'),
+ data: { token: Buffer.from('credential-b').toString('base64') },
+ }
+ const store = new FakeStore()
+ store.hostObjects = new Map([
+ [host.name, host],
+ [hostB.name, hostB],
+ ])
+ store.contextObjects = new Map([
+ [context.name, context],
+ [contextB.name, contextB],
+ ])
+ store.serverObjects = new Map([
+ [server.name, server],
+ [serverB.name, serverB],
+ ])
+ store.secretMetadataObjects = new Map([
+ [secret.name, secret],
+ [secretB.name, secretB],
+ ])
+ store.secretObjects = new Map([
+ [secret.name, secret],
+ [secretB.name, secretB],
+ ])
- const serviceA = new McpAuthorizationService(storeA)
- const serviceB = new McpAuthorizationService(storeB)
- await expect(serviceA.listServers(principal)).resolves.toEqual([
+ const service = new McpAuthorizationService(store)
+ await expect(service.listServers(principal)).resolves.toEqual([
expect.objectContaining({ name: 'server-a' }),
])
- await expect(serviceB.listServers(principalB)).resolves.toEqual([
+ await expect(service.listServers(principalB)).resolves.toEqual([
expect.objectContaining({ name: 'server-b' }),
])
- await expect(serviceA.getCredential(principal, 'server-b')).rejects.toMatchObject({
+ const readsBeforeForeignRequests = {
+ secretMetadata: store.secretMetadataReads,
+ secretValue: store.secretValueReads,
+ }
+ await expect(service.getCredential(principal, 'server-b')).rejects.toMatchObject({
code: 'not_found',
})
- await expect(serviceB.getCredential(principalB, 'server-a')).rejects.toMatchObject({
+ await expect(service.getCredential(principalB, 'server-a')).rejects.toMatchObject({
code: 'not_found',
})
- expect(storeA.secretMetadataReads).toBe(1)
- expect(storeA.secretValueReads).toBe(0)
- expect(storeB.secretMetadataReads).toBe(1)
- expect(storeB.secretValueReads).toBe(0)
+ expect(store.secretMetadataReads).toBe(readsBeforeForeignRequests.secretMetadata)
+ expect(store.secretValueReads).toBe(readsBeforeForeignRequests.secretValue)
+ await expect(service.getCredential(principalB, 'server-b')).resolves.toMatchObject({
+ token: 'credential-b',
+ })
})
it('projects only valid TCP ports into the public transport contract', () => {
diff --git a/mcp-host/README.md b/mcp-host/README.md
index a104d0ddd..922a9b949 100644
--- a/mcp-host/README.md
+++ b/mcp-host/README.md
@@ -25,6 +25,7 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr
| `CLERUM_SERVER_PORT` | Sets the HTTP listen port for the runtime API server. | `CLERUM_SERVER_PORT=8080` |
| `CLERUM_CONTEXT_MAPPER_URL` | Points to the host-context-controller endpoint used to resolve MCP servers for a context. | `CLERUM_CONTEXT_MAPPER_URL=http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` |
| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | Controls polling interval (milliseconds) for MCP server config changes from context mapper. | `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL=30000` |
+| `HCC_AUTHORITY_MAX_STALENESS_MS` | Maximum time a previously published MCP fleet may survive without a fresh authenticated HCC snapshot. It is capped at 60000 ms and must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. | `HCC_AUTHORITY_MAX_STALENESS_MS=60000` |
| `CLERUM_HOST_CONFIG` | Provides a full Host spec as JSON in dev mode, overriding provider/model context env composition. | `CLERUM_HOST_CONFIG={"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}` |
| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |
| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 1d8ebec3c..51dfa9140 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.273",
+ "version": "0.1.274",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.273",
+ "version": "0.1.274",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index e8f570de9..af8f046f9 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.273",
+ "version": "0.1.274",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/config.hccAuthority.test.ts b/mcp-host/src/config.hccAuthority.test.ts
index 6b512225b..0296814d9 100644
--- a/mcp-host/src/config.hccAuthority.test.ts
+++ b/mcp-host/src/config.hccAuthority.test.ts
@@ -2,9 +2,13 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
const originalEnv = process.env
-async function loadAuthorityMaxStaleness(value: string | undefined): Promise<number> {
+async function loadAuthorityMaxStaleness(
+ value: string | undefined,
+ pollInterval = '30000'
+): Promise<number> {
vi.resetModules()
process.env = { ...originalEnv }
+ process.env.CLERUM_CONTEXT_MAPPER_POLL_INTERVAL = pollInterval
if (value === undefined) {
delete process.env.HCC_AUTHORITY_MAX_STALENESS_MS
} else {
@@ -24,7 +28,7 @@ describe('HCC_AUTHORITY_MAX_STALENESS_MS', () => {
})
it('allows an operator to fail closed sooner', async () => {
- await expect(loadAuthorityMaxStaleness('15000')).resolves.toBe(15_000)
+ await expect(loadAuthorityMaxStaleness('15000', '5000')).resolves.toBe(15_000)
})
it('cannot be configured beyond the 60-second authority ceiling', async () => {
@@ -34,4 +38,23 @@ describe('HCC_AUTHORITY_MAX_STALENESS_MS', () => {
it('uses the safe ceiling for an invalid value', async () => {
await expect(loadAuthorityMaxStaleness('not-a-duration')).resolves.toBe(60_000)
})
+
+ it('rejects a poll interval that reaches the authority ceiling', async () => {
+ const { validateHccAuthorityTiming } = await import('./config')
+ expect(() => validateHccAuthorityTiming(60_000, 60_000)).toThrow(
+ 'CLERUM_CONTEXT_MAPPER_POLL_INTERVAL (60000ms) must be less than HCC_AUTHORITY_MAX_STALENESS_MS (60000ms)'
+ )
+ expect(() => validateHccAuthorityTiming(75_000, 60_000)).toThrow()
+ })
+
+ it('fails production configuration when the poll interval reaches the ceiling', async () => {
+ await expect(loadAuthorityMaxStaleness('15000', '30000')).rejects.toThrow(
+ 'CLERUM_CONTEXT_MAPPER_POLL_INTERVAL (30000ms) must be less than HCC_AUTHORITY_MAX_STALENESS_MS (15000ms)'
+ )
+ })
+
+ it('accepts the default 30-second poll inside the 60-second ceiling', async () => {
+ const { validateHccAuthorityTiming } = await import('./config')
+ expect(() => validateHccAuthorityTiming(30_000, 60_000)).not.toThrow()
+ })
})
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index 66a42d4b9..71b4db83c 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -475,6 +475,29 @@ export function resolveDevModelProvider(raw: string | undefined): LlmProvider |
return raw
}
+/**
+ * Keep the poll cadence strictly inside the authority-retention window.
+ *
+ * A cadence at or above the staleness ceiling guarantees that a healthy fleet
+ * can be revoked before the next authoritative poll arrives. Failing startup
+ * closed is safer than silently widening the retention window or allowing a
+ * deployment to flap forever after every successful reconnect.
+ */
+export function validateHccAuthorityTiming(
+ contextMapperPollIntervalMs: number,
+ hccAuthorityMaxStalenessMs: number
+): void {
+ if (
+ Number.isFinite(contextMapperPollIntervalMs) &&
+ Number.isFinite(hccAuthorityMaxStalenessMs) &&
+ contextMapperPollIntervalMs >= hccAuthorityMaxStalenessMs
+ ) {
+ throw new Error(
+ `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL (${contextMapperPollIntervalMs}ms) must be less than HCC_AUTHORITY_MAX_STALENESS_MS (${hccAuthorityMaxStalenessMs}ms)`
+ )
+ }
+}
+
// In dev mode, try CLERUM_HOST_CONFIG first, then fall back to building from env vars
function getDevHostConfig(): HostSpec | undefined {
if (!devMode) return undefined
@@ -552,6 +575,20 @@ function parseApprovalPromptHistoryMaxBytes(raw: string): number {
return Number.isSafeInteger(value) && value >= 1_024 && value <= 32_768 ? value : Number.NaN
}
+const contextMapperPollInterval = parseInt(
+ getEnv('CLERUM_CONTEXT_MAPPER_POLL_INTERVAL', '30000')!,
+ 10
+)
+const hccAuthorityMaxStalenessMs = Math.min(
+ getEnvNumber('HCC_AUTHORITY_MAX_STALENESS_MS', 60_000),
+ 60_000
+)
+
+// Dev mode does not retain a Kubernetes-authoritative MCP fleet, so the
+// production polling/staleness relationship is intentionally not required for
+// local fixture runs. Every cluster-mode process must satisfy it at startup.
+if (!devMode) validateHccAuthorityTiming(contextMapperPollInterval, hccAuthorityMaxStalenessMs)
+
export const config: Config = {
devMode,
devHostConfig: getDevHostConfig(),
@@ -606,15 +643,12 @@ export const config: Config = {
)!,
// Context Mapper poll interval (default 30 seconds)
- contextMapperPollInterval: parseInt(getEnv('CLERUM_CONTEXT_MAPPER_POLL_INTERVAL', '30000')!, 10),
+ contextMapperPollInterval,
// Bound transient HCC/Kubernetes authority outages. Identity failures revoke
// immediately; 5xx/transport failures may preserve the last good fleet only
// within this finite window.
- hccAuthorityMaxStalenessMs: Math.min(
- getEnvNumber('HCC_AUTHORITY_MAX_STALENESS_MS', 60_000),
- 60_000
- ),
+ hccAuthorityMaxStalenessMs,
// MCP status heartbeat. Defaults to 30 seconds so a single missed tick does
// not trip desktop staleness.