Skip to content

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

TypeScript

fix(np08): align staleness tests and docs

Alfredo Lopez729e095f24fb
diff --git a/mcp-host/README.md b/mcp-host/README.md
index 922a9b949..b525d022d 100644
--- a/mcp-host/README.md
+++ b/mcp-host/README.md
@@ -17,48 +17,48 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr
### Environment Variables
-| Variable | Explanation | Canonical example |
-| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |
-| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |
-| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |
-| `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` |
-| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |
-| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=3600000` |
-| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=3600000` |
-| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |
-| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |
-| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |
-| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |
-| `CLERUM_AGENT_TASK_DELAY` | Delay in milliseconds between queued task processing attempts in the state machine loop. | `CLERUM_AGENT_TASK_DELAY=100` |
-| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum task runtime in milliseconds before task execution is treated as timed out. | `CLERUM_AGENT_MAX_TASK_DURATION=1800000` |
-| `CLERUM_AGENT_MAX_TOOL_CALLS` | Hard cap on tool calls per task to prevent unbounded tool loops. | `CLERUM_AGENT_MAX_TOOL_CALLS=50` |
-| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |
-| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |
-| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |
-| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |
-| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |
-| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction logic before pruning/summarization. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |
-| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |
-| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=600000` |
-| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=660000` |
-| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |
-| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |
-| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |
-| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |
-| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |
-| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |
-| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |
-| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |
-| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |
-| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |
-| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |
+| Variable | Explanation | Canonical example |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |
+| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |
+| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |
+| `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 an unavailable HCC (default 180000 ms; hard-capped at 600000 ms). It must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. Minikube pins 60000 ms for its deterministic staleness E2E. | `HCC_AUTHORITY_MAX_STALENESS_MS=180000` |
+| `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` |
+| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |
+| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=3600000` |
+| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=3600000` |
+| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |
+| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |
+| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |
+| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |
+| `CLERUM_AGENT_TASK_DELAY` | Delay in milliseconds between queued task processing attempts in the state machine loop. | `CLERUM_AGENT_TASK_DELAY=100` |
+| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum task runtime in milliseconds before task execution is treated as timed out. | `CLERUM_AGENT_MAX_TASK_DURATION=1800000` |
+| `CLERUM_AGENT_MAX_TOOL_CALLS` | Hard cap on tool calls per task to prevent unbounded tool loops. | `CLERUM_AGENT_MAX_TOOL_CALLS=50` |
+| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |
+| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |
+| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |
+| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |
+| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |
+| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction logic before pruning/summarization. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |
+| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |
+| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=600000` |
+| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=660000` |
+| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |
+| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |
+| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |
+| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |
+| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |
+| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |
+| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |
+| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |
+| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |
+| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |
+| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |
### Host CRD
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 96f47cfe4..7f6e1cb32 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.276",
+ "version": "0.1.277",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.276",
+ "version": "0.1.277",
"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 feb6bd6ea..1908c8523 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.276",
+ "version": "0.1.277",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/__tests__/main.mcpInitialization.test.ts b/mcp-host/src/__tests__/main.mcpInitialization.test.ts
index c918ded98..7f8520686 100644
--- a/mcp-host/src/__tests__/main.mcpInitialization.test.ts
+++ b/mcp-host/src/__tests__/main.mcpInitialization.test.ts
@@ -531,14 +531,16 @@ describe('authoritative poll publication fence', () => {
describe('context-mapper polling lifecycle', () => {
it('wires the live manager and configured staleness ceiling into poll failure handling', () => {
const manager = {}
+ const lastSuccessAt = 1_000
+ const staleNow = lastSuccessAt + config.hccAuthorityMaxStalenessMs
const revoke = vi.fn()
const onCallerAuthorizationRejected = vi.fn()
const onInventoryAuthorityRevoked = vi.fn()
const onUnavailable = vi.fn()
const options = createMcpAuthorityPollFailureOptions({
getManager: () => manager,
- lastSuccessAt: () => 1_000,
- now: () => 61_000,
+ lastSuccessAt: () => lastSuccessAt,
+ now: () => staleNow,
revoke,
onCallerAuthorizationRejected,
onInventoryAuthorityRevoked,
@@ -562,8 +564,8 @@ describe('context-mapper polling lifecycle', () => {
new ContextMapperRequestError(503, 'inventory', false),
createMcpAuthorityPollFailureOptions({
getManager: () => null,
- lastSuccessAt: () => 1_000,
- now: () => 61_000,
+ lastSuccessAt: () => lastSuccessAt,
+ now: () => staleNow,
revoke: noManagerRevoke,
onCallerAuthorizationRejected: vi.fn(),
onInventoryAuthorityRevoked: vi.fn(),
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index 27fe2480d..dc58d5ed0 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -587,11 +587,12 @@ const contextMapperPollInterval = parseInt(
//
// Crucially, this window ONLY governs the `unavailable` failure class. Identity /
// authorization failures (401/403 — Host UID change, revoked grant) revoke
-// immediately on the next reachable call and are NOT gated by this value, and a
-// grant change while HCC is healthy is applied by the next successful poll. So
-// raising this ceiling does not delay any real authority revocation and does not
-// widen the NP-08 credential-disclosure surface (which lives entirely in HCC's
-// per-request authorization). See issue #425.
+// immediately on the next reachable call, and a grant change while HCC is healthy
+// is applied by the next successful poll. Raising this ceiling intentionally trades
+// bounded revocation latency during an HCC outage for fleet availability; it does
+// not widen the NP-08 credential-disclosure surface because HCC cannot serve a new
+// credential while unavailable and rechecks live authorization when reachable.
+// See issue #425.
//
// Operators may lower it, or raise it up to HCC_AUTHORITY_MAX_STALENESS_CEILING_MS
// for slower-starting clusters. The minikube e2e lane pins 60000 explicitly so the