Skip to content

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

TypeScript

test(grok-contract): specify V2 image parts, limits, envelope and Codex parity

Alfredo Lopezdb4c8bfbafac
diff --git a/packages/grok-provider-attempt-contract/fixtures/canonical-request-hashes.v2.json b/packages/grok-provider-attempt-contract/fixtures/canonical-request-hashes.v2.json
new file mode 100644
index 000000000..8bb0008f7
--- /dev/null
+++ b/packages/grok-provider-attempt-contract/fixtures/canonical-request-hashes.v2.json
@@ -0,0 +1,736 @@
+{
+ "schemaVersion": "grok-completion-request.v2",
+ "notes": "Grok twin of the Codex V2 corpus: same shapes, same refusal messages. SHA-256 over the validated V2 projection using the same lexicographic stableStringify as V1. Array order (messages, contentParts, toolCalls) is significant. Image parts carry `dataRef` (resolved by index.test.cjs from fixtures/visual-requests.json, whose imageSha256 pins the same bytes); `mutate` applies a documented truncation. The frozen request digest therefore pins those bytes transitively.",
+ "cases": [
+ {
+ "name": "text-only-v2",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-text",
+ "idempotencyKey": "idem-req-v2-text",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "hello"
+ }
+ ]
+ },
+ "sha256": "9f1ec10fd58b8f4a269b4305b912fd413d659ff27765fa38b5589e3b6fdaf0f2"
+ },
+ {
+ "name": "text-and-png-attachment",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-png",
+ "idempotencyKey": "idem-req-v2-png",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "Describe the attached image",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "Describe the attached image"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "sha256": "a0a2bbb6f510fe8db3cb07c35b5a32dca9b288f908f171c7bae8666b47f3d751"
+ },
+ {
+ "name": "image-only-jpeg-tool-source",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-jpeg",
+ "idempotencyKey": "idem-req-v2-jpeg",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "",
+ "contentParts": [
+ {
+ "type": "image",
+ "mimeType": "image/jpeg",
+ "dataRef": "jpeg",
+ "source": {
+ "kind": "tool",
+ "attachmentId": "att_1700000000001_ff00aa11",
+ "toolCallId": "call_abc123"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "sha256": "5b95f2d72a2023bbe96e6c207f3e17e9b655550925dcc8dba376bad12ccdaee6"
+ },
+ {
+ "name": "text-only-parts-after-compaction",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-compacted",
+ "idempotencyKey": "idem-req-v2-compacted",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "first line\nsecond line",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "first line"
+ },
+ {
+ "type": "text",
+ "text": "second line"
+ }
+ ]
+ }
+ ]
+ },
+ "sha256": "bdddacaa83c109288eb0421494b875d65c7e5e83974dc9119dc03fc981d8fe5b"
+ },
+ {
+ "name": "multi-image-order-significant",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-multi",
+ "idempotencyKey": "idem-req-v2-multi",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "compare",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "compare"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ },
+ {
+ "type": "image",
+ "mimeType": "image/jpeg",
+ "dataRef": "jpeg",
+ "source": {
+ "kind": "tool",
+ "attachmentId": "att_1700000000001_ff00aa11",
+ "toolCallId": "call_abc123"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "distinctRequest": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-multi",
+ "idempotencyKey": "idem-req-v2-multi",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "compare",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "compare"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/jpeg",
+ "dataRef": "jpeg",
+ "source": {
+ "kind": "tool",
+ "attachmentId": "att_1700000000001_ff00aa11",
+ "toolCallId": "call_abc123"
+ }
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "sha256": "10014afbfaecae00b7d81e6e3364e120a9169b1082a7c8604c39a7b97aae826c"
+ },
+ {
+ "name": "source-identity-is-hashed",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-png",
+ "idempotencyKey": "idem-req-v2-png",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "Describe the attached image",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "Describe the attached image"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "distinctRequest": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-png",
+ "idempotencyKey": "idem-req-v2-png",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "Describe the attached image",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "Describe the attached image"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-2"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "sha256": "a0a2bbb6f510fe8db3cb07c35b5a32dca9b288f908f171c7bae8666b47f3d751"
+ }
+ ],
+ "rejects": [
+ {
+ "name": "content-parts-contradict-content",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r1",
+ "idempotencyKey": "idem-req-v2-r1",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "different text",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "actual text"
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].content must equal the text parts joined by '\\n'"
+ },
+ {
+ "name": "content-parts-join-uses-newline",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r2",
+ "idempotencyKey": "idem-req-v2-r2",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "ab",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "a"
+ },
+ {
+ "type": "text",
+ "text": "b"
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].content must equal the text parts joined by '\\n'"
+ },
+ {
+ "name": "content-parts-empty-array",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r3",
+ "idempotencyKey": "idem-req-v2-r3",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "",
+ "contentParts": []
+ }
+ ]
+ },
+ "message": "messages[0].contentParts must be a non-empty array"
+ },
+ {
+ "name": "content-parts-on-assistant",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r4",
+ "idempotencyKey": "idem-req-v2-r4",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "assistant",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts is only allowed on user"
+ },
+ {
+ "name": "image-only-with-nonempty-content",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r5",
+ "idempotencyKey": "idem-req-v2-r5",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "hi",
+ "contentParts": [
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].content must equal the text parts joined by '\\n'"
+ },
+ {
+ "name": "unknown-part-type",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r6",
+ "idempotencyKey": "idem-req-v2-r6",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "audio",
+ "text": "x"
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[0].type is not allowed"
+ },
+ {
+ "name": "unknown-part-field",
+ "reason": "unknown-field",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r7",
+ "idempotencyKey": "idem-req-v2-r7",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x",
+ "extra": 1
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[0] rejects field 'extra'"
+ },
+ {
+ "name": "image-mime-not-allowed",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r8",
+ "idempotencyKey": "idem-req-v2-r8",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/webp",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1].mimeType is not allowed"
+ },
+ {
+ "name": "image-data-not-canonical-base64",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r9",
+ "idempotencyKey": "idem-req-v2-r9",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "data": "iVBORw0KGgo",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1]: image data must be canonical base64"
+ },
+ {
+ "name": "png-signature-only",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r10",
+ "idempotencyKey": "idem-req-v2-r10",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "data": "iVBORw0KGgo=",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1]: PNG has no IHDR"
+ },
+ {
+ "name": "png-ihdr-only-truncated",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r11",
+ "idempotencyKey": "idem-req-v2-r11",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "mutate": "truncate-after-ihdr",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1]: PNG has no IDAT image data"
+ },
+ {
+ "name": "jpeg-eoi-missing",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r12",
+ "idempotencyKey": "idem-req-v2-r12",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/jpeg",
+ "dataRef": "jpeg",
+ "mutate": "strip-eoi",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1]: JPEG EOI marker is missing"
+ },
+ {
+ "name": "image-missing-source",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r13",
+ "idempotencyKey": "idem-req-v2-r13",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png"
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1].source must be an object"
+ },
+ {
+ "name": "image-source-unknown-kind",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r14",
+ "idempotencyKey": "idem-req-v2-r14",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "web",
+ "attachmentId": "a1",
+ "messageId": "m1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1].source.kind is not allowed"
+ },
+ {
+ "name": "image-source-extra-field",
+ "reason": "unknown-field",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r15",
+ "idempotencyKey": "idem-req-v2-r15",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "a1",
+ "messageId": "m1",
+ "toolCallId": "t1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1].source rejects field 'toolCallId'"
+ },
+ {
+ "name": "image-source-id-too-long",
+ "reason": "invalid",
+ "request": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-r16",
+ "idempotencyKey": "idem-req-v2-r16",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "x",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "x"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "dataRef": "png",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ "messageId": "m1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "message": "messages[0].contentParts[1].source.attachmentId is invalid"
+ }
+ ]
+}
diff --git a/packages/grok-provider-attempt-contract/fixtures/visual-requests.json b/packages/grok-provider-attempt-contract/fixtures/visual-requests.json
new file mode 100644
index 000000000..f66de7537
--- /dev/null
+++ b/packages/grok-provider-attempt-contract/fixtures/visual-requests.json
@@ -0,0 +1,97 @@
+{
+ "schemaVersion": "grok-completion-request.v2",
+ "notes": "Reusable Grok V2 requests carrying the same real, decodable 2x2 images and inline base64 as the Codex contract fixture (packages/llm-provider-attempt-contract/fixtures/visual-requests.json); imageSha256 pins the same octets. PNG: 2x2 RGB truecolor built with zlib.deflateSync and real CRCs (75 bytes). JPEG: 2x2 baseline (834 bytes). The contract validates framing and headers only and does not claim full decode.",
+ "imageSha256": {
+ "png": "becbba8bdf9d37f1628e1f6f587111a4a29d7e5b730582e77d518ddb00bebd8e",
+ "jpeg": "0e6db313e0bb29c0ed8937efd0c833eec96e15f5da4449640201783286cf8e1a"
+ },
+ "expectedDimensions": {
+ "png": {
+ "width": 2,
+ "height": 2
+ },
+ "jpeg": {
+ "width": 2,
+ "height": 2
+ }
+ },
+ "png": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-png",
+ "idempotencyKey": "idem-req-v2-png",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "Describe the attached image",
+ "contentParts": [
+ {
+ "type": "text",
+ "text": "Describe the attached image"
+ },
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "data": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAEklEQVR42mP4z8DAwAAi/gMJABvyA/23MHTXAAAAAElFTkSuQmCC",
+ "source": {
+ "kind": "attachment",
+ "attachmentId": "att_1700000000000_ab12cd34",
+ "messageId": "msg-1"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "jpeg": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-jpeg",
+ "idempotencyKey": "idem-req-v2-jpeg",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "",
+ "contentParts": [
+ {
+ "type": "image",
+ "mimeType": "image/jpeg",
+ "data": "/9j/4AAQSkZJRgABAQAASABIAAD/4QBMRXhpZgAATU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAAD/7QA4UGhvdG9zaG9wIDMuMAA4QklNBAQAAAAAAAA4QklNBCUAAAAAABDUHYzZjwCyBOmACZjs+EJ+/8AAEQgAAgACAwEiAAIRAQMRAf/EAB8AAAEFAQEBAQEBAAAAAAAAAAABAgMEBQYHCAkKC//EALUQAAIBAwMCBAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNicoIJChYXGBkaJSYnKCkqNDU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6g4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2drh4uPk5ebn6Onq8fLz9PX29/j5+v/EAB8BAAMBAQEBAQEBAQEAAAAAAAABAgMEBQYHCAkKC//EALURAAIBAgQEAwQHBQQEAAECdwABAgMRBAUhMQYSQVEHYXETIjKBCBRCkaGxwQkjM1LwFWJy0QoWJDThJfEXGBkaJicoKSo1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoKDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uLj5OXm5+jp6vLz9PX29/j5+v/bAEMAAgICAgICAwICAwUDAwMFBgUFBQUGCAYGBgYGCAoICAgICAgKCgoKCgoKCgwMDAwMDA4ODg4ODw8PDw8PDw8PD//bAEMBAgICBAQEBwQEBxALCQsQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEP/dAAQAAf/aAAwDAQACEQMRAD8A+BtH0fSLvSLG7u7GCaeaCJ5JHiVnd2UFmZiMkk8knrWl/wAI/oH/AEDbb/vyn+FHh7/kAab/ANe0P/oArXr+qD+1D//Z",
+ "source": {
+ "kind": "tool",
+ "attachmentId": "att_1700000000001_ff00aa11",
+ "toolCallId": "call_abc123"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ "pngImageOnly": {
+ "schemaVersion": "grok-completion-request.v2",
+ "requestId": "req-v2-png-only",
+ "idempotencyKey": "idem-req-v2-png-only",
+ "provider": "grok-subscription",
+ "model": "grok-4.6",
+ "messages": [
+ {
+ "role": "user",
+ "content": "",
+ "contentParts": [
+ {
+ "type": "image",
+ "mimeType": "image/png",
+ "data": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAEklEQVR42mP4z8DAwAAi/gMJABvyA/23MHTXAAAAAElFTkSuQmCC",
+ "source": {
+ "kind": "tool",
+ "attachmentId": "att_1700000000001_ff00aa11",
+ "toolCallId": "call_abc123"
+ }
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/packages/grok-provider-attempt-contract/index.test.cjs b/packages/grok-provider-attempt-contract/index.test.cjs
index 5b53aeb57..92a69f07f 100644
--- a/packages/grok-provider-attempt-contract/index.test.cjs
+++ b/packages/grok-provider-attempt-contract/index.test.cjs
@@ -1,10 +1,23 @@
'use strict'
const assert = require('node:assert/strict')
+const crypto = require('node:crypto')
const fs = require('node:fs')
const path = require('node:path')
const test = require('node:test')
const contract = require('./index.cjs')
+const visualPayload = require('./visualPayload.cjs')
+// Test-only: the Codex contract is the reference the V2 messages and the image
+// validator copy must stay identical to. Production code never imports it.
+const codexContract = require('../llm-provider-attempt-contract/index.cjs')
+const codexVisualPayload = require('../llm-provider-attempt-contract/visualPayload.cjs')
+const {
+ declaredHeaderPng,
+ declaredHeaderPngOfSize,
+ jpegOfSize,
+ realPng,
+ realPngOfSize,
+} = require('../llm-provider-attempt-contract/testImageFixtures.cjs')
const BASE = {
schemaVersion: 'grok-completion-request.v1',
@@ -80,6 +93,12 @@ test('exports the 16 KiB envelope allowance with a matching declared literal', (
test('does not import Codex LIMITS or Codex provider id', () => {
const src = fs.readFileSync(path.join(__dirname, 'index.cjs'), 'utf8')
assert.equal(src.includes("require('../llm-provider-attempt-contract"), false)
+ // The image validator is a copy with Grok limits, not a re-export of the
+ // Codex one. Witness: the file exists and holds its own decoder.
+ const visualSrc = fs.readFileSync(path.join(__dirname, 'visualPayload.cjs'), 'utf8')
+ assert.match(visualSrc, /function decodeStrictBase64\(/)
+ assert.equal(visualSrc.includes('llm-provider-attempt-contract'), false)
+ assert.equal(visualSrc.includes(['chatgpt', 'com'].join('.')), false)
assert.equal(contract.PROVIDER_ID, 'grok-subscription')
assert.equal(contract.TICKET_TYP, 'grok-execution-ticket')
assert.equal(contract.LIMITS.maxToolCalls, 256)
@@ -605,3 +624,643 @@ test('message count is bounded at maxMessages', () => {
if (!parsed.ok) assert.equal(parsed.message, 'messages exceed 1024')
}
})
+
+// ---------------------------------------------------------------------------
+// V2 (grok-completion-request.v2): user image parts. The structure mirrors the
+// Codex V2 contract; the limits are Grok's (xAI documentation for api.x.ai/v1:
+// 20 MiB per image, jpeg/png only; 20 images and 20 MiB per request is a local
+// product decision). There is no dimension or pixel limit.
+// ---------------------------------------------------------------------------
+
+const MIB = 1024 * 1024
+const FIXTURE_V2 = JSON.parse(
+ fs.readFileSync(path.join(__dirname, 'fixtures/canonical-request-hashes.v2.json'), 'utf8')
+)
+const VISUAL_FIXTURE = JSON.parse(
+ fs.readFileSync(path.join(__dirname, 'fixtures/visual-requests.json'), 'utf8')
+)
+const CODEX_VISUAL_FIXTURE = JSON.parse(
+ fs.readFileSync(
+ path.join(__dirname, '../llm-provider-attempt-contract/fixtures/visual-requests.json'),
+ 'utf8'
+ )
+)
+const IMAGE_DATA = {
+ png: VISUAL_FIXTURE.png.messages[0].contentParts.find(part => part.type === 'image').data,
+ jpeg: VISUAL_FIXTURE.jpeg.messages[0].contentParts.find(part => part.type === 'image').data,
+}
+
+/**
+ * Fixture image parts carry `dataRef` (resolved from visual-requests.json) and
+ * `mutate` for documented truncations, as in the Codex corpus. Resolution
+ * returns a deep copy: a loaded fixture is never mutated in place.
+ */
+function resolveFixtureImages(value) {
+ if (Array.isArray(value)) return value.map(resolveFixtureImages)
+ if (value && typeof value === 'object') {
+ if (typeof value.dataRef === 'string') {
+ const source = IMAGE_DATA[value.dataRef]
+ assert.ok(source, `unknown image ref ${value.dataRef}`)
+ const bytes = Buffer.from(source, 'base64')
+ let data = source
+ if (value.mutate === 'strip-eoi') data = bytes.subarray(0, bytes.length - 2).toString('base64')
+ else if (value.mutate === 'truncate-after-ihdr') data = bytes.subarray(0, 33).toString('base64')
+ else assert.equal(value.mutate, undefined, `unknown mutate ${value.mutate}`)
+ const clone = { ...value, data }
+ delete clone.dataRef
+ delete clone.mutate
+ return clone
+ }
+ const out = {}
+ for (const [key, inner] of Object.entries(value)) out[key] = resolveFixtureImages(inner)
+ return out
+ }
+ return value
+}
+
+function imagePart(data, mimeType = 'image/png') {
+ return {
+ type: 'image',
+ mimeType,
+ data,
+ source: { kind: 'tool', attachmentId: 'att_1700000000001_ff00aa11', toolCallId: 'call_abc123' },
+ }
+}
+
+function v2WithMessages(messages) {
+ return { ...BASE, schemaVersion: 'grok-completion-request.v2', messages }
+}
+
+function v2WithParts(parts, content = '') {
+ return v2WithMessages([{ role: 'user', content, contentParts: parts }])
+}
+
+function v2TextRequest(content) {
+ return v2WithMessages([{ role: 'user', content }])
+}
+
+/** The same request shape, addressed to the Codex contract. */
+function asCodex(request) {
+ return {
+ ...request,
+ schemaVersion: request.schemaVersion.replace('grok-', 'codex-'),
+ provider: 'codex-subscription',
+ }
+}
+
+const V2_EXPORTS = [
+ 'SCHEMA_VERSION_V2',
+ 'GROK_VISUAL_LIMITS',
+ 'requestBodyLimitBytes',
+ 'measureNonImageAuthorizeBytes',
+ 'measureNonImageCompletionBytes',
+ 'parseGrokCompletionRequestV2',
+ 'parseGrokCompletionRequest',
+ 'hashGrokCompletionRequest',
+ 'buildGrokProxyEnvelope',
+]
+
+test('v2 exports: every V2 name exists at runtime and in index.d.ts', () => {
+ const declarations = fs.readFileSync(path.join(__dirname, 'index.d.ts'), 'utf8')
+ const declared = new Set(
+ Array.from(
+ declarations.matchAll(/export declare (?:const|function)\s+([A-Za-z0-9_]+)/g),
+ m => m[1]
+ )
+ )
+ for (const name of V2_EXPORTS) {
+ assert.ok(name in contract, `runtime export ${name}`)
+ assert.ok(declared.has(name), `declared export ${name}`)
+ }
+ assert.equal(contract.SCHEMA_VERSION_V2, 'grok-completion-request.v2')
+ assert.match(
+ declarations,
+ /export declare const SCHEMA_VERSION_V2: 'grok-completion-request\.v2'/
+ )
+ assert.match(declarations, /export type ContractLimitKind = 'size' \| 'count'/)
+})
+
+test('GROK_VISUAL_LIMITS: 20 images, 20 MiB per image, 20 MiB total, no dimension or pixel key', () => {
+ assert.deepEqual(
+ { ...contract.GROK_VISUAL_LIMITS },
+ { maxImages: 20, maxImageBytes: 20971520, maxTotalImageBytes: 20971520 }
+ )
+ assert.equal(contract.GROK_VISUAL_LIMITS, visualPayload.GROK_VISUAL_LIMITS)
+ assert.equal(Object.isFrozen(contract.GROK_VISUAL_LIMITS), true)
+ assert.equal(visualPayload.MAX_ENCODED_IMAGE_BYTES, 4 * Math.ceil(20971520 / 3))
+ const declarations = fs.readFileSync(path.join(__dirname, 'index.d.ts'), 'utf8')
+ const block = declarations.match(/export declare const GROK_VISUAL_LIMITS: \{([\s\S]*?)\n\}/)
+ assert.ok(block, 'index.d.ts must declare a GROK_VISUAL_LIMITS object literal')
+ const members = block[1]
+ .replace(/\/\*[\s\S]*?\*\//g, '')
+ .replace(/\/\/.*$/gm, '')
+ .split('\n')
+ .map(line => line.trim())
+ .filter(line => line !== '')
+ const declared = Object.fromEntries(
+ members.map(line => {
+ const m = /^readonly ([A-Za-z0-9_]+): (\d+)$/.exec(line)
+ assert.ok(m, `GROK_VISUAL_LIMITS member must be "readonly <name>: <integer>": ${line}`)
+ return [m[1], Number(m[2])]
+ })
+ )
+ assert.deepEqual(declared, { ...contract.GROK_VISUAL_LIMITS })
+})
+
+test('v2 fixture corpus: valid cases match frozen digests and distinct payloads differ', () => {
+ assert.equal(FIXTURE_V2.cases.length, 6)
+ for (const fixture of FIXTURE_V2.cases) {
+ const request = resolveFixtureImages(fixture.request)
+ const parsed = contract.parseGrokCompletionRequest(request)
+ assert.equal(parsed.ok, true, `${fixture.name}: ${parsed.message}`)
+ const direct = contract.parseGrokCompletionRequestV2(request)
+ assert.deepEqual(parsed, direct, `${fixture.name} dispatcher parity`)
+ const digest = contract.hashGrokCompletionRequest(parsed.value)
+ assert.equal(digest, fixture.sha256, fixture.name)
+ const canonical = contract.hashCanonicalGrokRequest(request)
+ assert.equal(canonical.ok, true, fixture.name)
+ assert.equal(canonical.value.requestHash, fixture.sha256, `${fixture.name} canonical`)
+ if (fixture.distinctRequest) {
+ const other = contract.parseGrokCompletionRequest(
+ resolveFixtureImages(fixture.distinctRequest)
+ )
+ assert.equal(other.ok, true, `${fixture.name} distinct`)
+ assert.notEqual(contract.hashGrokCompletionRequest(other.value), digest, fixture.name)
+ }
+ }
+})
+
+test('v2 fixture corpus: rejected payloads fail closed with the frozen code and message', () => {
+ assert.equal(FIXTURE_V2.rejects.length, 16)
+ for (const fixture of FIXTURE_V2.rejects) {
+ const parsed = contract.parseGrokCompletionRequest(resolveFixtureImages(fixture.request))
+ assert.equal(parsed.ok, false, fixture.name)
+ assert.equal(parsed.code, fixture.reason, fixture.name)
+ assert.equal(parsed.message, fixture.message, fixture.name)
+ // The Codex contract refuses the same shape with the same message.
+ const codex = codexContract.parseCodexCompletionRequest(
+ asCodex(resolveFixtureImages(fixture.request))
+ )
+ assert.equal(codex.message, fixture.message, `${fixture.name} matches Codex`)
+ }
+})
+
+test('v2 visual fixtures: inline png/jpeg requests parse and pin the Codex fixture octets', () => {
+ assert.deepEqual(VISUAL_FIXTURE.imageSha256, CODEX_VISUAL_FIXTURE.imageSha256)
+ for (const key of ['png', 'jpeg', 'pngImageOnly']) {
+ const request = VISUAL_FIXTURE[key]
+ assert.equal(request.schemaVersion, contract.SCHEMA_VERSION_V2, key)
+ assert.equal(request.provider, 'grok-subscription', key)
+ const imageParts = request.messages[0].contentParts.filter(part => part.type === 'image')
+ assert.equal(imageParts.length, 1, key)
+ const bytes = Buffer.from(imageParts[0].data, 'base64')
+ const pinned = VISUAL_FIXTURE.imageSha256[imageParts[0].mimeType.replace('image/', '')]
+ assert.equal(crypto.createHash('sha256').update(bytes).digest('hex'), pinned, key)
+ const parsed = contract.parseGrokCompletionRequest(request)
+ assert.equal(parsed.ok, true, `${key}: ${parsed.message}`)
+ assert.deepEqual(
+ parsed.value.messages[0].contentParts,
+ request.messages[0].contentParts,
+ `${key} projection`
+ )
+ }
+})
+
+test('dispatcher: v1 rejects contentParts, unknown versions fail closed, v1 hashes are unchanged', () => {
+ const v1WithParts = { ...VISUAL_FIXTURE.png, schemaVersion: contract.SCHEMA_VERSION }
+ const rejected = contract.parseGrokCompletionRequestV1(v1WithParts)
+ assert.deepEqual(rejected, {
+ ok: false,
+ code: 'unknown-field',
+ message: "messages[0] rejects field 'contentParts'",
+ })
+ assert.equal(contract.parseGrokCompletionRequest(v1WithParts).ok, false)
+ // V1 keeps its own version message.
+ assert.equal(
+ contract.parseGrokCompletionRequestV1(v2TextRequest('hello')).message,
+ 'schemaVersion is not grok-completion-request.v1'
+ )
+
+ for (const schemaVersion of ['grok-completion-request.v3', undefined, null, 2]) {
+ assert.deepEqual(contract.parseGrokCompletionRequest({ ...BASE, schemaVersion }), {
+ ok: false,
+ code: 'invalid',
+ message: 'schemaVersion must be grok-completion-request.v1 or grok-completion-request.v2',
+ })
+ }
+ assert.equal(contract.parseGrokCompletionRequest('not an object').ok, false)
+
+ const v1 = contract.parseGrokCompletionRequest(BASE)
+ const v2 = contract.parseGrokCompletionRequest(v2TextRequest('hello'))
+ assert.equal(v1.ok, true)
+ assert.equal(v2.ok, true)
+ const withoutVersion = ({ schemaVersion, ...rest }) => rest
+ assert.deepEqual(withoutVersion(v2.value), withoutVersion(v1.value), 'text-only v2 keeps v1 semantics')
+ assert.notEqual(
+ contract.hashGrokCompletionRequest(v2.value),
+ contract.hashGrokCompletionRequest(v1.value)
+ )
+ // Every V1 golden request hashes identically through the version-generic path.
+ assert.equal(GOLDEN.cases.length > 0, true)
+ for (const entry of GOLDEN.cases) {
+ const parsed = contract.parseGrokCompletionRequest(entry.request)
+ assert.equal(parsed.ok, true, entry.name)
+ assert.equal(contract.hashGrokCompletionRequest(parsed.value), entry.sha256, entry.name)
+ }
+})
+
+test('pins the V2 refusal messages byte-identical to the Codex contract', () => {
+ const template = message => message.replace(/\d+/g, 'N')
+ const cases = [
+ {
+ name: 'non-image share',
+ grok: v2TextRequest('x'.repeat(contract.LIMITS.maxRequestBodyBytes + 1)),
+ codex: v2TextRequest('x'.repeat(codexContract.LIMITS.maxRequestBodyBytes + 1)),
+ message: 'request exceeds maxRequestBodyBytes outside image data',
+ },
+ {
+ name: 'per-image bytes',
+ grok: v2WithParts([imagePart(Buffer.alloc(20971520 + 1).toString('base64'))]),
+ codex: v2WithParts([
+ imagePart(
+ Buffer.alloc(codexContract.VISUAL_LIMITS.maxImageBytes + 1).toString('base64')
+ ),
+ ]),
+ message: 'messages[0].contentParts[0]: image exceeds 20971520 decoded bytes',
+ },
+ {
+ name: 'total image bytes',
+ grok: v2WithParts([
+ imagePart(declaredHeaderPngOfSize(10 * MIB).toString('base64')),
+ imagePart(declaredHeaderPngOfSize(10 * MIB + 1).toString('base64')),
+ ]),
+ codex: v2WithParts([
+ imagePart(declaredHeaderPngOfSize(10 * MIB).toString('base64')),
+ imagePart(declaredHeaderPngOfSize(6 * MIB + 1).toString('base64')),
+ ]),
+ message: 'request exceeds 20971520 total image bytes',
+ },
+ {
+ name: 'whole V2 body',
+ grok: v2WithParts([imagePart('A'.repeat(contract.LIMITS.maxVisualRequestBodyBytes))]),
+ codex: v2WithParts([
+ imagePart('A'.repeat(codexContract.LIMITS.maxVisualRequestBodyBytes)),
+ ]),
+ message: 'request exceeds maxVisualRequestBodyBytes',
+ },
+ ]
+ for (const entry of cases) {
+ const grok = contract.parseGrokCompletionRequest(entry.grok)
+ assert.deepEqual(
+ grok,
+ { ok: false, code: 'limit', kind: 'size', message: entry.message },
+ entry.name
+ )
+ const codex = codexContract.parseCodexCompletionRequest(asCodex(entry.codex))
+ assert.equal(codex.ok, false, `${entry.name}: Codex refuses its twin`)
+ assert.equal(codex.kind, 'size', entry.name)
+ assert.equal(template(codex.message), template(entry.message), `${entry.name} template`)
+ }
+})
+
+test("accepts a 20 MiB PNG and refuses 20 MiB + 1 with kind:'size'", () => {
+ const max = contract.GROK_VISUAL_LIMITS.maxImageBytes
+ assert.equal(max, 20 * MIB)
+ const atMax = realPngOfSize(max, 64, 48, 3)
+ assert.equal(atMax.length, max)
+ const accepted = contract.parseGrokCompletionRequest(v2WithParts([imagePart(atMax.toString('base64'))]))
+ assert.equal(accepted.ok, true, accepted.message)
+ const acceptedJpeg = contract.parseGrokCompletionRequest(
+ v2WithParts([imagePart(jpegOfSize(max).toString('base64'), 'image/jpeg')])
+ )
+ assert.equal(acceptedJpeg.ok, true, acceptedJpeg.message)
+ // Above the Codex per-image ceiling: the Grok budget is its own.
+ assert.ok(max > codexContract.VISUAL_LIMITS.maxImageBytes)
+
+ const overMax = realPngOfSize(max + 1, 64, 48, 3)
+ assert.equal(overMax.length, max + 1)
+ assert.deepEqual(
+ contract.parseGrokCompletionRequest(v2WithParts([imagePart(overMax.toString('base64'))])),
+ {
+ ok: false,
+ code: 'limit',
+ kind: 'size',
+ message: 'messages[0].contentParts[0]: image exceeds 20971520 decoded bytes',
+ }
+ )
+ // Encoded length is bounded before decoding.
+ const encoded = contract.parseGrokCompletionRequest(
+ v2WithParts([imagePart('A'.repeat(visualPayload.MAX_ENCODED_IMAGE_BYTES + 4))])
+ )
+ assert.equal(encoded.code, 'limit')
+ assert.equal(encoded.kind, 'size')
+})
+
+test("refuses 21 images with kind:'count', counted across the whole request", () => {
+ const png = IMAGE_DATA.png
+ const twenty = Array.from({ length: contract.GROK_VISUAL_LIMITS.maxImages }, () => imagePart(png))
+ const accepted = contract.parseGrokCompletionRequest(v2WithParts(twenty))
+ assert.equal(accepted.ok, true, accepted.message)
+ const refusal = {
+ ok: false,
+ code: 'limit',
+ kind: 'count',
+ message: 'request exceeds 20 images',
+ }
+ assert.deepEqual(contract.parseGrokCompletionRequest(v2WithParts([...twenty, imagePart(png)])), refusal)
+ // History counts: ten images in one message and eleven in another.
+ const split = contract.parseGrokCompletionRequest(
+ v2WithMessages([
+ { role: 'user', content: '', contentParts: twenty.slice(0, 10) },
+ { role: 'assistant', content: 'seen' },
+ { role: 'user', content: '', contentParts: [...twenty.slice(0, 10), imagePart(png)] },
+ ])
+ )
+ assert.deepEqual(split, refusal)
+})
+
+test('refuses a total over 20971520 image bytes', () => {
+ const tenMiB = declaredHeaderPngOfSize(10 * MIB).toString('base64')
+ const atTotal = contract.parseGrokCompletionRequest(
+ v2WithParts([imagePart(tenMiB), imagePart(tenMiB)])
+ )
+ assert.equal(atTotal.ok, true, atTotal.message)
+ assert.deepEqual(
+ contract.parseGrokCompletionRequest(
+ v2WithParts([
+ imagePart(tenMiB),
+ imagePart(declaredHeaderPngOfSize(10 * MIB + 1).toString('base64')),
+ ])
+ ),
+ { ok: false, code: 'limit', kind: 'size', message: 'request exceeds 20971520 total image bytes' }
+ )
+})
+
+test('refuses webp and gif; jpeg and png are the only image types', () => {
+ // Witness: the same part is accepted as png.
+ assert.equal(contract.parseGrokCompletionRequest(v2WithParts([imagePart(IMAGE_DATA.png)])).ok, true)
+ for (const mimeType of ['image/webp', 'image/gif']) {
+ assert.deepEqual(
+ contract.parseGrokCompletionRequest(v2WithParts([imagePart(IMAGE_DATA.png, mimeType)])),
+ { ok: false, code: 'invalid', message: 'messages[0].contentParts[0].mimeType is not allowed' },
+ mimeType
+ )
+ }
+ // Container and declared type must agree.
+ assert.equal(
+ contract.parseGrokCompletionRequest(v2WithParts([imagePart(IMAGE_DATA.png, 'image/jpeg')])).ok,
+ false
+ )
+})
+
+test('accepts a declared 9000x9000 PNG: there is no dimension or pixel limit', () => {
+ const huge = declaredHeaderPng(9000, 9000).toString('base64')
+ const accepted = contract.parseGrokCompletionRequest(v2WithParts([imagePart(huge)]))
+ assert.equal(accepted.ok, true, accepted.message)
+ assert.equal(accepted.value.messages[0].contentParts[0].data, huge)
+ const wide = contract.parseGrokCompletionRequest(
+ v2WithParts([imagePart(realPng(9000, 1, 5).toString('base64'))])
+ )
+ assert.equal(wide.ok, true, wide.message)
+ // The input is meaningful: the Codex contract refuses the same image on its
+ // dimension budget.
+ const codex = codexContract.parseCodexCompletionRequest(asCodex(v2WithParts([imagePart(huge)])))
+ assert.equal(codex.ok, false)
+ assert.match(codex.message, /dimension/)
+})
+
+test('non-image share over maxRequestBodyBytes is refused outside image data', () => {
+ const { maxRequestBodyBytes } = contract.LIMITS
+ const overflow = {
+ ok: false,
+ code: 'limit',
+ kind: 'size',
+ message: 'request exceeds maxRequestBodyBytes outside image data',
+ }
+ // Text-only V2: the whole body is the non-image share. Exact boundary.
+ const base = Buffer.byteLength(JSON.stringify(v2TextRequest('')), 'utf8')
+ const exact = v2TextRequest('x'.repeat(maxRequestBodyBytes - base))
+ assert.equal(Buffer.byteLength(JSON.stringify(exact), 'utf8'), maxRequestBodyBytes)
+ const atLimit = contract.parseGrokCompletionRequest(exact)
+ assert.equal(atLimit.ok, true, atLimit.message)
+ assert.deepEqual(
+ contract.parseGrokCompletionRequest(v2TextRequest('x'.repeat(maxRequestBodyBytes - base + 1))),
+ overflow
+ )
+ // Images do not buy text, and tool definitions share the same budget.
+ const longText = 'x'.repeat(maxRequestBodyBytes + MIB)
+ assert.deepEqual(
+ contract.parseGrokCompletionRequest(
+ v2WithParts([imagePart(IMAGE_DATA.png), { type: 'text', text: longText }], longText)
+ ),
+ overflow
+ )
+ assert.deepEqual(
+ contract.parseGrokCompletionRequest({
+ ...v2WithParts([imagePart(IMAGE_DATA.png)]),
+ tools: [{ name: 'read', description: 'y'.repeat(maxRequestBodyBytes + MIB), parameters: {} }],
+ }),
+ overflow
+ )
+})
+
+test('requestBodyLimitBytes: V2 declares 35 MiB; every other body keeps the 8 MiB ceiling', () => {
+ for (const v2 of [VISUAL_FIXTURE.png, VISUAL_FIXTURE.jpeg, VISUAL_FIXTURE.pngImageOnly]) {
+ assert.equal(contract.requestBodyLimitBytes(v2), 36700160)
+ }
+ for (const other of [
+ BASE,
+ { ...BASE, schemaVersion: 'grok-completion-request.v3' },
+ { ...BASE, schemaVersion: 'codex-completion-request.v2' },
+ { ...BASE, schemaVersion: undefined },
+ {},
+ null,
+ undefined,
+ 'x',
+ 7,
+ [],
+ ]) {
+ assert.equal(contract.requestBodyLimitBytes(other), 8388608, String(other))
+ }
+ // The same oversized shape parsed as V1 keeps the V1 ceiling and message.
+ const oversized = v2WithParts([imagePart('A'.repeat(contract.LIMITS.maxVisualRequestBodyBytes))])
+ assert.deepEqual(
+ contract.parseGrokCompletionRequestV1({ ...oversized, schemaVersion: contract.SCHEMA_VERSION }),
+ { ok: false, code: 'limit', kind: 'size', message: 'request exceeds maxRequestBodyBytes' }
+ )
+})
+
+test('measureNonImageAuthorizeBytes keeps wrapper fields on the maxRequestBodyBytes budget', () => {
+ const request = v2WithParts([{ type: 'text', text: 'look' }, imagePart(IMAGE_DATA.png)], 'look')
+ const wrapper = { request, invocationId: 'invocation-1', attemptGeneration: 1, targetRef: 'grok-primary' }
+ const whole = Buffer.byteLength(JSON.stringify(wrapper), 'utf8')
+ const blanked = {
+ ...wrapper,
+ request: {
+ ...request,
+ messages: [
+ { ...request.messages[0], contentParts: [{ type: 'text', text: 'look' }, { ...imagePart(''), data: '' }] },
+ ],
+ },
+ }
+ assert.equal(contract.measureNonImageAuthorizeBytes(wrapper), Buffer.byteLength(JSON.stringify(blanked), 'utf8'))
+ assert.ok(whole > contract.measureNonImageAuthorizeBytes(wrapper))
+ const stuffed = { ...wrapper, invocationId: 'x'.repeat(contract.LIMITS.maxRequestBodyBytes + MIB) }
+ assert.ok(contract.measureNonImageAuthorizeBytes(stuffed) > contract.LIMITS.maxRequestBodyBytes)
+ assert.equal(contract.requestBodyLimitBytes(stuffed.request), 36700160)
+})
+
+test('measureNonImageCompletionBytes omits the execution ticket', () => {
+ const request = v2WithParts([{ type: 'text', text: 'look' }, imagePart(IMAGE_DATA.png)], 'look')
+ const completion = {
+ request,
+ requestHash: 'a'.repeat(64),
+ executionTicket: `header.${'a'.repeat(2048)}.sig`,
+ }
+ const { executionTicket, ...withoutTicket } = completion
+ assert.ok(executionTicket.length > 2048)
+ assert.equal(
+ contract.measureNonImageCompletionBytes(completion),
+ contract.measureNonImageAuthorizeBytes(withoutTicket)
+ )
+ assert.ok(
+ contract.measureNonImageAuthorizeBytes(completion) >
+ contract.measureNonImageCompletionBytes(completion) + 2048
+ )
+})
+
+test('buildGrokProxyEnvelope: exact shape, no outer deadline, exact size boundary', () => {
+ const parsed = contract.parseGrokCompletionRequest({ ...VISUAL_FIXTURE.png, deadlineMs: 15000 })
+ assert.equal(parsed.ok, true, parsed.message)
+ const requestHash = contract.hashGrokCompletionRequest(parsed.value)
+ const built = contract.buildGrokProxyEnvelope({
+ executionTicket: 'header.payload.signature',
+ requestHash,
+ request: parsed.value,
+ })
+ assert.equal(built.ok, true, built.message)
+ assert.deepEqual(Object.keys(built.value), ['executionTicket', 'requestHash', 'request'])
+ assert.equal('deadlineMs' in built.value, false, 'outer deadline is never emitted')
+ assert.equal(built.value.request.deadlineMs, 15000)
+ assert.equal(Object.isFrozen(built.value), true)
+
+ // V2 exact boundary, moved by the ticket as the authorizer really does.
+ const limit = contract.LIMITS.maxVisualRequestBodyBytes
+ const sizeFor = ticketBytes =>
+ Buffer.byteLength(
+ JSON.stringify({ executionTicket: 't'.repeat(ticketBytes), requestHash, request: parsed.value }),
+ 'utf8'
+ )
+ const exactTicket = 8 + (limit - sizeFor(8))
+ assert.equal(sizeFor(exactTicket), limit)
+ const atLimit = contract.buildGrokProxyEnvelope({
+ executionTicket: 't'.repeat(exactTicket),
+ requestHash,
+ request: parsed.value,
+ })
+ assert.equal(atLimit.ok, true, atLimit.message)
+ assert.deepEqual(
+ contract.buildGrokProxyEnvelope({
+ executionTicket: 't'.repeat(exactTicket + 1),
+ requestHash,
+ request: parsed.value,
+ }),
+ { ok: false, code: 'limit', kind: 'size', message: 'proxy envelope exceeds maxVisualRequestBodyBytes' }
+ )
+
+ // V1 keeps the 8 MiB envelope ceiling and its own message.
+ const v1 = contract.parseGrokCompletionRequest({ ...BASE, deadlineMs: 5000 })
+ const v1Hash = contract.hashGrokCompletionRequest(v1.value)
+ const v1Size = ticketBytes =>
+ Buffer.byteLength(
+ JSON.stringify({ executionTicket: 't'.repeat(ticketBytes), requestHash: v1Hash, request: v1.value }),
+ 'utf8'
+ )
+ const v1Ticket = 8 + (contract.LIMITS.maxRequestBodyBytes - v1Size(8))
+ const v1Exact = contract.buildGrokProxyEnvelope({
+ executionTicket: 't'.repeat(v1Ticket),
+ requestHash: v1Hash,
+ request: v1.value,
+ })
+ assert.equal(v1Exact.ok, true, v1Exact.message)
+ assert.deepEqual(
+ contract.buildGrokProxyEnvelope({
+ executionTicket: 't'.repeat(v1Ticket + 1),
+ requestHash: v1Hash,
+ request: v1.value,
+ }),
+ { ok: false, code: 'limit', kind: 'size', message: 'proxy envelope exceeds maxRequestBodyBytes' }
+ )
+})
+
+test('buildGrokProxyEnvelope: fails closed on hash mismatch, bad input and invalid requests', () => {
+ const ticket = 'header.payload.signature'
+ const parsed = contract.parseGrokCompletionRequest(VISUAL_FIXTURE.png)
+ assert.equal(parsed.ok, true)
+ const requestHash = contract.hashGrokCompletionRequest(parsed.value)
+ // Witness: the well-formed envelope is accepted.
+ assert.equal(
+ contract.buildGrokProxyEnvelope({ executionTicket: ticket, requestHash, request: parsed.value }).ok,
+ true
+ )
+ const cases = [
+ ['hash-mismatch', { executionTicket: ticket, requestHash: 'a'.repeat(64), request: parsed.value }, 'request_hash_mismatch'],
+ ['hash-shape', { executionTicket: ticket, requestHash: 'not-a-digest', request: parsed.value }, 'invalid'],
+ ['unknown-envelope-field', { executionTicket: ticket, requestHash, request: parsed.value, deadlineMs: 1000 }, 'unknown-field'],
+ ['short-ticket', { executionTicket: 'short', requestHash, request: parsed.value }, 'invalid'],
+ ['ticket-control-character', { executionTicket: 'ticket\u0000value', requestHash, request: parsed.value }, 'invalid'],
+ ['request-unknown-root-field', { executionTicket: ticket, requestHash, request: { ...VISUAL_FIXTURE.png, headers: { Authorization: 'Bearer x' } } }, 'unknown-field'],
+ ['request-contradictory-parts', { executionTicket: ticket, requestHash, request: v2WithParts([{ type: 'text', text: 'actual' }], 'different') }, 'invalid'],
+ ['codex-request', { executionTicket: ticket, requestHash, request: asCodex(VISUAL_FIXTURE.png) }, 'invalid'],
+ ]
+ for (const [name, input, code] of cases) {
+ const result = contract.buildGrokProxyEnvelope(input)
+ assert.equal(result.ok, false, name)
+ assert.equal(result.code, code, name)
+ }
+ assert.equal(contract.buildGrokProxyEnvelope(null).code, 'invalid')
+})
+
+// The Grok validator is a copy of the Codex one with Grok limits and without
+// the dimension/pixel budget. On images inside both budgets the two copies
+// must return the same verdict, byte for byte.
+test('parity: identical verdicts across both visualPayload copies, dimension limits excluded', () => {
+ const png = Buffer.from(IMAGE_DATA.png, 'base64')
+ const jpeg = Buffer.from(IMAGE_DATA.jpeg, 'base64')
+ const corpus = [
+ ['fixture png', 'image/png', IMAGE_DATA.png],
+ ['fixture jpeg', 'image/jpeg', IMAGE_DATA.jpeg],
+ ['real 64x48 png', 'image/png', realPng(64, 48, 7).toString('base64')],
+ ['framed 4 KiB jpeg', 'image/jpeg', jpegOfSize(4096, 640, 480).toString('base64')],
+ ['declared 2048x2048 png', 'image/png', declaredHeaderPng(2048, 2048).toString('base64')],
+ ['jpeg without EOI', 'image/jpeg', jpeg.subarray(0, jpeg.length - 2).toString('base64')],
+ ['png truncated after IHDR', 'image/png', png.subarray(0, 33).toString('base64')],
+ ['png signature only', 'image/png', png.subarray(0, 8).toString('base64')],
+ ['png declared as jpeg', 'image/jpeg', IMAGE_DATA.png],
+ ['jpeg declared as png', 'image/png', IMAGE_DATA.jpeg],
+ ['base64 without padding', 'image/png', 'abc'],
+ ['base64 with non-canonical trailing bits', 'image/png', 'AB=='],
+ ['base64 with a bad alphabet', 'image/png', '!!!!'],
+ ['empty data', 'image/png', ''],
+ ['non-string data', 'image/png', 42],
+ ['gif type', 'image/gif', IMAGE_DATA.png],
+ ['webp type', 'image/webp', IMAGE_DATA.png],
+ ]
+ assert.ok(corpus.length > 0)
+ let accepted = 0
+ let refused = 0
+ for (const [name, mimeType, data] of corpus) {
+ const grok = visualPayload.inspectVisualImage({ mimeType, data })
+ const codex = codexVisualPayload.inspectVisualImage({ mimeType, data })
+ assert.deepEqual(grok, codex, name)
+ if (grok.ok) accepted += 1
+ else refused += 1
+ }
+ assert.ok(accepted >= 1, 'the corpus contains accepted images')
+ assert.ok(refused >= 1, 'the corpus contains refused images')
+
+ // The one intended difference: dimensions beyond the Codex budget.
+ const large = { mimeType: 'image/png', data: declaredHeaderPng(9000, 9000).toString('base64') }
+ assert.equal(visualPayload.inspectVisualImage(large).ok, true)
+ assert.equal(codexVisualPayload.inspectVisualImage(large).ok, false)
+})