Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(grok-contract): mark byte-bound refusals kind:'size' and add the 35 MiB visual cap
Alfredo Lopeze45d45cf0f21
diff --git a/grok-llm-proxy/test/contractFreeze.test.ts b/grok-llm-proxy/test/contractFreeze.test.tsindex 900a78e03..8aa539339 100644--- a/grok-llm-proxy/test/contractFreeze.test.ts+++ b/grok-llm-proxy/test/contractFreeze.test.ts@@ -61,7 +61,9 @@ const SHARED_LIMIT_KEYS = [// `LIMITS` fails this suite until someone decides which. Publishing it takes// three edits: the fixture's `limits`, FIXTURE_LIMIT_KEYS and// SHARED_LIMIT_KEYS. Keeping it runtime-only takes one: add it here.-const RUNTIME_ONLY_LIMIT_KEYS = ['maxIdLength', 'maxNestingDepth'] as const+// maxVisualRequestBodyBytes stays here while the subscription endpoint is+// unmeasured for images: the fixture describes the measured upstream.+const RUNTIME_ONLY_LIMIT_KEYS = ['maxIdLength', 'maxNestingDepth', 'maxVisualRequestBodyBytes'] as consttype Fixture = {protocolVersion: stringdiff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjsindex 4e28175d6..797261241 100644--- a/packages/grok-provider-attempt-contract/index.cjs+++ b/packages/grok-provider-attempt-contract/index.cjs@@ -7,6 +7,7 @@*/const { createHash } = require('node:crypto')+const { MAX_ENCODED_TOTAL_IMAGE_BYTES } = require('./visualPayload.cjs')const SCHEMA_VERSION = 'grok-completion-request.v1'const RECEIPT_SCHEMA_VERSION = 'grok-attempt-receipt.v1'@@ -16,13 +17,23 @@ const TRANSPORT_PROTOCOL_VERSION = 'grok-subscription-transport.v1'const COMPLETIONS_ORIGIN = 'https://cli-chat-proxy.grok.com/v1/responses'const CATALOG_ORIGIN = 'https://cli-chat-proxy.grok.com/v1/models'+const MAX_REQUEST_BODY_BYTES = 8388608+const MIB = 1024 * 1024+const LIMITS = Object.freeze({// 8 MiB of serialized request (#731). A 1M-token window is about 4 MB of// text, and escaped JSON tool results cost 1.3-1.5x that, so this covers the// largest listed model window; past it the model refuses on tokens first.// It is a non-image cap, and the element bound in checkStructure follows// this value 1:1.- maxRequestBodyBytes: 8388608,+ maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,+ // V2 request/envelope ceiling: the whole image budget encoded as base64+ // (27962028 bytes) plus the non-image share, rounded up to a whole MiB,+ // which gives 36700160 (35 MiB). The rounding leaves more than+ // ENVELOPE_ALLOWANCE_BYTES of headroom, so a V2 envelope is bounded by this+ // value as a whole and gets no allowance on top, as in the Codex contract.+ maxVisualRequestBodyBytes:+ Math.ceil((MAX_ENCODED_TOTAL_IMAGE_BYTES + MAX_REQUEST_BODY_BYTES) / MIB) * MIB,maxMessages: 1024,// Bounds the `toolCalls` array of a single assistant message, independently// of how many definitions the request advertises. The 1:4 spread against@@ -118,8 +129,11 @@ const RECEIPT_KEYS = new Set([])const USAGE_KEYS = new Set(['inputTokens', 'outputTokens'])-function fail(code, message) {- return { ok: false, code, message }+// `kind` classifies a `limit` failure. The proxy and control-api answer+// `kind: 'size'` with payload_too_large and every other failure with+// invalid_request, so the field is set only where a byte budget refused.+function fail(code, message, kind) {+ return kind ? { ok: false, code, message, kind } : { ok: false, code, message }}function ok(value) {@@ -222,15 +236,15 @@ function checkStructure(value, maxDepth) {if (elements > LIMITS.maxRequestBodyBytes) {// Named distinctly from the byte measurement below, which refuses with// the bare `request exceeds maxRequestBodyBytes`. Both are `limit`- // failures and `fail()` carries no field beyond code and message, so the- // wording is the only thing that tells a user report which guard fired.+ // failures of `kind: 'size'`, so the wording is the only thing that+ // tells a user report which guard fired.// The remedy is the same for both - compaction - and the bound is reused// rather than given a constant of its own: every element serializes to// at least one byte, so a request of plain JSON data with more elements// than the byte cap cannot fit under it either (#731). A value that// JSON.stringify drops (a function, a symbol) is still counted here, so// for such input this bound can only refuse earlier, never later.- return fail('limit', 'request exceeds maxRequestBodyBytes element bound')+ return fail('limit', 'request exceeds maxRequestBodyBytes element bound', 'size')}for (const child of children) {if (child !== null && typeof child === 'object') stack.push(child, depth + 1)@@ -434,7 +448,7 @@ function parseGrokCompletionRequestV1(input) {// the Host labels it context length, although compaction shrinks only the// conversation and cannot bring such a request under the cap.if (encoded > LIMITS.maxRequestBodyBytes) {- return fail('limit', 'request exceeds maxRequestBodyBytes')+ return fail('limit', 'request exceeds maxRequestBodyBytes', 'size')}const extra = rejectUnknown(input, ROOT_KEYS, 'request')if (extra) return extradiff --git a/packages/grok-provider-attempt-contract/index.d.ts b/packages/grok-provider-attempt-contract/index.d.tsindex 5a2ffa50c..fc076f126 100644--- a/packages/grok-provider-attempt-contract/index.d.ts+++ b/packages/grok-provider-attempt-contract/index.d.ts@@ -15,7 +15,10 @@ export declare const COMPLETIONS_ORIGIN: 'https://cli-chat-proxy.grok.com/v1/resexport declare const CATALOG_ORIGIN: 'https://cli-chat-proxy.grok.com/v1/models'export declare const LIMITS: {+ /** V1 ceiling, and the V2 ceiling for everything that is not image data. */readonly maxRequestBodyBytes: 8388608+ /** V2 request/envelope ceiling; covers image payloads plus the non-image share. */+ readonly maxVisualRequestBodyBytes: 36700160readonly maxMessages: 1024readonly maxToolCalls: 256readonly maxOutputTokens: 16384@@ -33,9 +36,11 @@ export declare const LIMITS: {*/export declare const ENVELOPE_ALLOWANCE_BYTES: 16384+export type ContractLimitKind = 'size'+export type ContractResult<T> =| { ok: true; value: T }- | { ok: false; code: string; message: string }+ | { ok: false; code: string; message: string; kind?: ContractLimitKind }export type GrokMessageRole = 'system' | 'user' | 'assistant' | 'tool'diff --git a/packages/grok-provider-attempt-contract/visualPayload.cjs b/packages/grok-provider-attempt-contract/visualPayload.cjsnew file mode 100644index 000000000..664075208--- /dev/null+++ b/packages/grok-provider-attempt-contract/visualPayload.cjs@@ -0,0 +1,30 @@+'use strict'++/**+ * Image budget for grok-completion-request.v2.+ *+ * The numbers come from the xAI documentation for api.x.ai/v1 (read+ * 2026-09-23): at most 20 MiB per image, jpg/jpeg and png only, no+ * image-count limit. The per-request budget of 20 images and 20 MiB decoded+ * in total is a local product decision. The subscription endpoint+ * cli-chat-proxy.grok.com/v1/responses is UNMEASURED for images: these limits+ * are not an upstream capability fact for it.+ *+ * There is no dimension or pixel limit. Dimensions are read only to validate+ * the container.+ */++const GROK_VISUAL_LIMITS = Object.freeze({+ maxImages: 20,+ maxImageBytes: 20971520,+ maxTotalImageBytes: 20971520,+})++// Encoded length of the whole decoded image budget as canonical base64. The+// contract sizes the V2 envelope from it.+const MAX_ENCODED_TOTAL_IMAGE_BYTES = 4 * Math.ceil(GROK_VISUAL_LIMITS.maxTotalImageBytes / 3)++module.exports = {+ GROK_VISUAL_LIMITS,+ MAX_ENCODED_TOTAL_IMAGE_BYTES,+}