Skip to content

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.ts
index 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 const
type Fixture = {
protocolVersion: string
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index 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 extra
diff --git a/packages/grok-provider-attempt-contract/index.d.ts b/packages/grok-provider-attempt-contract/index.d.ts
index 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/res
export 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: 36700160
readonly maxMessages: 1024
readonly maxToolCalls: 256
readonly 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.cjs
new file mode 100644
index 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,
+}