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.cjsindex 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 extraif (!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_V2let encodedtry {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 messagesconst 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 parsedreturn 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.tsindex 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: stringdescription: 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: stringtyp: '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): numberexport 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: GrokCompletionRequestrequestHash: string}>+export declare function buildGrokProxyEnvelope(input: {+ executionTicket: string+ requestHash: string+ request: GrokCompletionRequest+}): ContractResult<GrokProxyEnvelope>export declare function computeGrokPolicyHash(input: {model: stringcatalogRevision: numberdiff --git a/packages/grok-provider-attempt-contract/visualPayload.cjs b/packages/grok-provider-attempt-contract/visualPayload.cjsindex 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,}