Skip to content

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

TypeScript

feat(grok-contract): add grok-completion-request.v2 with jpeg/png image parts

Alfredo Lopez5a5c261ef019
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index 797261241..e2736b4cf 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -7,9 +7,14 @@
*/
const { createHash } = require('node:crypto')
-const { MAX_ENCODED_TOTAL_IMAGE_BYTES } = require('./visualPayload.cjs')
+const {
+ GROK_VISUAL_LIMITS,
+ MAX_ENCODED_TOTAL_IMAGE_BYTES,
+ inspectVisualImage,
+} = require('./visualPayload.cjs')
const SCHEMA_VERSION = 'grok-completion-request.v1'
+const SCHEMA_VERSION_V2 = 'grok-completion-request.v2'
const RECEIPT_SCHEMA_VERSION = 'grok-attempt-receipt.v1'
const PROVIDER_ID = 'grok-subscription'
const TICKET_TYP = 'grok-execution-ticket'
@@ -99,6 +104,26 @@ const TOOL_CALL_KEYS = new Set(['id', 'name', 'arguments'])
const TOOL_KEYS = new Set(['name', 'description', 'parameters'])
const GENERATION_KEYS = new Set(['temperature', 'maxOutputTokens', 'toolChoice'])
const HINT_KEYS = new Set(['promptCacheKey'])
+
+/**
+ * V2 (grok-completion-request.v2) adds typed visual parts to user messages.
+ * The root field set is deliberately the same closed set as V1: V2 must not
+ * become a looser schema at the root.
+ */
+const MESSAGE_KEYS_V2 = new Set([
+ 'role',
+ 'content',
+ 'contentParts',
+ 'name',
+ 'toolCallId',
+ 'toolCalls',
+])
+const CONTENT_PART_TEXT_KEYS = new Set(['type', 'text'])
+const CONTENT_PART_IMAGE_KEYS = new Set(['type', 'mimeType', 'data', 'source'])
+const IMAGE_SOURCE_ATTACHMENT_KEYS = new Set(['kind', 'attachmentId', 'messageId'])
+const IMAGE_SOURCE_TOOL_KEYS = new Set(['kind', 'attachmentId', 'toolCallId'])
+const ENVELOPE_KEYS = new Set(['executionTicket', 'requestHash', 'request'])
+
const CLAIMS_KEYS = new Set([
'jti',
'typ',
@@ -131,7 +156,8 @@ 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, so the field is set only where a byte budget refused.
+// invalid_request, so `size` is set only where a byte budget refused. The V2
+// image count sets `count`; the other count and range bounds carry no kind.
function fail(code, message, kind) {
return kind ? { ok: false, code, message, kind } : { ok: false, code, message }
}
@@ -195,6 +221,96 @@ function unknownKeys(obj, allowed) {
return Object.keys(obj).filter(k => !allowed.has(k))
}
+/**
+ * Request/envelope byte ceiling for a schema version. V2 raises the ceiling so
+ * a body can carry image payloads; every other value keeps the V1 ceiling, so a
+ * missing, unknown or lower version can never buy the larger budget.
+ */
+function schemaRequestBodyLimit(schemaVersion) {
+ return schemaVersion === SCHEMA_VERSION_V2
+ ? LIMITS.maxVisualRequestBodyBytes
+ : LIMITS.maxRequestBodyBytes
+}
+
+/**
+ * Ceiling for a request body, or for the envelope that carries it, BEFORE
+ * parsing. Callers that must size an HTTP body — the client, the authorizer and
+ * the proxy — only have the declared document at that point, so this keys off
+ * the declaration and falls back to the V1 ceiling for anything else.
+ */
+function requestBodyLimitBytes(request) {
+ return schemaRequestBodyLimit(isPlainObject(request) ? request.schemaVersion : undefined)
+}
+
+/**
+ * UTF-8 length of a request with every image payload replaced by an empty
+ * string: the caller-controlled text/tool share of the body.
+ *
+ * V2's larger ceiling exists for image data only, so this share stays on the V1
+ * budget and declaring V2 never buys 35 MiB of text or tool definitions. The
+ * measurement builds a detached shadow — the input's key order, shallow copies,
+ * only image `data` blanked — measures it and discards it. The original
+ * request, its hash and its projection are never touched, so this cannot change
+ * what is authorized or signed.
+ */
+function blankImagePayloadsInMessages(messages) {
+ if (!Array.isArray(messages)) return messages
+ return messages.map(message => {
+ const parts = isPlainObject(message) ? message.contentParts : undefined
+ if (!Array.isArray(parts)) return message
+ return {
+ ...message,
+ contentParts: parts.map(part =>
+ isPlainObject(part) && part.type === 'image' ? { ...part, data: '' } : part
+ ),
+ }
+ })
+}
+
+function measureNonImageRequestBytes(input) {
+ return Buffer.byteLength(
+ JSON.stringify({ ...input, messages: blankImagePayloadsInMessages(input.messages) }),
+ 'utf8'
+ )
+}
+
+/**
+ * Authorize JSON is a different document from a Grok request or proxy
+ * envelope. `requestBodyLimitBytes(body.request)` still gates the whole
+ * wrapper (35 MiB only when the nested request declares V2). This helper
+ * blanks image payloads inside `body.request` so wrapper fields — ids,
+ * hashes, ticket links — stay on the `maxRequestBodyBytes` non-image budget.
+ */
+function measureNonImageAuthorizeBytes(body) {
+ if (!isPlainObject(body)) {
+ return Buffer.byteLength(JSON.stringify(body ?? null), 'utf8')
+ }
+ const request = body.request
+ if (!isPlainObject(request)) {
+ return Buffer.byteLength(JSON.stringify(body), 'utf8')
+ }
+ return Buffer.byteLength(
+ JSON.stringify({
+ ...body,
+ request: { ...request, messages: blankImagePayloadsInMessages(request.messages) },
+ }),
+ 'utf8'
+ )
+}
+
+/**
+ * Proxy completion JSON includes `executionTicket`, which authorize never
+ * measured. Blank images and drop the ticket so a body that sat under the
+ * `maxRequestBodyBytes` authorize budget is not 413'd on redeem by ~1 KB of JWT.
+ */
+function measureNonImageCompletionBytes(body) {
+ if (!isPlainObject(body)) {
+ return measureNonImageAuthorizeBytes(body)
+ }
+ const { executionTicket: _executionTicket, ...rest } = body
+ return measureNonImageAuthorizeBytes(rest)
+}
+
function isBoundedId(value) {
return typeof value === 'string' && ID_PATTERN.test(value)
}
@@ -285,7 +401,7 @@ function assertFiniteTree(value, label, depth = 1) {
return null
}
-function parseMessages(raw) {
+function parseMessages(raw, messageKeys, visualBudget) {
if (!Array.isArray(raw) || raw.length === 0) {
return fail('invalid', 'messages must be a non-empty array')
}
@@ -296,7 +412,7 @@ function parseMessages(raw) {
for (let i = 0; i < raw.length; i++) {
const item = raw[i]
if (!isPlainObject(item)) return fail('invalid', `messages[${i}] must be an object`)
- const extra = rejectUnknown(item, MESSAGE_KEYS, `messages[${i}]`)
+ const extra = rejectUnknown(item, messageKeys, `messages[${i}]`)
if (extra) return extra
if (!MESSAGE_ROLES.has(item.role)) return fail('invalid', `messages[${i}].role is not allowed`)
if (typeof item.content !== 'string')
@@ -347,6 +463,21 @@ function parseMessages(raw) {
}
message.toolCalls = toolCalls
}
+ if (item.contentParts !== undefined) {
+ if (item.role !== 'user') {
+ return fail('invalid', `messages[${i}].contentParts is only allowed on user`)
+ }
+ const parts = parseContentParts(
+ item.contentParts,
+ `messages[${i}].contentParts`,
+ visualBudget
+ )
+ if (!parts.ok) return parts
+ if (parts.value.text !== item.content) {
+ return fail('invalid', `messages[${i}].content must equal the text parts joined by '\\n'`)
+ }
+ message.contentParts = parts.value.parts
+ }
messages.push(message)
}
return ok(messages)
@@ -431,12 +562,13 @@ function parseTransportHints(raw) {
return ok({ promptCacheKey: raw.promptCacheKey })
}
-function parseGrokCompletionRequestV1(input) {
+function parseGrokCompletionRequestRoot(input, schemaVersion, messageKeys) {
if (!isPlainObject(input)) return fail('invalid', 'request must be an object')
// Runs before JSON.stringify: a deeply nested body would otherwise throw a
// RangeError out of the parser instead of failing closed.
const structure = checkStructure(input, MAX_REQUEST_DEPTH)
if (structure) return structure
+ const visualSchema = schemaVersion === SCHEMA_VERSION_V2
let encoded
try {
encoded = Buffer.byteLength(JSON.stringify(input), 'utf8')
@@ -447,20 +579,29 @@ function parseGrokCompletionRequestV1(input) {
// tool catalog that alone exceeds the cap is refused with this message and
// 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', 'size')
+ if (encoded > schemaRequestBodyLimit(schemaVersion)) {
+ return fail(
+ 'limit',
+ visualSchema
+ ? 'request exceeds maxVisualRequestBodyBytes'
+ : 'request exceeds maxRequestBodyBytes',
+ 'size'
+ )
+ }
+ if (visualSchema && measureNonImageRequestBytes(input) > LIMITS.maxRequestBodyBytes) {
+ return fail('limit', 'request exceeds maxRequestBodyBytes outside image data', 'size')
}
const extra = rejectUnknown(input, ROOT_KEYS, 'request')
if (extra) return extra
- if (input.schemaVersion !== SCHEMA_VERSION) {
- return fail('invalid', 'schemaVersion is not grok-completion-request.v1')
+ if (input.schemaVersion !== schemaVersion) {
+ return fail('invalid', `schemaVersion is not ${schemaVersion}`)
}
if (!isBoundedId(input.requestId)) return fail('invalid', 'requestId is invalid')
if (!isBoundedId(input.idempotencyKey)) return fail('invalid', 'idempotencyKey is invalid')
if (input.provider !== PROVIDER_ID) return fail('invalid', 'provider must be grok-subscription')
if (!isBoundedId(input.model)) return fail('invalid', 'model is invalid')
- const messages = parseMessages(input.messages)
+ const messages = parseMessages(input.messages, messageKeys, { images: 0, totalBytes: 0 })
if (!messages.ok) return messages
const tools = parseTools(input.tools)
if (!tools.ok) return tools
@@ -485,7 +626,7 @@ function parseGrokCompletionRequestV1(input) {
}
const projected = {
- schemaVersion: SCHEMA_VERSION,
+ schemaVersion,
requestId: input.requestId,
idempotencyKey: input.idempotencyKey,
provider: PROVIDER_ID,
@@ -499,18 +640,194 @@ function parseGrokCompletionRequestV1(input) {
return ok(Object.freeze(projected))
}
+function parseGrokCompletionRequestV1(input) {
+ return parseGrokCompletionRequestRoot(input, SCHEMA_VERSION, MESSAGE_KEYS)
+}
+
function hashGrokCompletionRequestV1(request) {
return createHash('sha256').update(stableStringify(request)).digest('hex')
}
+/**
+ * Minimal image provenance for V2. Closed union: an attachment that arrived
+ * with a user message, or one produced by a tool call. It is hashed with the
+ * rest of the part and never becomes model text, and the proxy never sends it
+ * upstream. Identifiers use the bounded ID pattern, as in the Codex contract.
+ */
+function parseImageSource(raw, label) {
+ if (!isPlainObject(raw)) return fail('invalid', `${label} must be an object`)
+ if (raw.kind !== 'attachment' && raw.kind !== 'tool') {
+ return fail('invalid', `${label}.kind is not allowed`)
+ }
+ const fromAttachment = raw.kind === 'attachment'
+ const extra = rejectUnknown(
+ raw,
+ fromAttachment ? IMAGE_SOURCE_ATTACHMENT_KEYS : IMAGE_SOURCE_TOOL_KEYS,
+ label
+ )
+ if (extra) return extra
+ if (!isBoundedId(raw.attachmentId)) return fail('invalid', `${label}.attachmentId is invalid`)
+ const ownerKey = fromAttachment ? 'messageId' : 'toolCallId'
+ if (!isBoundedId(raw[ownerKey])) return fail('invalid', `${label}.${ownerKey} is invalid`)
+ if (fromAttachment) {
+ return ok({ kind: 'attachment', attachmentId: raw.attachmentId, messageId: raw.messageId })
+ }
+ return ok({ kind: 'tool', attachmentId: raw.attachmentId, toolCallId: raw.toolCallId })
+}
+
+/**
+ * Ordered content parts. Order is significant and preserved verbatim; nothing
+ * is merged, reordered or dropped. Text parts must agree with the message
+ * `content` string, so the textual projection and the part projection cannot
+ * contradict each other. Parts are optional and may be text-only (a compacted
+ * message that no longer carries an image is valid); images are bounded by
+ * count, per-image bytes and total bytes. There is no dimension or pixel
+ * budget.
+ */
+function parseContentParts(raw, label, visualBudget) {
+ if (!Array.isArray(raw) || raw.length === 0) {
+ return fail('invalid', `${label} must be a non-empty array`)
+ }
+ const parts = []
+ const textBits = []
+ for (let i = 0; i < raw.length; i++) {
+ const part = raw[i]
+ const partLabel = `${label}[${i}]`
+ if (!isPlainObject(part)) return fail('invalid', `${partLabel} must be an object`)
+ if (part.type === 'text') {
+ const extra = rejectUnknown(part, CONTENT_PART_TEXT_KEYS, partLabel)
+ if (extra) return extra
+ if (typeof part.text !== 'string') {
+ return fail('invalid', `${partLabel}.text must be a string`)
+ }
+ parts.push({ type: 'text', text: part.text })
+ textBits.push(part.text)
+ continue
+ }
+ if (part.type === 'image') {
+ const extra = rejectUnknown(part, CONTENT_PART_IMAGE_KEYS, partLabel)
+ if (extra) return extra
+ if (part.mimeType !== 'image/jpeg' && part.mimeType !== 'image/png') {
+ return fail('invalid', `${partLabel}.mimeType is not allowed`)
+ }
+ const source = parseImageSource(part.source, `${partLabel}.source`)
+ if (!source.ok) return source
+ const image = inspectVisualImage({ mimeType: part.mimeType, data: part.data })
+ if (!image.ok) return fail(image.code, `${partLabel}: ${image.message}`, image.kind)
+ // Request-scoped budgets: history can carry more messages than one, so a
+ // per-message counter would let a request exceed the declared limits.
+ visualBudget.images += 1
+ if (visualBudget.images > GROK_VISUAL_LIMITS.maxImages) {
+ return fail('limit', `request exceeds ${GROK_VISUAL_LIMITS.maxImages} images`, 'count')
+ }
+ visualBudget.totalBytes += image.value.bytes
+ if (visualBudget.totalBytes > GROK_VISUAL_LIMITS.maxTotalImageBytes) {
+ return fail(
+ 'limit',
+ `request exceeds ${GROK_VISUAL_LIMITS.maxTotalImageBytes} total image bytes`,
+ 'size'
+ )
+ }
+ parts.push({
+ type: 'image',
+ mimeType: part.mimeType,
+ data: part.data,
+ source: source.value,
+ })
+ continue
+ }
+ return fail('invalid', `${partLabel}.type is not allowed`)
+ }
+ return ok({ parts, text: textBits.join('\n') })
+}
+
+/**
+ * V2 root: the shared root parser with the V2 schema version and the message
+ * field set that additionally allows `contentParts`.
+ */
+function parseGrokCompletionRequestV2(input) {
+ return parseGrokCompletionRequestRoot(input, SCHEMA_VERSION_V2, MESSAGE_KEYS_V2)
+}
+
+/**
+ * Single dispatcher for every supported version. It only selects the version
+ * and defers all validation to that version's parser, so an unknown or missing
+ * schemaVersion fails closed instead of falling through to a loose path.
+ */
+function parseGrokCompletionRequest(input) {
+ if (!isPlainObject(input)) return fail('invalid', 'request must be an object')
+ if (input.schemaVersion === SCHEMA_VERSION) return parseGrokCompletionRequestV1(input)
+ if (input.schemaVersion === SCHEMA_VERSION_V2) return parseGrokCompletionRequestV2(input)
+ return fail(
+ 'invalid',
+ 'schemaVersion must be grok-completion-request.v1 or grok-completion-request.v2'
+ )
+}
+
+function hashGrokCompletionRequest(request) {
+ return createHash('sha256').update(stableStringify(request)).digest('hex')
+}
+
+/**
+ * Exact proxy request envelope shared by the authorizer and the proxy.
+ *
+ * The outer `deadlineMs` is never emitted: a V2 request carries its deadline in
+ * `request.deadlineMs`, already bound by the request hash, and a caller must
+ * not be able to add an independent deadline after the envelope was measured.
+ *
+ * The returned envelope is re-parsed and re-hashed here, so it cannot carry a
+ * request the contract rejects or a hash that disagrees with the request it
+ * carries. Its exact UTF-8 byte length (JSON.stringify minus whitespace, the
+ * same serialization the transport sends) must fit the ceiling of the schema it
+ * carries — `requestBodyLimitBytes(request)`, i.e. 35 MiB for V2 and 8 MiB
+ * otherwise. A deployment that lowers the proxy's visual body limit below the
+ * contract limit is not covered by this measurement.
+ *
+ * The request inside the envelope already passed the V2 non-image budget, so
+ * the V2 headroom here can only be spent by the ticket and the digest the
+ * authorizer produced; a caller cannot reach this ceiling with text.
+ */
+function buildGrokProxyEnvelope(input) {
+ if (!isPlainObject(input)) return fail('invalid', 'proxy envelope must be an object')
+ const extra = rejectUnknown(input, ENVELOPE_KEYS, 'proxy envelope')
+ if (extra) return extra
+ const ticket = input.executionTicket
+ if (typeof ticket !== 'string' || ticket.length < 8 || /[\p{Cc}\p{Cs}]/u.test(ticket)) {
+ return fail('invalid', 'executionTicket is invalid')
+ }
+ if (typeof input.requestHash !== 'string' || !SHA256_HEX.test(input.requestHash)) {
+ return fail('invalid', 'requestHash must be a SHA-256 hex digest')
+ }
+ const parsed = parseGrokCompletionRequest(input.request)
+ if (!parsed.ok) return parsed
+ const requestHash = hashGrokCompletionRequest(parsed.value)
+ if (requestHash !== input.requestHash) {
+ return fail('request_hash_mismatch', 'requestHash does not match the request')
+ }
+ const envelope = { executionTicket: ticket, requestHash, request: parsed.value }
+ const visualSchema = parsed.value.schemaVersion === SCHEMA_VERSION_V2
+ const encoded = Buffer.byteLength(JSON.stringify(envelope), 'utf8')
+ if (encoded > requestBodyLimitBytes(parsed.value)) {
+ return fail(
+ 'limit',
+ visualSchema
+ ? 'proxy envelope exceeds maxVisualRequestBodyBytes'
+ : 'proxy envelope exceeds maxRequestBodyBytes',
+ 'size'
+ )
+ }
+ return ok(Object.freeze(envelope))
+}
+
/**
* Client-side canonical hashing. Serializes `raw` exactly as a JSON peer
- * receives it, parses that wire form with parseGrokCompletionRequestV1, and
- * hashes the validated projection — the same steps control-api authorize and
- * grok-llm-proxy perform. Callers send `value.request` with
+ * receives it, parses that wire form with parseGrokCompletionRequest (v1 or
+ * v2), and hashes the validated projection — the same steps control-api
+ * authorize and grok-llm-proxy perform. Callers send `value.request` with
* `value.requestHash`, so shapes the parser normalizes away (empty
* generation/tools/transportHints, undefined leaves) cannot make the two ends
- * disagree. Never throws; invalid input fails closed.
+ * disagree. For an already well-formed request the digest is identical to
+ * hashGrokCompletionRequest(request). Never throws; invalid input fails closed.
*/
function hashCanonicalGrokRequest(raw) {
if (!isPlainObject(raw)) return fail('invalid', 'request must be an object')
@@ -522,12 +839,12 @@ function hashCanonicalGrokRequest(raw) {
} catch {
return fail('invalid', 'request is not JSON-serializable')
}
- const parsed = parseGrokCompletionRequestV1(wire)
+ const parsed = parseGrokCompletionRequest(wire)
if (!parsed.ok) return parsed
return ok(
Object.freeze({
request: parsed.value,
- requestHash: hashGrokCompletionRequestV1(parsed.value),
+ requestHash: hashGrokCompletionRequest(parsed.value),
})
)
}
@@ -699,18 +1016,27 @@ function parseGrokAttemptReceiptV1(input) {
module.exports = {
SCHEMA_VERSION,
+ SCHEMA_VERSION_V2,
RECEIPT_SCHEMA_VERSION,
PROVIDER_ID,
TICKET_TYP,
LIMITS,
+ GROK_VISUAL_LIMITS,
ENVELOPE_ALLOWANCE_BYTES,
TRANSPORT_PROTOCOL_VERSION,
COMPLETIONS_ORIGIN,
CATALOG_ORIGIN,
stableStringify,
+ requestBodyLimitBytes,
+ measureNonImageAuthorizeBytes,
+ measureNonImageCompletionBytes,
parseGrokCompletionRequestV1,
+ parseGrokCompletionRequestV2,
+ parseGrokCompletionRequest,
hashGrokCompletionRequestV1,
+ hashGrokCompletionRequest,
hashCanonicalGrokRequest,
+ buildGrokProxyEnvelope,
computeGrokPolicyHash,
parseGrokExecutionTicketClaims,
parseAuthorizeAttemptResponse,
diff --git a/packages/grok-provider-attempt-contract/index.d.ts b/packages/grok-provider-attempt-contract/index.d.ts
index fc076f126..3b3c12d80 100644
--- a/packages/grok-provider-attempt-contract/index.d.ts
+++ b/packages/grok-provider-attempt-contract/index.d.ts
@@ -7,6 +7,12 @@
*/
export declare const SCHEMA_VERSION: 'grok-completion-request.v1'
+/**
+ * V2 adds typed visual parts (`contentParts` on user messages). V2 shares the
+ * V1 root field set; its body ceiling is `LIMITS.maxVisualRequestBodyBytes`,
+ * and the non-image share of the body stays on `LIMITS.maxRequestBodyBytes`.
+ */
+export declare const SCHEMA_VERSION_V2: 'grok-completion-request.v2'
export declare const RECEIPT_SCHEMA_VERSION: 'grok-attempt-receipt.v1'
export declare const PROVIDER_ID: 'grok-subscription'
export declare const TICKET_TYP: 'grok-execution-ticket'
@@ -36,7 +42,23 @@ export declare const LIMITS: {
*/
export declare const ENVELOPE_ALLOWANCE_BYTES: 16384
-export type ContractLimitKind = 'size'
+/**
+ * Budgets for V2 image parts, from the xAI documentation for api.x.ai/v1
+ * (20 MiB per image; the 20-image, 20 MiB per-request budget is a local
+ * product decision). cli-chat-proxy.grok.com/v1/responses is unmeasured for
+ * images. There is no dimension or pixel limit.
+ */
+export declare const GROK_VISUAL_LIMITS: {
+ readonly maxImages: 20
+ readonly maxImageBytes: 20971520
+ readonly maxTotalImageBytes: 20971520
+}
+
+/**
+ * `size`: a byte budget refused (payload_too_large). `count`: the V2 image
+ * count refused. Every other failure carries no kind.
+ */
+export type ContractLimitKind = 'size' | 'count'
export type ContractResult<T> =
| { ok: true; value: T }
@@ -58,6 +80,46 @@ export interface GrokMessageV1 {
toolCalls?: GrokAssistantToolCallV1[]
}
+export interface GrokMessagePartTextV2 {
+ type: 'text'
+ text: string
+}
+
+/**
+ * Minimal provenance for a V2 image part. Closed union: an attachment that
+ * arrived with a user message, or one produced by a tool call. It is hashed
+ * with the rest of the part, never becomes model text and is never sent
+ * upstream.
+ */
+export type GrokImageSourceV2 =
+ | { kind: 'attachment'; attachmentId: string; messageId: string }
+ | { kind: 'tool'; attachmentId: string; toolCallId: string }
+
+export interface GrokMessagePartImageV2 {
+ type: 'image'
+ mimeType: 'image/jpeg' | 'image/png'
+ /** Strict canonical base64 of a structurally valid PNG/JPEG container. */
+ data: string
+ source: GrokImageSourceV2
+}
+
+export type GrokMessagePartV2 = GrokMessagePartTextV2 | GrokMessagePartImageV2
+
+/**
+ * V2 message. `contentParts` is optional and only allowed on user messages.
+ * When present, the text parts joined with `\n` must equal `content`
+ * (an image-only message therefore carries `content: ''`). A parts array may
+ * be text-only after compaction.
+ */
+export interface GrokMessageV2 {
+ role: GrokMessageRole
+ content: string
+ contentParts?: GrokMessagePartV2[]
+ name?: string
+ toolCallId?: string
+ toolCalls?: GrokAssistantToolCallV1[]
+}
+
export interface GrokToolDefinitionV1 {
name: string
description: string
@@ -89,6 +151,32 @@ export interface GrokCompletionRequestV1 {
transportHints?: GrokTransportHintsV1
}
+export interface GrokCompletionRequestV2 {
+ schemaVersion: 'grok-completion-request.v2'
+ requestId: string
+ idempotencyKey: string
+ provider: 'grok-subscription'
+ model: string
+ messages: GrokMessageV2[]
+ tools?: GrokToolDefinitionV1[]
+ generation?: GrokGenerationOptionsV1
+ deadlineMs?: number
+ transportHints?: GrokTransportHintsV1
+}
+
+export type GrokCompletionRequest = GrokCompletionRequestV1 | GrokCompletionRequestV2
+
+/**
+ * Exact body the control-api authorizer hands to the Grok proxy. The outer
+ * `deadlineMs` is never emitted: a V2 request carries its deadline in
+ * `request.deadlineMs`, already bound by the request hash.
+ */
+export interface GrokProxyEnvelope {
+ executionTicket: string
+ requestHash: string
+ request: GrokCompletionRequest
+}
+
export type GrokExecutionTicketClaims = {
jti: string
typ: 'grok-execution-ticket'
@@ -144,19 +232,54 @@ export type GrokAttemptReceiptV1 = {
}
export declare function stableStringify(value: unknown): string
+/**
+ * Byte ceiling for a request body, or for the envelope that carries it, applied
+ * BEFORE parsing: 35 MiB for a document that declares
+ * `grok-completion-request.v2`, `maxRequestBodyBytes` (8 MiB) for anything
+ * else. Declaring V2 does not raise the budget for text or tool definitions —
+ * the parser measures the body with every image payload blanked and keeps that
+ * share on the `maxRequestBodyBytes` ceiling.
+ */
+export declare function requestBodyLimitBytes(request: unknown): number
+/**
+ * Byte length of an authorize document after every image payload inside
+ * `body.request` is blanked. Wrapper fields stay on the non-image budget
+ * even when the nested request declares V2.
+ */
+export declare function measureNonImageAuthorizeBytes(body: unknown): number
+/**
+ * Byte length of a proxy completion document after image payloads inside
+ * `body.request` are blanked and `executionTicket` is omitted. The ticket is
+ * issued after authorize, so it must not consume the non-image budget
+ * that authorize already applied to the pre-ticket wrapper.
+ */
+export declare function measureNonImageCompletionBytes(body: unknown): number
export declare function parseGrokCompletionRequestV1(
input: unknown
): ContractResult<GrokCompletionRequestV1>
+export declare function parseGrokCompletionRequestV2(
+ input: unknown
+): ContractResult<GrokCompletionRequestV2>
+export declare function parseGrokCompletionRequest(
+ input: unknown
+): ContractResult<GrokCompletionRequest>
export declare function hashGrokCompletionRequestV1(request: GrokCompletionRequestV1): string
+export declare function hashGrokCompletionRequest(request: GrokCompletionRequest): string
/**
- * Canonical client hash: JSON wire round-trip, parseGrokCompletionRequestV1,
- * then hashGrokCompletionRequestV1 of the projection. Send `request` together
- * with `requestHash`. Never throws; invalid input returns `{ ok: false }`.
+ * Canonical client hash: JSON wire round-trip, parseGrokCompletionRequest
+ * (v1 or v2), then hashGrokCompletionRequest of the projection. Send
+ * `request` together with `requestHash`. Never throws; invalid input returns
+ * `{ ok: false }`.
*/
export declare function hashCanonicalGrokRequest(raw: unknown): ContractResult<{
- request: GrokCompletionRequestV1
+ request: GrokCompletionRequest
requestHash: string
}>
+export declare function buildGrokProxyEnvelope(input: {
+ executionTicket: string
+ requestHash: string
+ request: GrokCompletionRequest
+}): ContractResult<GrokProxyEnvelope>
export declare function computeGrokPolicyHash(input: {
model: string
catalogRevision: number
diff --git a/packages/grok-provider-attempt-contract/visualPayload.cjs b/packages/grok-provider-attempt-contract/visualPayload.cjs
index 664075208..dd01355d8 100644
--- a/packages/grok-provider-attempt-contract/visualPayload.cjs
+++ b/packages/grok-provider-attempt-contract/visualPayload.cjs
@@ -1,7 +1,14 @@
'use strict'
/**
- * Image budget for grok-completion-request.v2.
+ * Bounded visual-payload validation for grok-completion-request.v2.
+ *
+ * Guarantee, stated narrowly on purpose: this module proves base64
+ * canonicality, byte budgets, JPEG/PNG container framing, required header and
+ * terminator blocks, and the dimensions declared by those headers. It does not
+ * decode pixels, verify PNG CRCs, validate entropy-coded JPEG data, or prove
+ * that the image renders. "Valid" here means "syntactically well-formed
+ * container inside the local budget", never "decoded and visually correct".
*
* 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
@@ -12,6 +19,11 @@
*
* There is no dimension or pixel limit. Dimensions are read only to validate
* the container.
+ *
+ * The decoder and the container readers are a copy of the Codex contract's
+ * visualPayload.cjs, kept separate so this package never imports the Codex
+ * one. index.test.cjs requires identical verdicts from both copies on images
+ * inside both budgets.
*/
const GROK_VISUAL_LIMITS = Object.freeze({
@@ -20,11 +32,178 @@ const GROK_VISUAL_LIMITS = Object.freeze({
maxTotalImageBytes: 20971520,
})
+// Exact encoded length of a canonical base64 string that decodes to
+// maxImageBytes octets. Compared before any decoding work happens.
+const MAX_ENCODED_IMAGE_BYTES = 4 * Math.ceil(GROK_VISUAL_LIMITS.maxImageBytes / 3)
+
// 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)
+const BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+const PNG_IHDR = 'IHDR'
+const PNG_IDAT = 'IDAT'
+const PNG_IEND = 'IEND'
+
+// SOF0..SOF15 except DHT (0xC4), JPG (0xC8) and DAC (0xCC), which reuse the
+// same marker range without carrying frame dimensions.
+const JPEG_SOF_MARKERS = new Set([
+ 0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+])
+const JPEG_SOI = 0xd8
+const JPEG_EOI = 0xd9
+const JPEG_SOS = 0xda
+const JPEG_TEM = 0x01
+
+function fail(code, message, kind) {
+ return kind ? { ok: false, code, message, kind } : { ok: false, code, message }
+}
+
+function ok(value) {
+ return { ok: true, value }
+}
+
+/**
+ * Strict canonical base64. Length is bounded before `Buffer.from`, invalid
+ * alphabets and padding placement are rejected, and a decode/encode round trip
+ * rejects non-canonical trailing bits that a lenient decoder would accept.
+ */
+function decodeStrictBase64(data, maxDecodedBytes) {
+ if (typeof data !== 'string') return fail('invalid', 'image data must be a base64 string')
+ if (data.length === 0) return fail('invalid', 'image data must not be empty')
+ if (data.length > MAX_ENCODED_IMAGE_BYTES) {
+ return fail('limit', `image exceeds ${maxDecodedBytes} decoded bytes`, 'size')
+ }
+ if (data.length % 4 !== 0) return fail('invalid', 'image data must be canonical base64')
+ if (!BASE64_PATTERN.test(data)) return fail('invalid', 'image data must be canonical base64')
+ const bytes = Buffer.from(data, 'base64')
+ if (bytes.length === 0) return fail('invalid', 'image data must not be empty')
+ if (bytes.length > maxDecodedBytes) {
+ return fail('limit', `image exceeds ${maxDecodedBytes} decoded bytes`, 'size')
+ }
+ if (bytes.toString('base64') !== data) {
+ return fail('invalid', 'image data must be canonical base64')
+ }
+ return ok(bytes)
+}
+
+function readPngDimensions(buffer) {
+ const length = buffer.length
+ if (length < 8 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+ return fail('invalid', 'PNG signature is missing')
+ }
+ let pos = 8
+ let header = null
+ let sawImageData = false
+ let sawEnd = false
+ while (pos < length) {
+ if (pos + 8 > length) return fail('invalid', 'PNG chunk header is truncated')
+ const chunkLength = buffer.readUInt32BE(pos)
+ const type = buffer.toString('latin1', pos + 4, pos + 8)
+ if (pos + 12 + chunkLength > length) return fail('invalid', 'PNG chunk is truncated')
+ if (header === null) {
+ if (type !== PNG_IHDR || chunkLength !== 13) {
+ return fail('invalid', 'PNG first chunk must be a 13-byte IHDR')
+ }
+ const width = buffer.readUInt32BE(pos + 8)
+ const height = buffer.readUInt32BE(pos + 12)
+ if (width < 1 || height < 1) return fail('invalid', 'PNG dimensions must be positive')
+ header = { width, height }
+ } else if (type === PNG_IHDR) {
+ return fail('invalid', 'PNG repeats IHDR')
+ }
+ if (type === PNG_IDAT) sawImageData = true
+ if (type === PNG_IEND) {
+ if (chunkLength !== 0) return fail('invalid', 'PNG IEND must be empty')
+ if (pos + 12 !== length) return fail('invalid', 'PNG IEND must be the last chunk')
+ sawEnd = true
+ break
+ }
+ pos += 12 + chunkLength
+ }
+ // IHDR alone (or signature-only) is header-only pretending: the container
+ // must also carry image data and terminate.
+ if (header === null) return fail('invalid', 'PNG has no IHDR')
+ if (!sawImageData) return fail('invalid', 'PNG has no IDAT image data')
+ if (!sawEnd) return fail('invalid', 'PNG has no IEND terminator')
+ return ok(header)
+}
+
+function readJpegDimensions(buffer) {
+ const length = buffer.length
+ if (length < 4 || buffer[0] !== 0xff || buffer[1] !== JPEG_SOI) {
+ return fail('invalid', 'JPEG SOI marker is missing')
+ }
+ if (buffer[length - 2] !== 0xff || buffer[length - 1] !== JPEG_EOI) {
+ return fail('invalid', 'JPEG EOI marker is missing')
+ }
+ let pos = 2
+ let frame = null
+ let scanEnd = -1
+ while (pos < length) {
+ if (buffer[pos] !== 0xff) return fail('invalid', 'JPEG marker framing is malformed')
+ while (pos < length && buffer[pos] === 0xff) pos += 1
+ if (pos >= length) return fail('invalid', 'JPEG marker is truncated')
+ const marker = buffer[pos]
+ pos += 1
+ if (marker === 0x00) return fail('invalid', 'JPEG marker framing is malformed')
+ if (marker === JPEG_EOI) break
+ if (marker === JPEG_SOI) return fail('invalid', 'JPEG repeats SOI')
+ if (marker === JPEG_TEM || (marker >= 0xd0 && marker <= 0xd7)) continue
+ if (pos + 2 > length) return fail('invalid', 'JPEG segment length is truncated')
+ const segmentLength = buffer.readUInt16BE(pos)
+ if (segmentLength < 2 || pos + segmentLength > length) {
+ return fail('invalid', 'JPEG segment is truncated')
+ }
+ if (JPEG_SOF_MARKERS.has(marker)) {
+ if (segmentLength < 8) return fail('invalid', 'JPEG frame header is truncated')
+ const height = buffer.readUInt16BE(pos + 3)
+ const width = buffer.readUInt16BE(pos + 5)
+ if (width < 1 || height < 1) return fail('invalid', 'JPEG dimensions must be positive')
+ frame = { width, height }
+ }
+ if (marker === JPEG_SOS) {
+ scanEnd = pos + segmentLength
+ break
+ }
+ pos += segmentLength
+ }
+ // Frame header plus scan header plus at least one entropy-coded byte: a
+ // header-only file must not pass as an image.
+ if (frame === null) return fail('invalid', 'JPEG has no frame header')
+ if (scanEnd < 0) return fail('invalid', 'JPEG has no start-of-scan segment')
+ if (scanEnd >= length - 2) return fail('invalid', 'JPEG has no entropy-coded image data')
+ return ok(frame)
+}
+
+/**
+ * Per-image gate: MIME, strict base64, octet budget and container framing.
+ * Aggregate image count and total bytes stay with the caller because they
+ * span the complete request, including history messages.
+ */
+function inspectVisualImage(input) {
+ if (input.mimeType !== 'image/jpeg' && input.mimeType !== 'image/png') {
+ return fail('invalid', 'image mimeType is not allowed')
+ }
+ const decoded = decodeStrictBase64(input.data, GROK_VISUAL_LIMITS.maxImageBytes)
+ if (!decoded.ok) return decoded
+ const dimensions =
+ input.mimeType === 'image/png'
+ ? readPngDimensions(decoded.value)
+ : readJpegDimensions(decoded.value)
+ if (!dimensions.ok) return dimensions
+ return ok({
+ bytes: decoded.value.length,
+ width: dimensions.value.width,
+ height: dimensions.value.height,
+ })
+}
+
module.exports = {
GROK_VISUAL_LIMITS,
+ MAX_ENCODED_IMAGE_BYTES,
MAX_ENCODED_TOTAL_IMAGE_BYTES,
+ decodeStrictBase64,
+ inspectVisualImage,
}