Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: address second-round review on feature guides
Jose Gabriel Ramirez Encinas2b4475418844
diff --git a/docs/crds/host.md b/docs/crds/host.mdindex e9c9d8bb1..3c359d13a 100644--- a/docs/crds/host.md+++ b/docs/crds/host.md@@ -60,8 +60,8 @@ represents a single LLM agent instance (an "agent" in Control UI and the Desktop| `guardrails.builtins[]` | First-party hooks compiled into mcp-host (e.g. `prompt-shaping`, `token-trim`). || `guardrails.minInstalledHookTrustLevel` | `low` \| `mid` \| `high`: minimum trust level for hooks installed onto this Host. Checked by control-api when a hook is installed or upgraded, not at runtime. || `guardrails.capabilityCeiling[]` | Upper bound on the capabilities an install may grant: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Checked at install/upgrade, not at runtime, so a hand-edited LlmHook is not re-validated against it. |-| `guardrails.approvalPolicies[]` | Accepted by the schema (`cli_only`, `channel_users`, `designated_approvers`) but not read by mcp-host today; `ask` decisions use `spec.approval`. |-| `guardrails.limits` | `maxRules` (100) and `maxHookTimeoutMs` (5000, the deadline for every hook call) are enforced. `maxHookOutputBytes` (65536 when a `limits` object is present; otherwise mcp-host allows 1 MiB, and 5 MiB for `preCall` rewrites) applies to LLM-lane hooks. `maxHooksPerPhase` is accepted but not enforced. |+| `guardrails.approvalPolicies[]` | Accepted by the schema (`cli_only`, `channel_users`, `designated_approvers`) but not read by mcp-host today; `ask` decisions use `spec.approval`, or mcp-host's `CLERUM_APPROVAL_CONFIG` when `spec.approval` is unset. |+| `guardrails.limits` | `maxRules` (100) and `maxHookTimeoutMs` (5000, the transport timeout for each hook call on both lanes) are enforced; LLM-lane hooks also have a fixed 15000 ms hard deadline, so a larger value has no effect there. `maxHookOutputBytes` (65536 when a `limits` object is present; otherwise 1 MiB) caps `moderate`, `postCallSuccess` and `onError` hook responses. It does not apply to `preCall` (always 5 MiB) or to tool-lane hooks (1 MiB). `maxHooksPerPhase` is accepted but not enforced. |Apply the CRD before any component writes `spec.guardrails`: the API serversilently prunes fields an older CRD does not know.diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.mdindex 90c36d95d..b117a0a1c 100644--- a/docs/crds/llmhook.md+++ b/docs/crds/llmhook.md@@ -49,7 +49,7 @@ either at runtime.| `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 (CRD default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. The Control UI install form preselects the hook author's suggested fail mode, or `open`; granting `may_deny` forces `closed`. |-| `spec.timeoutMs` | int | no (default 5000) | Accepted but not used today; the deadline is the Host's `guardrails.limits.maxHookTimeoutMs` (default 5000). |+| `spec.timeoutMs` | int | no (default 5000) | Accepted but not used today; the transport timeout is the Host's `guardrails.limits.maxHookTimeoutMs` (default 5000). LLM-lane calls also stop at a fixed 15000 ms hard deadline. || `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`. Checked against the Host's `guardrails.capabilityCeiling` at install time; mcp-host ignores response actions the hook was not granted. || `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |@@ -67,12 +67,12 @@ either at runtime.## Status Fields-| Field | Description |-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `status.observedDigest` | Image digest actually running. mcp-host compares it with `Host.spec.guardrails.hooks[].digest`. On a mismatch the hook is quarantined: calls are treated as unavailable, so a `may_deny` hook denies and an advisory hook contributes nothing (LLM-lane points). |-| `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. For `image` targets whose Host reference pins `Host.spec.guardrails.hooks[].digest`, mcp-host compares the two. On a mismatch the hook is quarantined at LLM-lane points: calls are treated as unavailable, so a `may_deny` hook denies and an advisory hook contributes nothing. Tool-lane points are not quarantined. |+| `status.readyReplicas` | Ready replicas (image targets only). |+| `status.lastReconciled` | Timestamp of the last successful reconcile. |+| `status.conditions[]` | Standard conditions (`Deployed`, `Ready`) with `observedGeneration`. |`kubectl get llmhooks -n llm-hooks` shows Path, Order, FailMode, Digest, and Ready.diff --git a/docs/how-to/add-mcp-server.md b/docs/how-to/add-mcp-server.mdindex c331a868b..4a87d0f12 100644--- a/docs/how-to/add-mcp-server.md+++ b/docs/how-to/add-mcp-server.md@@ -8,8 +8,9 @@ platform enforces that with NetworkPolicies on Kubernetes.When running `mcp-host` standalone (`CLERUM_DEV_MODE=true npm run dev`), wireservers with `CLERUM_MCP_SERVERS` (JSON array). Each entry needs `name`,-`contextRef`, `transport`, `enabled`, and-`status: { deployed: true, ready: true }` or it is skipped as not ready:+`contextRef`, `transport`, `enabled`, and `status.ready: true`, or it is+skipped as not ready (mcp-host checks only `ready`; `deployed` in the example+is not read):```bashCLERUM_MCP_SERVERS=[{"name":"my-mcp","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://my-mcp:3000/mcp"},"enabled":true,"status":{"deployed":true,"ready":true}}]diff --git a/docs/how-to/configure-approvals.md b/docs/how-to/configure-approvals.mdindex f0bf37619..2e912d869 100644--- a/docs/how-to/configure-approvals.md+++ b/docs/how-to/configure-approvals.md@@ -1,13 +1,21 @@# How to: configure human-in-the-loop approvalsThe approval system is **on by default** (`CLERUM_ENABLE_APPROVAL` defaults to-`true`). **MCP tool calls always require approval** — they **suspend** until an-explicit approve or deny, and the per-tool overrides below do not apply to them.+`true`). **An MCP tool call suspends** until an explicit approve or deny unless+an earlier approval already covers it: approving once for the rest of the+turn, an "always" grant for the tool, or a grant for its whole MCP server lets+later matching calls run without a new prompt. The per-tool overrides below do+not apply to MCP tools.Among **native** tools, five require approval by default — `shell_exec`,-`http_request`, `cron_manage`, `browser_open`, and `browser_navigate` — while-every other native tool runs without prompting; each native tool can be flipped-with a per-tool override on `Host.spec.approval`. Pending approvals are-persisted so they survive pod restarts.+`http_request`, `cron_manage`, `browser_open`, and `browser_navigate`.+`workflow_trigger` also requires approval, except when the task came from+Telegram, Slack or Teams. Every other native tool runs without prompting. Each+native tool can be flipped with a per-tool override on `Host.spec.approval`.++Pending approvals are kept in mcp-host's conversation store. The default store+(`CLERUM_SESSION_STORE=memory`) is in memory, so a pod restart loses them.+Stateless Hosts use the SQLite store on their workspace volume, and the+minikube overlay sets `CLERUM_SESSION_STORE=sqlite`.## Mental model@@ -103,8 +111,12 @@ stay approval-required by default regardless of what is set here. See| Telegram / Slack | Mobile / chat-native approve-deny || Control plane APIs | Automation and integration tests |-Channel callbacks are signature-verified; unauthorized actors cannot mint-approvals by replaying chat. Wiring a chat surface up:+Tool approvals from chat do not arrive as signed callbacks. channel-reader+polls Telegram (long polling) and Slack with the bot's own token, and drops+messages from senders the channel does not allow. Workflow approvals are+different: the workflow approval reader takes inbound callbacks and checks+Telegram's webhook secret token, Slack's HMAC signature, or Teams'+authorization. Wiring a chat surface up:[Connect Telegram](connect-telegram.md), [Connect Slack](connect-slack.md).## Verify@@ -112,7 +124,8 @@ approvals by replaying chat. Wiring a chat surface up:1. Trigger a tool-using prompt (or E2E suite that exercises approvals).2. Confirm a pending approval appears on the configured surface.3. Deny once and confirm the tool does not run; approve and confirm it does.-4. Restart `mcp-host` with a pending approval and confirm it still resolves.+4. On a Host that uses the SQLite store, restart `mcp-host` with a pending+ approval and confirm it still resolves.Cluster E2E coverage: [E2E guide](../testing/e2e-guide.md).diff --git a/docs/how-to/configure-guardrails.md b/docs/how-to/configure-guardrails.mdindex 7eb392f9b..e40df86c4 100644--- a/docs/how-to/configure-guardrails.md+++ b/docs/how-to/configure-guardrails.md@@ -53,8 +53,11 @@ provenance (see the example below).tasks are **unattended**. In an unattended run an `ask` becomesa deny ("approval required but no approver is available"), so the taskdoes not hang.-- `allow` does not skip approvals. MCP tools and the five risky native tools- still require approval under `spec.approval`.+- `allow` does not skip approvals. MCP tool calls still go through the+ approval gate, which `spec.approval` does not configure. Native tools+ still follow their own approval default (for example `shell_exec` and+ `http_request` ask) or the per-tool override in `spec.approval.tools`.+ See [Configure approvals](configure-approvals.md).## Option A — mcp-host dev mode@@ -228,19 +231,24 @@ the fields it does not edit when it saves.`may_deny` is requested; the form preselects the hook author's suggestedfail mode (or `open`), and **May deny** forces `closed`.-- **Timeouts.** The per-call deadline is the Host's- `limits.maxHookTimeoutMs`, default 5000 ms, on both lanes. mcp-host does- not read `LlmHook.spec.timeoutMs`.+- **Timeouts.** The Host's `limits.maxHookTimeoutMs` (default 5000 ms) is+ the transport timeout for each hook call on both lanes. LLM-lane hooks+ also have a fixed 15000 ms hard deadline, so on that lane a value above+ 15000 has no effect: the call reports unavailable after 15 seconds.+ mcp-host does not read `LlmHook.spec.timeoutMs`.- **Circuit breaker.** `onUnavailable.mode: breaker` (threshold 5, cooldown30000 ms by default) short-circuits a down hook without dialing it. Itapplies only to LLM-lane hooks **without** `may_deny`. A deny-capable hookis always dialed.-- **Digest binding.** For image hooks, mcp-host compares the Host's `digest`- with `LlmHook.status.observedDigest`. On a mismatch it quarantines the- hook: every call reports unavailable, so the fail-mode rules above apply.- The same happens to a co-located hook that lost a `DuplicatePath`- collision. Upgrade with `POST /admin/registry/upgrade-hook`, which bumps- the CR and every Host's digest together.+- **Digest binding.** For image hooks whose Host reference pins a `digest`,+ mcp-host compares it with `LlmHook.status.observedDigest` (once that is+ set). On a mismatch it quarantines the hook. Quarantine is enforced on the+ LLM lane only: there every call reports unavailable, so the fail-mode+ rules above apply. A tool-lane hook (`preToolUse`/`postToolUse`) with a+ mismatched digest is still dialed. The same quarantine applies to a+ co-located hook that lost a `DuplicatePath` collision. Upgrade with+ `POST /admin/registry/upgrade-hook`, which bumps the CR and every Host's+ digest together.- **The Host phase key does not filter.** mcp-host collects hook ids fromall phases. The `LlmHook`'s own `lifecyclePoints` decide where it runs.diff --git a/docs/how-to/connect-llm-subscription.md b/docs/how-to/connect-llm-subscription.mdindex 81f58796a..0f8c09cf3 100644--- a/docs/how-to/connect-llm-subscription.md+++ b/docs/how-to/connect-llm-subscription.md@@ -67,8 +67,8 @@ Notes:creates both.- Optional: `SUBSCRIPTION_CATALOG_SYNC_CRON_ENABLED` in `control-api-config`turns on periodic catalog refresh (see [Models and catalog sync](#models-and-catalog-sync)).-- The minikube overlay sets everything in the table under- `deploy/overlays/minikube/` (`configmaps/*` and+- The minikube overlay sets every row except `MCP_HOST_GROK_SUBSCRIPTION_ENABLED`+ (which HCC injects) under `deploy/overlays/minikube/` (`configmaps/*` and`patches/workflow-recipes-grok.yaml`).Restart the affected Deployments after you change a ConfigMap. For upgradediff --git a/docs/how-to/connect-oauth-connector.md b/docs/how-to/connect-oauth-connector.mdindex 824064113..0590cbcdd 100644--- a/docs/how-to/connect-oauth-connector.md+++ b/docs/how-to/connect-oauth-connector.md@@ -28,12 +28,12 @@ also rejects an OAuth server that pins a static `Authorization` header.## Prerequisites-| Setting (control-api) | Default | What happens if it is wrong |-| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `MCP_OAUTH_BROKER_ENABLED` | **Off** in `deploy/base`, `true` in the minikube overlay | The token broker answers `404`, mcp-host reads that as "no grant", and the agent asks for consent forever, even after the user authorizes. Accepts only `true` or `false`. |-| `CONTROL_API_OAUTH_CALLBACK_BASE_URL` | Unset in base, `http://127.0.0.1:8090` in minikube | Must be the bare, browser-reachable origin that routes `/api/v1/oauth-callback/` to control-api. When unset, control-api builds the redirect URI from the request Host, which is usually an internal hostname. Marketplace built-in and generic installs, and remote installs that use CIMD, DCR, or a per-server callback (no RFC 9207), are rejected while it is unset. |-| `CONTROL_API_OAUTH_STATE_HMAC_SECRET`, `CONTROL_API_OAUTH_ENCRYPTION_KEY` | Built-in dev values only when `NODE_ENV` is not `production` (production refuses to start without them); read from the control-api Secret in base | Generate real values (`deploy/scripts/gen-jwt-keys.sh` does this). The encryption key protects stored grants. |-| `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED` | **Off**, including in minikube | Remote-server tokens are only refreshed when someone uses them. See [Refresh and background use](#refresh-and-background-use). |+| Setting (control-api) | Default | What happens if it is wrong |+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `MCP_OAUTH_BROKER_ENABLED` | **Off** in `deploy/base`, `true` in the minikube overlay | The token broker answers `404`, mcp-host reads that as "no grant", and the agent asks for consent forever, even after the user authorizes. Accepts only `true` or `false`. |+| `CONTROL_API_OAUTH_CALLBACK_BASE_URL` | Unset in base, `http://127.0.0.1:8090` in minikube | Must be the bare, browser-reachable origin that routes `/api/v1/oauth-callback/` to control-api (and, for CIMD, `/api/v1/.well-known/evenfire-mcp-client`; see the gateway limitation below). When unset, control-api builds the redirect URI from the request Host, which is usually an internal hostname. Marketplace built-in and generic installs, and remote installs that use CIMD, DCR, or a per-server callback (no RFC 9207), are rejected while it is unset. |+| `CONTROL_API_OAUTH_STATE_HMAC_SECRET`, `CONTROL_API_OAUTH_ENCRYPTION_KEY` | Built-in dev values only when `NODE_ENV` is not `production` (production refuses to start without them); read from the control-api Secret in base | Generate real values (`deploy/scripts/gen-jwt-keys.sh` does this). The encryption key protects stored grants. |+| `OAUTH_PROACTIVE_REFRESH_CRON_ENABLED` | **Off**, including in minikube | Remote-server tokens are only refreshed when someone uses them. See [Refresh and background use](#refresh-and-background-use). |The Control UI **Marketplace** OAuth install form (built-in and genericproviders) shows the redirect URI using@@ -89,11 +89,25 @@ Context they belong to. Otherwise the request fails withcorrect URL.3. **Configure**: review the detected issuer, endpoints, scopes, and**Registration mode**. The mode is picked in this order:- - **Client ID Metadata Document (public client)**: no credentials. Offered- only when the server supports RFC 9207 `iss`. The client ID is a URL on- your callback origin- (`<CALLBACK_BASE>/api/v1/.well-known/evenfire-mcp-client`), so the- authorization server must be able to fetch it.+ - **Client ID Metadata Document (public client)**: no credentials. Picked+ automatically when the server supports RFC 9207 `iss`, advertises CIMD,+ and accepts public clients. The client ID is a URL on your callback+ origin (`<CALLBACK_BASE>/api/v1/.well-known/evenfire-mcp-client`), which+ control-api serves, so the authorization server must be able to fetch it+ from the internet.++ > **Gateway limitation.** The public gateway shipped in `deploy/base`+ > (the nginx config in `deploy/base/profiles/configmaps.yaml`) forwards+ > only `/api/v1/external/` and `/api/v1/oauth-callback/` to control-api+ > and answers `403` for every other path, including the client document. Behind that gateway,+ > CIMD authorization fails because the authorization server cannot fetch+ > the client ID. Until the gateway ships this route (tracked as a+ > follow-up), add a route that forwards+ > `/api/v1/.well-known/evenfire-mcp-client` to control-api in your+ > gateway or ingress. Minikube does not use this gateway: its callback+ > origin is a loopback port-forward to control-api, which serves the+ > path, but an authorization server on the internet cannot fetch a+ > loopback URL.- **Dynamic Client Registration**: control-api registers a client and storesits credentials encrypted. You do not supply any.- **Pre-registered client required**: register an OAuth app at the provider@@ -242,18 +256,19 @@ out too, but the screen only tracks the current one.## Troubleshooting-| Symptom | Likely cause | Fix |-| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |-| Agent keeps asking to **Connect** after the user authorized | `MCP_OAUTH_BROKER_ENABLED` is not `true` | Set it on control-api and restart |-| Provider says `redirect_uri` mismatch | Callback base is unset or wrong, or the registered URI differs from the one shown | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` to the public origin. Register the exact URI the wizard shows. |-| Remote install returns `callback_base_url_unconfigured` | CIMD, DCR, or a server without RFC 9207 needs the public callback origin | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` |-| **Detect** stops with an unreachable transport (`transport_unreachable` on install) | The URL is not the MCP endpoint | Use the URL the wizard suggests, or the server's documented MCP path |-| Marketplace OAuth form says the callback URL is not configured | `NEXT_PUBLIC_CONTROL_API_OAUTH_CALLBACK_BASE_URL` was not set when Control UI was built | Rebuild Control UI with it, or install with YAML |-| `503 integration_not_configured` | The client ID or secret Secret, or one of its keys, is missing | Create the Secret the hint names |-| `403 context_membership_denied` | The user is not a member of the server's Context | Add the user to the Context |-| Users must authorize again after a reinstall | Grants are bound to the old McpServer UID | Expected |-| Connector shows **Missing Secret** | `SecretResolved=False` | Use **Set credentials** on the **Credentials** tab |-| Rotation restarted other connectors | They share the same `envSecret` | Expected. Check `affectedConnectors`. |+| Symptom | Likely cause | Fix |+| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |+| Agent keeps asking to **Connect** after the user authorized | `MCP_OAUTH_BROKER_ENABLED` is not `true` | Set it on control-api and restart |+| Provider says `redirect_uri` mismatch | Callback base is unset or wrong, or the registered URI differs from the one shown | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` to the public origin. Register the exact URI the wizard shows. |+| Remote install returns `callback_base_url_unconfigured` | CIMD, DCR, or a server without RFC 9207 needs the public callback origin | Set `CONTROL_API_OAUTH_CALLBACK_BASE_URL` |+| CIMD authorization fails; the authorization server cannot fetch the client ID | The gateway does not route `/api/v1/.well-known/evenfire-mcp-client` (the `deploy/base` gateway returns `403`) | Forward that path to control-api in your gateway or ingress |+| **Detect** stops with an unreachable transport (`transport_unreachable` on install) | The URL is not the MCP endpoint | Use the URL the wizard suggests, or the server's documented MCP path |+| Marketplace OAuth form says the callback URL is not configured | `NEXT_PUBLIC_CONTROL_API_OAUTH_CALLBACK_BASE_URL` was not set when Control UI was built | Rebuild Control UI with it, or install with YAML |+| `503 integration_not_configured` | The client ID or secret Secret, or one of its keys, is missing | Create the Secret the hint names |+| `403 context_membership_denied` | The user is not a member of the server's Context | Add the user to the Context |+| Users must authorize again after a reinstall | Grants are bound to the old McpServer UID | Expected |+| Connector shows **Missing Secret** | `SecretResolved=False` | Use **Set credentials** on the **Credentials** tab |+| Rotation restarted other connectors | They share the same `envSecret` | Expected. Check `affectedConnectors`. |## Relateddiff --git a/docs/how-to/desktop-setup-and-updates.md b/docs/how-to/desktop-setup-and-updates.mdindex 694aa8d92..d9888b257 100644--- a/docs/how-to/desktop-setup-and-updates.md+++ b/docs/how-to/desktop-setup-and-updates.md@@ -91,8 +91,9 @@ update policy, so different tenants can be on different versions at the sametime. It asks that tenant's External REST API for its release info, including a`minimumDesktopVersion`. If the installed version is **below** that minimum, theapp shows a **Desktop update required** dialog; **Download update** opens the-release page for the new build (tag `desktop-app-<version>`) in your browser. (A packaged distribution is-where this matters most — a source checkout can just pull the latest.)+`releaseUrl` the server returns (the release tagged `v<desktopVersion>`) in+your browser. (A packaged distribution is where this matters most — a source+checkout can just pull the latest.)This is update **detection**, not silent auto-install: the app tells the user anupdate is required and links the release. Code signing, notarization, anddiff --git a/docs/surfaces/desktop-app.md b/docs/surfaces/desktop-app.mdindex 5d248a773..466e41621 100644--- a/docs/surfaces/desktop-app.md+++ b/docs/surfaces/desktop-app.md@@ -121,8 +121,9 @@ Two screens worth calling out specifically:everything the plugin's UI loads comes through `rpc-proxy`. The plugin getsa real interface; it does not get a second client to install.- - *Dev cluster, demo tenant.*+ + *Dev cluster, demo tenant. Captured before the "Back to apps" bar was+ removed; the sidebar now returns you to the app picker.*## How it is wired