Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs(grok): answer the round-3 review doc and comment findings
Alfredo Lopeze2793d3f1c75
diff --git a/deploy/base/control-plane/grok-llm-proxy.yaml b/deploy/base/control-plane/grok-llm-proxy.yamlindex cc89e121a..f6a04a5ca 100644--- a/deploy/base/control-plane/grok-llm-proxy.yaml+++ b/deploy/base/control-plane/grok-llm-proxy.yaml@@ -93,8 +93,8 @@ spec:# byte-based BodyBudget also admits about eight compact bodies of# the worst structure the contract admits (#806 Q1), each a ~44 MiB# tree once parsed. With 8 held streams, 8 queued bodies and one- # V2 stream, 640 MiB passed 3 of 3 for Grok (it aborts the Codex- # proxy) and 768 MiB passed both; that load peaked at 1212-1482 MiB+ # V2 stream (two on the Codex proxy), 640 MiB passed 3 of 3 for+ # Grok (it aborts the Codex proxy) and 768 MiB passed both; that load peaked at 1212-1482 MiB# of RSS on macOS, which is not cgroup memory. 768 MiB is the# smallest cap tested that passes both, not a proven minimum.- name: NODE_OPTIONSdiff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.mdindex a08881875..ac5660040 100644--- a/docs/architecture/codex-subscription-transport-contract.md+++ b/docs/architecture/codex-subscription-transport-contract.md@@ -75,7 +75,9 @@ non-image bytes stay on the 6 MiB share. Non-chat rpc-proxy and Host controlroutes keep the 10 MB ordinary JSON cap. The proxy's largerparser requires a valid platform identity on the visual completion route.Admin and unauthenticated requests retain the ordinary configured body limit.-`CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES` controls the visual transport ceiling;+`CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES` is the visual transport ceiling and+must equal the contract cap: the proxy refuses to start when it is configured+below or above it;`CODEX_LLM_PROXY_MAX_BODY_BYTES` continues to control ordinary requests; themanifest leaves it unset so the proxy derives it from the contract cap plus theenvelope allowance.diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.mdindex 6348269d7..ceb8079c5 100644--- a/docs/architecture/grok-subscription-transport-contract.md+++ b/docs/architecture/grok-subscription-transport-contract.md@@ -97,7 +97,8 @@ Where the envelope is enforced:`client_max_body_size 36700160`;- `grok-llm-proxy` reads a V2 body with a separate parser whose limit is`GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES`, 36700160 in the base manifest; the- proxy refuses to start when it is configured below the contract cap.+ value must equal the contract cap, and the proxy refuses to start when it is+ configured below or above it.V2 has no outer deadline. Its deadline is `request.deadlineMs`, part of theauthorized hash. The Host refuses to stream with a deadline other than the@@ -168,7 +169,8 @@ admits about eight compact bodies of that structure (2.8 MiB each) or aboutfive at 4.7 MiB, and each parse allocates a tree of about 44 MiB once collected,plus transient copies. At a 384 MiB heap cap that load aborted without-of-memory before any upstream call. With 8 held streams, 8 queued bodies-and one V2 stream, 640 MiB passed Grok (peak RSS 1118-1250 MiB) but aborted+and the visual gate full (one V2 stream for Grok, two for Codex, whose gate is+two wide), 640 MiB passed Grok (peak RSS 1118-1250 MiB) but abortedthe Codex proxy in 3 of 3 runs, and 768 MiB passed both proxies in 3 of 3(Grok peak RSS 1212-1482 MiB). macOS RSS is not cgroup memory and varied byabout 100 MiB between runs; 768 MiB is the smallest cap tested that passes@@ -207,7 +209,12 @@ Errors:`invalid_request` before #784), and the proxy refuses size with 413`payload_too_large`. The Host maps `payload_too_large` to`LLM_CONTEXT_LENGTH_EXCEEDED`, not retryable.-- Images are never stripped silently and never trigger a provider fallback.+- Images are never stripped silently, and a size refusal never triggers a+ provider fallback. A 503 from the visual gate or from the per-principal+ share (`visual_gate`, `visual_host_share`) is different: the proxy answers+ `provider_unavailable`, the Host classifies it as `LLM_MODEL_OVERLOADED`,+ retryable, and a Host with a fallback provider configured fails over on it.+ Whether that should stay retryable is tracked in #868.Desktop. The composer budget for `grok-subscription` is 16 MiB per image and16 MiB decoded in total, with no dimension bound. That is the shared rpc-proxy@@ -958,8 +965,12 @@ Grok annotations. A new control-api also republishes on boot.follows automatically through HCC and WRC.Image input (#784) on a deployment where the Grok flags are already on: roll-out `grok-llm-proxy` first, then control-api, then the four Host images, and-wait until every pod of each runs the new image before starting the next.+out `grok-llm-proxy` first, then control-api together with the control-plane+ConfigMap, then the four Host images, and wait until every pod of each runs+the new image before starting the next. With the ConfigMap, restart+`nginx-workflow-approval-gateway`: it mounts `nginx.conf` through `subPath`,+so it keeps the old authorize `client_max_body_size` (25165824) until its pods+are replaced.V2 has no version negotiation and no flag of its own: a new Host sends animage-bearing request as soon as it runs, and nothing tells it what thecontrol-api or the proxy behind it accepts. Each mixed-version pairing fails@@ -969,6 +980,7 @@ closed, and what the user sees is:| --- | --- | --- | --- || new Host, old control-api | V2 within the old route parser | refused at authorize with 400 `invalid_request`; no attempt row, nothing sent | "Connection Error" (`LLM_API_CALL_FAILED`, not retryable) || new Host, old control-api | V2 above the old route parser (24 MiB) | refused at authorize with 413 `payload_too_large` | "Conversation Too Long" (`LLM_CONTEXT_LENGTH_EXCEEDED`); shortening the text does not help |+| new Host, new control-api, gateway not restarted | V2 between 24 MiB and 35 MiB | refused by nginx with a 413 that carries no JSON code, before control-api; no attempt row, nothing sent | "Conversation Too Long" (the Host maps every authorize 413 to `payload_too_large`) || new Host, new control-api, old proxy | V2 within the old proxy parser | authorized (ticket and attempt row written), refused by the proxy with 400 `invalid_request`; one attempt consumed, nothing sent upstream | "Connection Error" || new Host, new control-api, old proxy | V2 above the old proxy parser (8 MiB) | authorized, refused by the proxy with 413 `payload_too_large` | "Conversation Too Long" || old Host, any control-api and proxy | V1 only | unchanged | nothing new |diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 5778fe896..7f183a0de 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.476",+ "version": "0.1.477","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.476",+ "version": "0.1.477","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex ece16c828..fc186a3e8 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.476",+ "version": "0.1.477","description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude","main": "dist/main.js","engines": {diff --git a/mcp-host/src/llm/imageSource.ts b/mcp-host/src/llm/imageSource.tsindex f8701845b..348240e64 100644--- a/mcp-host/src/llm/imageSource.ts+++ b/mcp-host/src/llm/imageSource.ts@@ -162,7 +162,8 @@ export function projectMessage(message: ChatMessage, invalidRequestCode: string)* cannot replace the message here: `size` covers the conversation bytes and the* image byte budgets alike (the Codex contract adds dimension budgets), and a* shorter conversation fixes the first and not the second. `count` covers- * `maxImages` in both contracts and `maxMessages` in the Codex one. So the+ * `maxImages` in both contracts, and `maxMessages` and `maxToolCalls` in the+ * Codex one. So the* message stays the discriminator at this boundary (#731). The byte pattern is* a prefix so it covers the `outside image data` check of a V2 request. The* element bound has its own explicit pattern.diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjsindex 04da75325..b4bb287d2 100644--- a/packages/grok-provider-attempt-contract/index.cjs+++ b/packages/grok-provider-attempt-contract/index.cjs@@ -213,7 +213,7 @@ const USAGE_KEYS = new Set(['inputTokens', 'outputTokens'])// `size` also marks the image budgets, and the message and tool-call counts// carry no kind although the Host treats them as context length. The Host// therefore classifies by message (CONTEXT_LENGTH_REFUSALS in-// mcp-host/src/llm/grokSubscription.ts).+// mcp-host/src/llm/imageSource.ts).function fail(code, message, kind) {return kind ? { ok: false, code, message, kind } : { ok: false, code, message }}