Skip to content

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

TypeScript

docs(grok): correct the limit kind comments, the classification paragraph and the rollout notes

Alfredo Lopez2d51642db35d
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 7ef3d48ad..15465495b 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.652",
+ "version": "0.1.653",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.652",
+ "version": "0.1.653",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index 74a6b4932..99dedcfef 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.652",
+ "version": "0.1.653",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/services/llmProviderAttemptAuthorizer.ts b/control-api/src/services/llmProviderAttemptAuthorizer.ts
index 22767cf7a..c98c1151d 100644
--- a/control-api/src/services/llmProviderAttemptAuthorizer.ts
+++ b/control-api/src/services/llmProviderAttemptAuthorizer.ts
@@ -309,7 +309,10 @@ async function authorizeGrokProviderAttempt(
assertClaimBinding(body, claims)
const parsed = parseGrokCompletionRequest(body.request)
if (!parsed.ok) {
- // `kind: 'size'` is 413: byte ceilings. Range, count and depth stay 400.
+ // `kind: 'size'` is 413: the byte budgets and the container, member and
+ // element bounds. Every other refusal is 400, including the image count
+ // (`kind: 'count'`) and the message, tool-call, depth and range bounds
+ // (no kind).
throw new LlmProviderAttemptAuthorizeError(
parsed.code === 'limit' && parsed.kind === 'size' ? 'payload_too_large' : 'invalid_request',
parsed.message
@@ -715,7 +718,9 @@ export async function authorizeLlmProviderAttempt(
const parsed = parseCodexCompletionRequest(body.request)
if (!parsed.ok) {
- // `kind: 'size'` is 413: byte ceilings and image geometry. Range, count and depth stay 400.
+ // `kind: 'size'` is 413: the byte budgets, the image geometry and the
+ // container, member and element bounds. `range`, `count` and `depth`
+ // stay 400.
throw new LlmProviderAttemptAuthorizeError(
parsed.code === 'limit' && parsed.kind === 'size' ? 'payload_too_large' : 'invalid_request',
parsed.message
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 3202d3c03..cc6bd6298 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -643,8 +643,8 @@ code the proxy constructs, and every code it refuses a request with
the refusal message: `hashCanonicalCodexRequest` returns
`{ ok, code, message, kind }`, but `kind` cannot tell them apart from the
image budgets, because `size` covers the conversation bytes and the image
- byte and dimension budgets alike, and `count` covers `maxMessages` and
- `maxImages` alike.
+ byte and dimension budgets alike, and `count` covers `maxMessages`,
+ `maxToolCalls` and `maxImages` alike.
| Refusal message | Guard |
| -------------------------------------------------------- | --------------------------------- |
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 0d4418610..def07ab63 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -360,13 +360,13 @@ sees depends on where the rejection happens: the control-api authorizer and
the proxy both surface a size refusal (`kind: 'size'`) as HTTP 413
`payload_too_large` and every other parser failure as `invalid_request`
(#784; the control-api authorizer answered `invalid_request` for size too
-before it), while the Host raises `request_limit_exceeded` before it
-authorizes at all — for the five size refusals listed under that code below —
-`attachment_too_large` for the image budget refusals (classified as
-`InvalidAttachment`), `request_limit_exceeded` for the element bound and
-`payload_too_large` for the container and member bounds (all three
-classified as `ContextLengthExceeded`), and
-`invalid_request` for the rest, which no amount of compaction would fix.
+before it), while the Host, before it authorizes at all, raises
+`request_limit_exceeded` for the five volume refusals listed under that code
+below (the element bound among them), `attachment_too_large` for the image
+budget refusals (classified as `InvalidAttachment`), `payload_too_large` for
+the container and member bounds (classified, like `request_limit_exceeded`,
+as `ContextLengthExceeded`), and `invalid_request` for the rest, which no
+amount of compaction would fix.
That symmetry holds for a request and not for a response, which is why the
rollout order below is not interchangeable. A proxy carrying the new bound in
@@ -939,10 +939,15 @@ of its own, so a new Host sends an image-bearing request as soon as it runs.
An old control-api refuses it (400 `invalid_request`, or 413 above its 24 MiB
route parser), and an old proxy refuses it after the attempt was authorized
(400 `invalid_request`, or 413 above its 8 MiB parser, which the user sees as
-"Conversation Too Long"). Step 4's Host-before-proxy rule comes from a change
-of the V1 bounds; #784 leaves them unchanged (8 MiB body, 256 tool calls,
-1024 messages), so it does not apply to this upgrade. On a fresh rollout the
-flags stay off until step 6, and steps 1-6 apply as written.
+"Conversation Too Long"). Step 4's Host-before-proxy rule protects a
+response-side bound, `maxToolCalls`, whose band a new proxy would bill and an
+old Host would discard. #784 leaves `maxToolCalls` (256) unchanged, so the rule
+does not apply to this upgrade. #784 does tighten request-side V1 bounds: it
+adds `maxRequestContainers` and `maxRequestMembers` (262144 each) and lowers
+the element bound from 8388608 to `maxRequestElements` (1048576). A request
+over them is refused by control-api at authorize or by the proxy before
+redeem, so no upstream call is made and nothing is billed. On a fresh rollout
+the flags stay off until step 6, and steps 1-6 apply as written.
## Rollback order
@@ -970,6 +975,18 @@ flags stay off until step 6, and steps 1-6 apply as written.
code path. That attempt fails on the unique key index instead of reviving
the key.
+Image input (#784) alone, with the Grok flags left on: roll back the four Host
+images first and wait until no Host pod runs a #784 image, then roll back
+`grok-llm-proxy` and control-api — the upgrade order reversed. V2 has no flag
+of its own, so a #784 Host keeps sending image-bearing V2 requests; an older
+control-api refuses them at authorize (400 `invalid_request`, or 413 above its
+24 MiB route parser) and an older proxy refuses them after the attempt was
+authorized (400 `invalid_request`, or 413 above its 8 MiB parser). With the
+Hosts rolled back first only V1 requests remain, and the older control-api and
+proxy accept every V1 request the newer ones accept, since their structural
+bounds are looser. Steps 1-4 above do not apply: the flags stay on and #784
+adds no migration.
+
## SDK bootstrap
Binding slots are strict:
diff --git a/docs/testing/grok-subscription-validation.md b/docs/testing/grok-subscription-validation.md
index b7856323b..42ad9a1d4 100644
--- a/docs/testing/grok-subscription-validation.md
+++ b/docs/testing/grok-subscription-validation.md
@@ -50,10 +50,13 @@ images; the filename and the prompt must not carry the answer.
2. JPEG challenge. The same with a JPEG.
3. Order. One user message of text, image, text, where the answer depends on
the order (for example: "the code in the image, then the word after it").
-4. Limits. Each case in a new conversation. The image budget (20 images,
- 20 MiB decoded) covers every image in the request's history, so a case run
- after another in the same conversation carries the earlier images and can
- be refused on the total instead of on its own image:
+4. Limits. The image budget (20 images, 20 MiB decoded) is checked per
+ request, and a request carries the images of the current user message plus
+ every tool screenshot taken earlier in the same turn. Earlier turns are
+ rebuilt as text (`buildMessageHistory` in
+ `mcp-host/src/core/conversation/conversation.ts`), so a case never carries
+ a previous case's images. Keep each case to one turn that adds only its own
+ images:
- one image padded close to the ingress cap of 16 MiB decoded from the
composer, and one tool screenshot close to 20 MiB decoded, the contract's
per-image limit, which only tool screenshots can reach;
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index dc5c90bb7..26b13eb7d 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.466",
+ "version": "0.1.467",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.466",
+ "version": "0.1.467",
"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 120460319..23c13306d 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.466",
+ "version": "0.1.467",
"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/codexSubscription.ts b/mcp-host/src/llm/codexSubscription.ts
index 6c8fc31e6..47359c900 100644
--- a/mcp-host/src/llm/codexSubscription.ts
+++ b/mcp-host/src/llm/codexSubscription.ts
@@ -746,8 +746,9 @@ export class CodexSubscriptionProvider implements SingleTurnProvider {
}
: {}),
}
- // V1 stays byte-identical for every text-only turn; one message with parts
- // moves the whole request to V2, which is the only version that carries them.
+ // V1 stays byte-identical for a turn with no contentParts. One message with
+ // parts, even text-only parts left by redaction, moves the whole request to
+ // V2, the only version that carries them.
if (!projectedMessages.some(message => message.contentParts !== undefined)) {
return { schemaVersion: 'codex-completion-request.v1', ...base }
}
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
index 5b981370a..d07b82886 100644
--- a/mcp-host/src/llm/grokSubscription.ts
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -752,8 +752,9 @@ export class GrokSubscriptionProvider implements SingleTurnProvider {
: {}),
}
}
- // V1 stays byte-identical for every text-only turn; one message with parts
- // moves the whole request to V2, which is the only version that carries them.
+ // V1 stays byte-identical for a turn with no contentParts. One message with
+ // parts, even text-only parts left by redaction, moves the whole request to
+ // V2, the only version that carries them.
if (!projectedMessages.some(message => message.contentParts !== undefined)) {
return { schemaVersion: 'grok-completion-request.v1', ...request }
}
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index c871b08be..5eb69fdcb 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -199,12 +199,20 @@ const RECEIPT_KEYS = new Set([
])
const USAGE_KEYS = new Set(['inputTokens', 'outputTokens'])
-// `kind` classifies a `limit` failure. The proxy and control-api answer
-// `kind: 'size'` with payload_too_large and every other failure with
-// invalid_request. `size` covers the byte budget and the aggregate structural
-// counts (containers, members, elements) that a shorter conversation can fix.
-// The V2 image count sets `count`; depth and other range bounds carry no kind
-// because compaction cannot fix them.
+// `kind` classifies a `limit` failure; no other code carries one. The proxy
+// and control-api answer `kind: 'size'` with payload_too_large and every
+// other failure, with or without a kind, with invalid_request.
+// - `size`: the byte budgets (the whole request, the V2 non-image share, the
+// proxy envelope, each image's decoded bytes, the total image bytes) and
+// the container, member and element bounds.
+// - `count`: the V2 image count.
+// - no kind: nesting depth, the message and tool-call counts, and the
+// maxOutputTokens and deadlineMs ranges.
+// A kind decides the HTTP answer, not whether compaction can fix the refusal:
+// `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).
function fail(code, message, kind) {
return kind ? { ok: false, code, message, kind } : { ok: false, code, message }
}