Skip to content

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.yaml
index 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_OPTIONS
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 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 control
routes keep the 10 MB ordinary JSON cap. The proxy's larger
parser 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; the
manifest leaves it unset so the proxy derives it from the contract cap plus the
envelope allowance.
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 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 the
authorized 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 about
five 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 with
out-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 aborted
the 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 by
about 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 and
16 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 an
image-bearing request as soon as it runs, and nothing tells it what the
control-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.json
index 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.json
index 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.ts
index 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.cjs
index 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 }
}