Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

Merge commit 'e4f4f939b' into HEAD

Jose Gabriel Ramirez Encinas878c123bbdde
diff --cc docs/crds/llmhook.md
index b117a0a1c,b54916cec..1e4e12cad
--- a/docs/crds/llmhook.md
+++ b/docs/crds/llmhook.md
@@@ -32,27 -30,27 +33,27 @@@ either at runtime
## 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. 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 (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. |
-| `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. |
+| 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. |
+| `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 (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 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. |
### Admission and install rules
@@@ -67,12 -65,12 +68,12 @@@
## 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[]` | A single `Ready` condition with `observedGeneration`; its `reason` is one of `NoWorkload`, `Deploying`, `Ready`, `DuplicatePath`, `SecretNotFound`, `InvalidEgress`, `ReconcileError`. |
+| 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`. |
++| `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.