Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: address second-round review on correctness sweep
Jose Gabriel Ramirez Encinasc3272dd6bc5f
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdindex 81872f958..8d424676f 100644--- a/docs/architecture/overview.md+++ b/docs/architecture/overview.md@@ -520,9 +520,9 @@ a `Set<string>` so an unchanged hostRef triggers exactly one reconcile.**RBAC:** HCC's `host-context-controller-channels-runtime` Role grants`get/list/watch` on `communicationchannels.clerum.io` in the `channels`-namespace. **Applied out-of-band** via `make gcp-dev-bootstrap-rbac` /-`make gcp-prod-bootstrap-rbac` because the CD service account intentionally-cannot grant RBAC (see `deploy/scripts/post-deploy-sync.sh`).+namespace. **Applied out-of-band** with+[`deploy/scripts/bootstrap-rbac.sh`](../../deploy/scripts/bootstrap-rbac.sh),+because a deploy service account should not be able to grant RBAC.---@@ -1443,12 +1443,19 @@ Default: `your-registry.example.com/evenfire/`### Full Production Deployment Sequence+The service Makefiles only build and push images; they have no `deploy`+target. The workloads ship as Kustomize manifests under `deploy/base`, applied+through an overlay. [Production deployment](../deploy/production.md) gives the+rollout order, and [minikube](../deploy/minikube.md) is the scripted reference+(`make minikube-deploy-all`).+```bash# 1. Install CRDshelm install clerum-crds ./charts/clerum-crds-# 2. Deploy host-context-controller (operator must run first)-cd host-context-controller && make deploy+# 2. Apply the platform manifests (deploy/base through your overlay):+# host-context-controller first, then control-api, mcp-host,+# channel-reader and the proxies# 3. Deploy MCP server secrets and CRDscd mcp-servers && make deploy-all@@ -1456,16 +1463,10 @@ cd mcp-servers && make deploy-all# 4. Create Context CRD (defines which servers are accessible)kubectl apply -f charts/clerum-crds/examples/context1.yaml-# 5. Deploy mcp-host-cd mcp-host && make deploy--# 6. Create Host CRD with API keys secret+# 5. Create Host CRD with API keys secretkubectl apply -f charts/clerum-crds/examples/host-chatllm.yaml-# 7. Deploy channel-reader-cd channel-reader && make deploy--# 8. Create CommunicationChannel CRD+# 6. Create CommunicationChannel CRDkubectl apply -f charts/clerum-crds/examples/channels.yaml```diff --git a/docs/architecture/stateless-invariants.md b/docs/architecture/stateless-invariants.mdindex 83af6039c..ab7b9cb79 100644--- a/docs/architecture/stateless-invariants.md+++ b/docs/architecture/stateless-invariants.md@@ -7,9 +7,9 @@ reusable anti-patterns**. Four of the five share one root cause: _a decisionmade on evidence that had already aged between its producer and itsconsumer._ Encode these as guardrails so the class does not reappear.-This doc is the "how to not reintroduce the class" companion to the-narrative in-[`docs/architecture/overview.md` §12 (Stateless Agents / Host Lifecycle)](overview.md#12-stateless-agents-host-lifecycle).+This doc is the "how to not reintroduce the class" companion to the Host+stateless lifecycle fields (`spec.lifecycle.stateless`, `status.lifecycle`) in+the [Host CRD reference](../crds/host.md#spec-fields).---diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.mdindex 3ea4d4d5a..b54916cec 100644--- a/docs/crds/llmhook.md+++ b/docs/crds/llmhook.md@@ -16,8 +16,9 @@ A Host opts in by listing hooks under `Host.spec.guardrails.hooks.<phase>[]`(see [Host CRD](host.md)). A Host without a `guardrails` block runs no hooks.- **Image targets:** host-context-controller deploys a Deployment, Service,- and NetworkPolicy in `llm-hooks`. Hooks that share an image digest are- co-located on one pod and routed by `spec.path`.+ and NetworkPolicy in `llm-hooks`. Hooks with the same image ref, port,+ `envSecret`, `egressBindings` and `addCapabilities` are co-located on one+ pod and routed by `spec.path`; a difference in any of these gets its own pod.- **Service and remote targets:** nothing is deployed.- **Who writes what:** mcp-host only reads LlmHook CRs. Only the controllerwrites `status`.@@ -32,11 +33,11 @@ install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,| 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.ref` | string | yes (image) | Container image. Must be digest-pinned at install; the image allowlist is checked only when `CONTROL_API_ENFORCE_IMAGE_ALLOWLIST` is on (default off). || `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.egressBindings[]` | object[] | no | Allowed external egress: `toFQDN` or `cidr`, plus `ports`. host-context-controller rejects private, metadata, link-local and reserved destinations at reconcile (reason `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. |@@ -64,12 +65,12 @@ install stamps a platform-assigned `clerum.io/trust-level` annotation (`low`,## Status Fields-| Field | Description |-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `status.observedDigest` | Image digest actually running. mcp-host binds `Host.spec.guardrails.hooks[].digest` against this, and fails closed (or skips with an alert) on mismatch. |-| `status.readyReplicas` | Ready replicas (image targets only). |-| `status.lastReconciled` | Timestamp of the last successful reconcile. |-| `status.conditions[]` | Standard conditions (`Deployed`, `Ready`) with `observedGeneration`. |+| Field | Description |+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `status.observedDigest` | Image digest actually running. mcp-host binds `Host.spec.guardrails.hooks[].digest` against this, and fails closed (or skips with an alert) on mismatch. |+| `status.readyReplicas` | Ready replicas (image targets only). |+| `status.lastReconciled` | Timestamp of the last successful reconcile. |+| `status.conditions[]` | A single `Ready` condition with `observedGeneration`; its `reason` is one of `NoWorkload`, `Deploying`, `Ready`, `DuplicatePath`, `SecretNotFound`, `InvalidEgress`, `ReconcileError`. |`kubectl get llmhooks -n llm-hooks` shows Path, Order, FailMode, Digest, and Ready.diff --git a/docs/crds/mcpserver.md b/docs/crds/mcpserver.mdindex e80de7292..e4163c45f 100644--- a/docs/crds/mcpserver.md+++ b/docs/crds/mcpserver.md@@ -72,7 +72,7 @@ after creation:|-------|-----------|-------------|| `oauth.id` | all | Stable client identifier; also the callback path segment. Immutable. || `oauth.provider` | built-in | `salesforce`, `slack`, `notion`, `microsoft-graph`, `google`, `monday`, `clickup`, `vercel`. Immutable. |-| `oauth.clientIdRef` / `oauth.clientSecretRef` | all | `{name, key}` of Secrets in the `mcp-servers` namespace holding the client id / secret. |+| `oauth.clientIdRef` / `oauth.clientSecretRef` | all | `{name, key}` of Secrets in the `mcp-server` namespace (control-api's `CONTROL_API_MCP_SERVERS_NAMESPACE`) holding the client id / secret. || `oauth.scopes[]` | all | Scopes to request. Include the provider's offline/refresh scope when `backgroundAccess` is true. || `oauth.backgroundAccess` | all | Allow use by a workload with no live human session. || `oauth.grantScope` | all | `user` (default): every user authorizes their own grant. `context`: one shared identity per Context, which one member bootstraps and others inherit. Immutable. |diff --git a/docs/features/self-hosted-registry-ux-redesign.md b/docs/features/self-hosted-registry-ux-redesign.mdindex 9c669ad04..53e59e5c8 100644--- a/docs/features/self-hosted-registry-ux-redesign.md+++ b/docs/features/self-hosted-registry-ux-redesign.md@@ -8,7 +8,7 @@> function that changes, grouped by the spec's five phases.>> **Scope boundary:** control-ui only. Confirmed **zero new backend endpoints**-> are required for phases 1–5 (see [Backend: no new endpoints](#backend-no-new-endpoints)).+> are required for phases 1–5 (see [Backend: no new endpoints](#04-backend-no-new-endpoints)).---diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.mdindex 89ed4da70..538b10bea 100644--- a/docs/get-started/quickstart.md+++ b/docs/get-started/quickstart.md@@ -24,7 +24,8 @@ 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`. Setup only writes the four keys above to the cluster,+ `HOST_MODEL_UNKNOWN` (pair not in the allowlist) or `HOST_MODEL_DISABLED`+ (pair listed but disabled). 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 adddiff --git a/docs/get-started/registry-quickstart.md b/docs/get-started/registry-quickstart.mdindex c37d3e074..7ab43549d 100644--- a/docs/get-started/registry-quickstart.md+++ b/docs/get-started/registry-quickstart.md@@ -90,13 +90,16 @@ press **Install**.| Field | Notes || --------------- | ------------------------------------------------------------------------------------------------- |-| **Name** | Optional. Left blank, it is generated from the entry name and version. Must be a valid K8s name. |+| **Server name** | Under **Configuration**. Optional. Left blank, it is generated from the entry name and version. || **Credentials** | Only if the entry declares them. Fill in **all** fields or **none** (empty installs it pending). || **Egress** | Review the external hosts the connector needs. Default-deny networking means unlisted hosts fail. |-The install runs as a server-side saga: it verifies the bundle digest, creates-the `McpServer` with its own private access scope, and rolls back if a step-fails. Afterwards, grant it to agents from **Installed Connectors**.+The install runs as a server-side saga: it creates the `McpServer` with its own+private access scope and rolls back the Secrets and `McpServer` it created if a+later step fails. For a `local` (bundle) entry it also compares the bundle to+the registry's published digest and stops on a mismatch; when the registry+returns no digest, or the lookup fails, the install continues without that+check. Afterwards, grant it to agents from **Installed Connectors**.Verify it landed:diff --git a/docs/llm-providers/README.md b/docs/llm-providers/README.mdindex 85dd9eac7..05047e61a 100644--- a/docs/llm-providers/README.md+++ b/docs/llm-providers/README.md@@ -119,7 +119,7 @@ authenticates with an `api-key` header instead of `Authorization: Bearer`, and| Grok subscription | `grok-subscription` | OAuth sign-in held by control-api, no Secret slot | `CONTROL_API_GROK_SUBSCRIPTION_ENABLED`, `GROK_LLM_PROXY_EXECUTION_ENABLED`, `WRC_GROK_SUBSCRIPTION_ENABLED` (recipes); mcp-host's flag is injected per Host |These providers use a subscription account instead of an API key. An admin-signs in from Control UI (**Secrets → LLM → Subscriptions**,+signs in from Control UI (**Secrets → LLM Subscriptions** tab,`/secrets/llm/subscriptions`); control-apikeeps the OAuth tokens, and model traffic goes through the in-cluster`codex-llm-proxy` / `grok-llm-proxy`. A Host selects a sign-in withdiff --git a/docs/testing/desktop-headful-journeys.md b/docs/testing/desktop-headful-journeys.mdindex 39e046e2b..348b68090 100644--- a/docs/testing/desktop-headful-journeys.md+++ b/docs/testing/desktop-headful-journeys.md@@ -49,10 +49,26 @@ journey always runs.cd desktop-app# dev Evenfire must be closed (process-wide single-instance lock)# keep control-api / external-rest-api / rpc-proxy port-forwarded to loopback-# (for a local minikube: make -C .. minikube-pf-desktop)+# (standard single minikube profile: make -C .. minikube-pf-desktop,+# fixed ports 8090 / 8091 / 8094)npm run qa:recorder:navigation # one journey-npm run qa:recorder:all # all 13 specs / 22 tests+npm run qa:recorder:all # all 14 specs / 23 tests+```++On a **branch-owned profile** the forwards use profile-owned ports instead of+8091 / 8094. Hold them on the host and point the recorder at them:++```bash+MINIKUBE_PROFILE=<owned-profile> \+ make -f scripts/minikube-profiles/branch.mk branch-profile-pf # from the repo root+MINIKUBE_PROFILE=<owned-profile> \+ make -f scripts/minikube-profiles/branch.mk branch-profile-info # prints the ports++cd desktop-app+EXTERNAL_REST_API_BASE_URL=http://127.0.0.1:<external-rest-api-port> \+RPC_PROXY_BASE_URL=http://127.0.0.1:<rpc-proxy-port> \+ npm run qa:recorder:navigation````qa:recorder:all` includes `qa-recorder-model-selector.spec.ts`, which fails loudlydiff --git a/scripts/e2e/README-mongodb-mcp-dev.md b/scripts/e2e/README-mongodb-mcp-dev.mdindex 89cd471e4..2784c56a1 100644--- a/scripts/e2e/README-mongodb-mcp-dev.md+++ b/scripts/e2e/README-mongodb-mcp-dev.md@@ -49,7 +49,7 @@ bash scripts/e2e/fix-mongodb-probes-dev.sh # re-apply probe workarou### Validate Desktop App against the stack```bash-# ensure port-forwards are running first (make gcp-dev-pf-desktop)+# first keep control-api :8090, external-rest-api :8091 and rpc-proxy :8094 forwarded to loopbackbash scripts/e2e/playwright-dev.sh chat.test.ts -g "MongoDB"# ── Visual debug modes ──