Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: address review findings on the correctness sweep
Jose Gabriel Ramirez Encinas5dd8b0b1dc81
diff --git a/.env.example b/.env.exampleindex 6d9a413a9..f7a429aa1 100644--- a/.env.example+++ b/.env.example@@ -32,8 +32,9 @@ ZAI_API_KEY=BAILIAN_API_KEY=# Setup auto-selects the agent's provider from the first of the four keys above.-# Every other supported provider is read too (and written to the LLM Secret),-# but needs CLERUM_MODEL_PROVIDER + CLERUM_MODEL_NAME below to be selected:+# Other supported providers need CLERUM_MODEL_PROVIDER + CLERUM_MODEL_NAME below,+# and their key reaches the cluster only when you run `make minikube-apply-secrets`+# after `make minikube-setup` (setup itself writes only the four keys above):# OPENROUTER_API_KEY GEMINI_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY# TOGETHER_API_KEY FIREWORKS_API_KEY MISTRAL_API_KEY XAI_API_KEY# CEREBRAS_API_KEY DEEPINFRA_API_KEY PERPLEXITY_API_KEY MOONSHOT_API_KEYdiff --git a/control-ui/README.md b/control-ui/README.mdindex 00be5964e..f39addd7d 100644--- a/control-ui/README.md+++ b/control-ui/README.md@@ -38,7 +38,7 @@ Sidebar destinations map to the public routes in `app/constants/routes.ts` (`com| Cost & Usage | `/cost-and-usage/usage`, `/cost-and-usage/llm-prices`, `/cost-and-usage/token-budgets` | Token usage dashboard, model prices, token budgets || Settings | `/settings/ui` | Control settings panel |-Routes not in the sidebar: `/users-and-teams/admins/new` (invite a control admin; `/control-admins/new` redirects there), `/plugin-workload-sdk` (SDK grants and invocation search), `/traces/*` (hidden Traces section), and the public token flows listed above. Legacy paths such as `/cost/*`, `/registry`, `/publisher/*`, `/mcp-servers`, `/hosts` and `/contexts` redirect to their current locations (`next.config.js`, `components/LegacyContextRedirect`).+Routes not in the sidebar: `/users-and-teams/admins/new` (invite a control admin; `/control-admins/new` redirects there), `/plugins/sdk` (SDK grants and invocation search), `/traces/*` (hidden Traces section), and the public token flows listed above. Legacy paths such as `/cost/*`, `/registry`, `/publisher/*`, `/mcp-servers`, `/hosts` and `/contexts` redirect to their current locations (`next.config.js`, `components/LegacyContextRedirect`).## Notable Featuresdiff --git a/control-ui/package-lock.json b/control-ui/package-lock.jsonindex 89df19642..191082cb1 100644--- a/control-ui/package-lock.json+++ b/control-ui/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-control-ui",- "version": "0.1.729",+ "version": "0.1.730","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-control-ui",- "version": "0.1.729",+ "version": "0.1.730","dependencies": {"@clerum/display-field": "file:../packages/display-field","@clerum/frontend-components": "file:../packages/frontend-components",diff --git a/control-ui/package.json b/control-ui/package.jsonindex a23f3ab42..86b2a5f69 100644--- a/control-ui/package.json+++ b/control-ui/package.json@@ -1,6 +1,6 @@{"name": "clerum-control-ui",- "version": "0.1.729",+ "version": "0.1.730","private": true,"scripts": {"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",diff --git a/docs/crds/host.md b/docs/crds/host.mdindex 23877a459..2475cbc9b 100644--- a/docs/crds/host.md+++ b/docs/crds/host.md@@ -49,7 +49,6 @@ represents a single LLM agent instance (an "agent" in Control UI and the Desktop| `spec.personalization.soul` | string | no | Content of `SOUL.md` (system-prompt section "## Core Values"). || `spec.personalization.agents` | string | no | Content of `AGENTS.md` (system-prompt section "## Agent Instructions"). || `spec.personalization.user` | string | no | Content of `USER.md` (system-prompt section "## User Context"). |-| `spec.guardrails` | object | no | Opt-in guardrail policy. A Host without it runs no rules or hooks. See [Guardrails](#guardrails). |### Guardrailsdiff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.mdindex 1450066f5..3ea4d4d5a 100644--- a/docs/crds/llmhook.md+++ b/docs/crds/llmhook.md@@ -29,37 +29,38 @@ install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,## Spec Fields-| Field | Type | Required | Description |-| -------------------------------------------- | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `spec.target` | object | yes | Exactly one of `image`, `service`, `remote`. |-| `spec.target.image.ref` | string | yes (image) | Container image. Validated against the image allowlist and digest-pinned at install. |-| `spec.target.image.port` | int | yes (image) | Port the hook HTTP server listens on (1–65535). |-| `spec.target.image.imagePullSecrets` | string[] | no | Pull secret names in `llm-hooks`. |-| `spec.target.image.envSecret` | string | no | The hook's own credential Secret in `llm-hooks`. It can never reference a Host or LLM-key Secret. |-| `spec.target.image.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. Looser than McpServer egress: no private-range hardening yet. |-| `spec.target.image.security.addCapabilities` | string[] | no | Subset of `CHOWN`, `FOWNER`, `DAC_OVERRIDE`, `NET_BIND_SERVICE`. |-| `spec.target.service` | object | yes (service) | Existing in-cluster Service: `name`, `namespace`, `port`. |-| `spec.target.remote.baseUrl` | string | yes (remote) | External endpoint mcp-host dials directly. Must be `https://`; SSRF-validated at dial time. |-| `spec.target.remote.authHeadersSecret` | string | no | Secret supplying auth headers for the remote endpoint. |-| `spec.path` | string | no (default `/`) | Calls go to `{endpoint}{path}/v1/{point}`. Co-located image hooks must use distinct paths. |-| `spec.lifecyclePoints` | string[] | yes (1–6) | LLM lane: `preCall`, `moderate`, `postCallSuccess`, `onError`. Tool lane: `preToolUse`, `postToolUse`. |-| `spec.contentAccess` | `metadata` \| `content` | no | What the hook receives. **Omitting it means `content`.** Only a `preCall`-only hook may declare `metadata` (model, params and usage, no message bodies). |-| `spec.order` | int | no (default 100) | Order within a phase; lower runs first. |-| `spec.failMode` | `open` \| `closed` | no (default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. |-| `spec.timeoutMs` | int | no (default 5000) | Per-call timeout. |-| `spec.onUnavailable` | object | no | Circuit breaker: `mode` (`strict` \| `breaker`, default `strict`), `failureThreshold` (default 5), `cooldownMs` (default 30000). |-| `spec.capabilities` | string[] | no | Admin-granted: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Must fall within the Host's `guardrails.capabilityCeiling`, and is re-checked on every hook response. |-| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |--### Admission rules+| Field | Type | Required | Description |+| -------------------------------------------- | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `spec.target` | object | yes | Exactly one of `image`, `service`, `remote`. |+| `spec.target.image.ref` | string | yes (image) | Container image. Validated against the image allowlist and digest-pinned at install. |+| `spec.target.image.port` | int | yes (image) | Port the hook HTTP server listens on (1–65535). |+| `spec.target.image.imagePullSecrets` | string[] | no | Pull secret names in `llm-hooks`. |+| `spec.target.image.envSecret` | string | no | The hook's own credential Secret in `llm-hooks`. It can never reference a Host or LLM-key Secret. |+| `spec.target.image.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. host-context-controller rejects private, metadata, link-local and reserved destinations at reconcile (condition `InvalidEgress`) and fails the hook pod closed; unlike McpServer, this is not checked at admission. |+| `spec.target.image.security.addCapabilities` | string[] | no | Subset of `CHOWN`, `FOWNER`, `DAC_OVERRIDE`, `NET_BIND_SERVICE`. |+| `spec.target.service` | object | yes (service) | Existing in-cluster Service: `name`, `namespace`, `port`. |+| `spec.target.remote.baseUrl` | string | yes (remote) | External endpoint mcp-host dials directly. Must be `https://`; SSRF-validated at dial time. |+| `spec.target.remote.authHeadersSecret` | string | no | Secret supplying auth headers for the remote endpoint. |+| `spec.path` | string | no (default `/`) | Calls go to `{endpoint}{path}/v1/{point}`. Co-located image hooks must use distinct paths. |+| `spec.lifecyclePoints` | string[] | yes (1–6) | LLM lane: `preCall`, `moderate`, `postCallSuccess`, `onError`. Tool lane: `preToolUse`, `postToolUse`. |+| `spec.contentAccess` | `metadata` \| `content` | no | What the hook receives. **Omitting it means `content`.** Only a `preCall`-only hook may declare `metadata` (model, params and usage, no message bodies). |+| `spec.order` | int | no (default 100) | Order within a phase; lower runs first. |+| `spec.failMode` | `open` \| `closed` | no (default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. |+| `spec.timeoutMs` | int | no (default 5000) | Per-call timeout. |+| `spec.onUnavailable` | object | no | Circuit breaker: `mode` (`strict` \| `breaker`, default `strict`), `failureThreshold` (default 5), `cooldownMs` (default 30000). |+| `spec.capabilities` | string[] | no | Admin-granted: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Must fall within the Host's `guardrails.capabilityCeiling`, and is re-checked on every hook response. |+| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |++### Admission and install rules- `remote.baseUrl` must start with `https://`.- A hook granted `may_deny` must use `failMode: closed`.- `contentAccess: metadata` is rejected for `moderate`, `postCallSuccess`,`onError`, `preToolUse` and `postToolUse`, which are inherentlycontent-bearing.-- A content-bearing hook that has `egressBindings` or a `remote` target can- only be installed at trust level `high`.+- At install time (not CRD admission), a content-bearing hook that has+ `egressBindings` or a `remote` target is accepted only at trust level+ `high`.## Status Fieldsdiff --git a/docs/crds/mcpserver.md b/docs/crds/mcpserver.mdindex 73b38b4f2..e80de7292 100644--- a/docs/crds/mcpserver.md+++ b/docs/crds/mcpserver.md@@ -55,7 +55,8 @@ time and are **never mounted into the connector pod**.> in `deploy/base` (the minikube overlay turns it on). While it is off,> OAuth connectors keep asking for consent and never get a token. Also set> `CONTROL_API_OAUTH_CALLBACK_BASE_URL` to the browser-reachable control-api-> origin; otherwise callbacks fall back to an internal hostname.+> origin; otherwise registry OAuth installs are refused, and other callbacks+> fall back to the request host (an internal hostname behind the proxy chain).There are three configuration styles, chosen by `source`, which can't changeafter creation:diff --git a/docs/get-started/minikube.md b/docs/get-started/minikube.mdindex dcd6bd181..9b1be1bb3 100644--- a/docs/get-started/minikube.md+++ b/docs/get-started/minikube.md@@ -7,7 +7,8 @@ service, deny-all NetworkPolicies, the JWT chain, and a seeded agent namedfrom the registry when you want more. Setup infers the provider from the first of`OPENAI_API_KEY`, `CLAUDE_API_KEY`, `ZAI_API_KEY`, `BAILIAN_API_KEY` set in`.env`; for any other provider also set `CLERUM_MODEL_PROVIDER` and-`CLERUM_MODEL_NAME`.+`CLERUM_MODEL_NAME`, then run `make minikube-apply-secrets` after setup (setup+itself writes only those four keys).## Prerequisitesdiff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.mdindex 4cd0e11cf..89ed4da70 100644--- a/docs/get-started/quickstart.md+++ b/docs/get-started/quickstart.md@@ -24,8 +24,11 @@ named `chatllm` you can message immediately.Mistral, … see [the full list](../llm-providers/README.md)) put its key in`.env` **and** set `CLERUM_MODEL_PROVIDER` and `CLERUM_MODEL_NAME`. The pairmust be enabled in the model allowlist, or setup stops with- `HOST_MODEL_UNKNOWN`. Without any key, setup still boots, but the agent- can't reply until you add one.+ `HOST_MODEL_UNKNOWN`. Setup only writes the four keys above to the cluster,+ so after `make minikube-setup` run `make minikube-apply-secrets` and then+ `kubectl rollout restart deployment/chatllm -n mcp-host --context clerum-test`.+ Without any key, setup still boots, but the agent can't reply until you add+ one.## 1. Configure