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.mdindex 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 CRDdiff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 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.jsonindex 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.tsindex 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.hccAuthorityMaxStalenessMsconst 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.tsindex 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