Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: address second-round review on configuration and reference docs
Jose Gabriel Ramirez Encinas243b664f3304
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdindex 07b0ce9d9..c0d591802 100644--- a/docs/architecture/overview.md+++ b/docs/architecture/overview.md@@ -897,7 +897,9 @@ host-context-controller/> `deploy/base/control-plane/host-context-controller.yaml`.The controller reconciles six CRDs: `McpServer`, `Context`, `Host`,-`SharedFileSystem`, `GlobalFileSystem`, and `LlmHook`.+`SharedFileSystem`, `GlobalFileSystem`, and `LlmHook`. It also watches+`CommunicationChannel` resources in the `channels` namespace to size each+Host's channel-reader Deployment.### Operator Reconciliation@@ -1229,7 +1231,7 @@ For comprehensive testing documentation, see [mcp-servers/README.md §Testing](.### Namespace Layout & NetworkPolicy Strategy-Scoped to the four namespaces on the message path — for the full deny-all model across all 12 namespaces, see [platform-topology.md §2](platform-topology.md#2-security-architecture-deny-all-by-default).+Scoped to the four namespaces on the message path — for the full deny-all model across all 13 namespaces, see [platform-topology.md §2](platform-topology.md#2-security-architecture-deny-all-by-default).```mermaid%%{init: {'theme':'base', 'themeVariables': {'fontSize':'12px'}}}%%@@ -1251,7 +1253,7 @@ flowchart LRclass HCC ctrl```-`deploy/base/namespaces.yaml` declares ten namespaces: `channels`, `control-plane`, `mcp-host`, `mcp-server`, `profiles`, `rpc-proxy`, `sandbox-recipes`, `sandbox-ui`, `webhook-ingress`, `gfs`. The core four for the message path are:+`deploy/base/namespaces.yaml` declares eleven namespaces: `channels`, `control-plane`, `mcp-host`, `mcp-server`, `llm-hooks`, `profiles`, `rpc-proxy`, `sandbox-recipes`, `sandbox-ui`, `webhook-ingress`, `gfs` (the opt-in `ingress` namespace from `deploy/base/ingress/` and the minikube-only `registry` namespace bring the platform total to 13). The core four for the message path are:- `channels` - channel-reader (no inbound traffic needed)- `mcp-host` - mcp-host service (receives HTTP from channel-reader)@@ -1457,29 +1459,27 @@ Default: `your-registry.example.com/evenfire/`### Full Production Deployment Sequence+See [Production deployment](../deploy/production.md) for the full rollout order.+```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 (namespaces, host-context-controller,+# mcp-host, channel-reader, ...). The services have no per-service+# `make deploy`; build your own kustomize overlay on deploy/base.+kubectl apply -k <your-overlay>-# 3. Deploy MCP server secrets and CRDs-cd mcp-servers && make deploy-all+# 3. Deploy the example MCP server secrets and McpServer CRDs+make -C mcp-servers 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/platform-topology.md b/docs/architecture/platform-topology.mdindex bf4b93137..ee7b8a60d 100644--- a/docs/architecture/platform-topology.md+++ b/docs/architecture/platform-topology.md@@ -4,7 +4,7 @@> All other specification documents reference this document for architectural decisions.> When the architecture changes, update THIS document first, then propagate to specs.>-> **Security-First Architecture**: This document defines the 12-namespace architecture,+> **Security-First Architecture**: This document defines the 13-namespace architecture,> the controller architecture (HCC + WRC), the Sandbox Recipes Namespace, the RPC Proxy Namespace,> and the **deny-all by default** security posture across all runtime namespaces.diff --git a/docs/crds/context.md b/docs/crds/context.mdindex be92bea3e..18ceac5f2 100644--- a/docs/crds/context.md+++ b/docs/crds/context.md@@ -22,7 +22,7 @@ inject SharedFileSystem volume mounts into the mcp-host pod.| `spec.description` | string | no | Human-readable description of the context scope. || `spec.mcpServers` | string[] | yes | List of McpServer CRD names accessible within this context. When a host requests servers for this context, only these servers are returned by the context-mapper. || `spec.sharedFileSystems` | object[] | no | Optional list of SharedFileSystem references. Each entry causes HCC to inject a read-only volume mount into every mcp-host pod whose Host references this Context. Keyed on `mountPath` (unique within a Context). Each entry requires `name` (SharedFileSystem.metadata.name in the mcp-host namespace) and `mountPath` (absolute path inside the container, matching `^/[a-zA-Z0-9_.][a-zA-Z0-9_./\-]*$`). |-| `spec.gfs.mounts` | object[] | no | Optional Global File System mount intents. Intent only: HCC wires a mount only if the Context identity already holds the requested scopes. Keyed on `target`. Each entry requires `drive` (gfs drive name), `target` (32-hex resource id or absolute path), and `scopes` (array from `gfs.read`, `gfs.write`, `gfs.delete`, `gfs.manage_acl`, `gfs.share`). |+| `spec.gfs.mounts` | object[] | no | Optional Global File System mount intents. Defined in the schema, but host-context-controller does not read it in this release: an entry wires no mount and grants no access. (The CRD description's scope check lives in `host-context-controller/src/contextGfsMount.ts`, which has no production caller yet.) Keyed on `target`. Each entry requires `drive` (gfs drive name), `target` (32-hex resource id or absolute path), and `scopes` (array from `gfs.read`, `gfs.write`, `gfs.delete`, `gfs.manage_acl`, `gfs.share`). |## Status Fieldsdiff --git a/docs/crds/workflowrecipe.md b/docs/crds/workflowrecipe.mdindex 2b1c68b81..ccb217b46 100644--- a/docs/crds/workflowrecipe.md+++ b/docs/crds/workflowrecipe.md@@ -3104,18 +3104,20 @@ rolling-back --> rollback-failed (rollback itself fails)- `failed` --> `active` (must go through `candidate` for retry)- `rollback-failed` --> any state (terminal; manual cleanup required)-**Recovery from `failed` state**: Unlike `rollback-failed` (which is terminal), the `failed` state supports a retry path via `failed` --> `candidate`. The operator triggers this transition by annotating the WorkflowRecipe with `clerum.io/retry: "true"`. The controller:+**Recovery from `failed` state**: Unlike `rollback-failed` (which is terminal), the `failed` state supports a retry path via `failed` --> `candidate`. The operator triggers this transition with the control-api admin endpoint `POST /api/v1/admin/recipes/<name>/retry` (`control-api/src/routes/admin/recipes.ts`). No annotation triggers a retry. The endpoint:-1. Resets `status.workloads[].phase` to `pending` for all workloads-2. Preserves existing PVCs and Secrets (does not recreate)-3. Transitions to `candidate`, re-entering the approval flow+1. Returns `409 invalid_transition` unless `status.phase` is `failed`+2. Patches only the status subresource to `phase: candidate`, `message: "Manual retry requested by operator"`; the spec and existing resources are not touched+3. Leaves the rest to WRC: the next reconcile evaluates WorkflowRecipePolicies again and reconciles the workloads, and the phase settles from their readiness++A recipe that failed a policy check (`message` starting `Policy violation:`) needs this retry after the spec or policy is fixed; editing the spec alone does not re-run enforcement (see [WorkflowRecipePolicy](workflowrecipepolicy.md)).Retry counting is controller-internal. There is **no** `status.retryCount`property in the CRD status schema (§12.2) — the status object is structural withno `x-kubernetes-preserve-unknown-fields`, so such a key would be pruned — andthere is no `WorkflowRecipePolicy.governance.maxRetries` field.-This avoids the overhead of deleting and recreating the entire recipe (which loses status history and correlation ID) while still requiring re-approval for safety.+This avoids deleting and recreating the entire recipe, which loses status history and correlation ID.#### 12.1.1 Simplified Visible States (CLI/Dashboard Layer)diff --git a/docs/crds/workflowrecipepolicy.md b/docs/crds/workflowrecipepolicy.mdindex 810029328..96a77ff1a 100644--- a/docs/crds/workflowrecipepolicy.md+++ b/docs/crds/workflowrecipepolicy.md@@ -24,8 +24,13 @@ Things to know before you write one:- **No status.** The CRD has no status subresource. A violation shows up onthe *WorkflowRecipe*: `status.phase: failed` and `status.message:"Policy violation: [<policy>] <rule>: <detail>"`. WRC does not retry or- self-heal a policy failure. Fix the recipe spec (or the policy) to re-arm- enforcement.+ self-heal a policy failure, and editing the spec does not clear it: while+ the recipe is `failed` with a `Policy violation:` message, WRC skips policy+ evaluation and the recipe stays `failed`. After you fix the recipe spec (or+ the policy), call the control-api admin endpoint+ `POST /api/v1/admin/recipes/<name>/retry`. It moves the recipe to+ `candidate`, and the next reconcile evaluates the policies again. Deleting+ and re-creating the recipe also starts it from `candidate`.- **Many fields are not enforced yet.** The schema accepts more than WRCchecks. The tables below mark each field as **Enforced** or **Notenforced**. A not-enforced field is stored but nothing reads it.diff --git a/docs/reference/configuration.md b/docs/reference/configuration.mdindex 28f7f6e17..4153bbeed 100644--- a/docs/reference/configuration.md+++ b/docs/reference/configuration.md@@ -14,8 +14,9 @@ Full per-service variable lists live in each service's README (see> you create it. Only the minikube overlay ships one> (`deploy/overlays/minikube/configmaps/mcp-host-config.yaml`); copy it and> review each value (see [Production deployment](../deploy/production.md)).-> Variables you leave out take mcp-host's code defaults, so the mcp-host rows-> below are off unless your ConfigMap sets them.+> Variables you leave out take mcp-host's code defaults: the mcp-host rows in+> the two "Off" tables below stay off unless your ConfigMap sets them, and the+> mcp-host rows under [On by default](#on-by-default) stay on.Set boolean switches to the lowercase string `true`. Some services also accept`1` or other casings, but `true` works everywhere.@@ -36,7 +37,7 @@ Set boolean switches to the lowercase string `true`. Some services also accept| `CLERUM_MEMORY_ENABLED` | mcp-host (`mcp-host-config`) | Agent workspace memory | [mcp-host README](../../mcp-host/README.md) || `CLERUM_SESSION_SEARCH_ENABLED` | mcp-host (`mcp-host-config`) | Session search for agents | [mcp-host README](../../mcp-host/README.md) || `CONTROL_API_DESKTOP_GFS_OPERATOR_LINKING_ENABLED` | control-api (`control-api-config`) | Makes the initial Desktop admin an EvenDrive operator on self-hosted installs | [GFS operator parity](../architecture/gfs-desktop-operator-parity.md) |-| `PLUGIN_WORKLOAD_SDK_ENABLED` | workflow-recipes (Deployment env) | The Plugin Workload SDK for recipe workloads | [Plugin Workload SDK upgrade](../deploy/plugin-workload-sdk-upgrade.md) |+| `PLUGIN_WORKLOAD_SDK_ENABLED` | workflow-recipes (Deployment env) | The Plugin Workload SDK; WRC passes it to the mcp-host pods of recipes that declare it | [Plugin Workload SDK upgrade](../deploy/plugin-workload-sdk-upgrade.md) || `WRC_ENABLE_SNIPPET_RUNTIME` | workflow-recipes (Deployment env) | Snippet-based workflow coordinators | [WorkflowRecipes operations](../deploy/workflow-recipes-guide.md) || `WRC_ENABLE_CUSTOM_COORDINATOR_IMAGE` | workflow-recipes (Deployment env) | Custom coordinator images (digest-pinned) | [Workflow SDK](../../packages/workflow-sdk/README.md) || `CLERUM_NETWORK_POLICY_ENFORCEMENT_CONFIRMED` | workflow-recipes (Deployment env) | Confirms the cluster CNI enforces NetworkPolicies (enforcement mode is `required` in both) | [WorkflowRecipes operations](../deploy/workflow-recipes-guide.md) |@@ -45,25 +46,25 @@ Set boolean switches to the lowercase string `true`. Some services also accept## Off in both `deploy/base` and the minikube overlay-| Switch | Service | What it turns on |-| ----------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- |-| `CONTROL_API_ENFORCE_IMAGE_ALLOWLIST` | control-api | Reject connector images that are not on the allowlist (otherwise audit mode) |-| `CONTEXT_MAPPER_ENFORCE_IMAGE_ALLOWLIST` | host-context-controller | Block non-allowlisted connector images at reconcile (otherwise logged and allowed) |-| `SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED` | control-api | Periodic model-catalog refresh for subscription connections |-| `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED` | control-api | Refresh remote-connector OAuth tokens before they expire |-| `TRACING_APPROVAL_PROMPT_HISTORY_ENABLED` | control-api | Keep prompt history in approval traces |-| `CLERUM_PERSONALIZATION_ENABLED` | mcp-host | Identity files from `CLERUM_IDENTITY_SEED` in dev mode (Hosts use `spec.personalization`) |-| `MCP_PROXY_ENABLED` | mcp-host | Route MCP traffic through mcp-proxy |+| Switch | Service | What it turns on |+| ----------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |+| `CONTROL_API_ENFORCE_IMAGE_ALLOWLIST` | control-api | Reject connector images that are not on the allowlist (off: no image check at all) |+| `CONTEXT_MAPPER_ENFORCE_IMAGE_ALLOWLIST` | host-context-controller | Block non-allowlisted connector images at reconcile (otherwise logged and allowed) |+| `SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED` | control-api | Periodic model-catalog refresh for subscription connections |+| `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED` | control-api | Refresh remote-connector OAuth tokens before they expire |+| `TRACING_APPROVAL_PROMPT_HISTORY_ENABLED` | control-api, mcp-host | Keep prompt history in approval traces |+| `CLERUM_PERSONALIZATION_ENABLED` | mcp-host | Identity files from `CLERUM_IDENTITY_SEED` at startup when the Host has no personalization |+| `MCP_PROXY_ENABLED` | mcp-host | Route MCP traffic through mcp-proxy |## On by default-| Switch | Service | Note |-| ------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------- |-| `CLERUM_ENABLE_APPROVAL` | mcp-host | Human approval gate ([Configure approvals](../how-to/configure-approvals.md)) |-| `LLM_CATALOG_SYNC_CRON_ENABLED` | control-api | models.dev catalog sync; new rows arrive disabled for review |-| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | channel-reader | Send generated files back to channels |-| `WRC_ENABLE_DETERMINISTIC` | workflow-recipes | Deterministic workflow steps |-| `WORKFLOW_APPROVAL_NOTIFICATION_DELIVERY_ENABLED` | control-api | Deliver workflow approval notifications |+| Switch | Service | Note |+| ------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------- |+| `CLERUM_ENABLE_APPROVAL` | mcp-host | Human approval gate ([Configure approvals](../how-to/configure-approvals.md)) |+| `LLM_CATALOG_SYNC_CRON_ENABLED` | control-api | models.dev catalog sync; new rows arrive disabled for review |+| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | channel-reader, mcp-host | Send generated files back to channels |+| `WRC_ENABLE_DETERMINISTIC` | workflow-recipes | Deterministic workflow steps |+| `WORKFLOW_APPROVAL_NOTIFICATION_DELIVERY_ENABLED` | control-api | Deliver workflow approval notifications |## Where every variable is documenteddiff --git a/host-context-controller/README.md b/host-context-controller/README.mdindex 9f78c0ad8..8298d7ff4 100644--- a/host-context-controller/README.md+++ b/host-context-controller/README.md@@ -642,7 +642,8 @@ unchanged into the gfsc pods (`gfscEnv` in `src/k8s/gfsFactory.ts`):(written to the pod as the matching `GFS_UPLOAD_*` name;`CONTEXT_MAPPER_GFSC_UPLOAD_V2_ENABLED` goes to the writer only). HCC sets nodefault for these: an unset variable is not injected, and gfsc's own default-applies (`gfs-controller/src/config.ts`). `deploy/base` sets only+applies (`gfs-controller/src/config.ts`; for `GFS_MAX_WRITE_BODY_BYTES`, 16 MiB+in `gfs-controller/src/api/serve.ts`). `deploy/base` sets only`GFS_MAX_WRITE_BODY_BYTES` (`25165824`, 24 MiB).### NetworkPolicydiff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.jsonindex ce2ef8678..ff63c4035 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.383",+ "version": "0.1.384","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-host-context-controller",- "version": "0.1.383",+ "version": "0.1.384","license": "SEE LICENSE IN LICENSE","dependencies": {"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",diff --git a/host-context-controller/package.json b/host-context-controller/package.jsonindex d6a0ec384..eefa0f2ba 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.383",+ "version": "0.1.384","description": "Host Context Controller - provides McpServer CRDs to mcp-host via REST API","main": "dist/main.js","engines": {diff --git a/mcp-host/README.md b/mcp-host/README.mdindex 853cb5eae..9f0fdeded 100644--- a/mcp-host/README.md+++ b/mcp-host/README.md@@ -220,11 +220,11 @@ Precedence there is host Secret > host ConfigMap > LLM Secret > process env.| Variable | Default | Source | Description || -------------------------------- | ---------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |-| `CLERUM_MEMORY_ENABLED` | `false` | CM `true` | Enable workspace memory. Used when the Host has no `spec.memory`. |-| `CLERUM_MEMORY_WORKSPACE_PATH` | `/workspace` (`./workspace` in dev mode) | - | Memory workspace directory, used when the Host has no `spec.memory.workspacePath`. |+| `CLERUM_MEMORY_ENABLED` | `false` | CM `true` | Enable workspace memory. The Host CRD has no memory field, so this variable is the only switch. |+| `CLERUM_MEMORY_WORKSPACE_PATH` | `/workspace` (`./workspace` in dev mode) | - | Memory workspace directory. || `CLERUM_MEMORY_MD_MAX_BYTES` | `8192` | - | Size cap for `MEMORY.md`. || `CLERUM_MEMORY_SCAN_ENABLED` | `true` | - | Reject memory writes that match prompt-injection, exfiltration, invisible-Unicode or sensitive-path patterns. Only `false` turns it off. |-| `CLERUM_PERSONALIZATION_ENABLED` | `false` | CM `false` | Enable identity/personalization seeding. |+| `CLERUM_PERSONALIZATION_ENABLED` | `false` | CM `false` | Seed identity files from `CLERUM_IDENTITY_SEED` at startup when the Host has no `spec.personalization`. Requires memory to be enabled. || `CLERUM_IDENTITY_SEED` | unset | - | JSON seed with optional `identity`, `soul`, `agents` and `user` strings (contents for `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, `USER.md`). |#### Guardrails@@ -382,7 +382,7 @@ Get your Coding Plan API key at: https://modelstudio.console.alibabacloud.com/### Per-Tool Approval Overrides-`Host.spec.approval.tools` is an optional map that overrides each native tool's hard-coded `requiresApproval()` default. Use it to skip per-call approval for tools whose risk you mitigate via a different gate (e.g. `http_request` paired with `CLERUM_HTTP_ALLOWLIST`).+`Host.spec.approval.tools` is an optional map that overrides each native tool's hard-coded `requiresApproval()` default. Use it to skip per-call approval for tools whose risk you mitigate via a different gate (e.g. `http_request` paired with `CLERUM_HTTP_ALLOWLIST`). `CLERUM_HTTP_ALLOWLIST` is empty by default, and an empty list filters no domains, so set it before you turn off approval for `http_request`.```yamlspec:@@ -391,7 +391,7 @@ spec:channels:telegram: { enabled: true }tools:- http_request: false # skip approval — relies on CLERUM_HTTP_ALLOWLIST as the gate+ http_request: false # skip approval — only safe with a non-empty CLERUM_HTTP_ALLOWLISTshell_exec: true # explicit (matches code default; documents intent)```diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 0e6daaf99..f0dd480d9 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.558",+ "version": "0.1.559","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.558",+ "version": "0.1.559","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex 17bcdd016..c02498c8d 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.558",+ "version": "0.1.559","description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude","main": "dist/main.js","engines": {