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.jsonindex 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.jsonindex 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.tsindex 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.messagediff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.mdindex 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 withthe refusal message: `hashCanonicalCodexRequest` returns`{ ok, code, message, kind }`, but `kind` cannot tell them apart from theimage 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.mdindex 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 andthe 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 therollout 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 MiBroute 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 revivingthe 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 bootstrapBinding slots are strict:diff --git a/docs/testing/grok-subscription-validation.md b/docs/testing/grok-subscription-validation.mdindex 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 onthe 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 thecomposer, and one tool screenshot close to 20 MiB decoded, the contract'sper-image limit, which only tool screenshots can reach;diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.cjsindex 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 }}