Skip to content

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

TypeScript

refactor(mcp-host): share the message projection, parse the Grok V2 request once

Alfredo Lopezdbf2c1c8b348
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 16658e403..0e1b6bcb6 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -39,8 +39,9 @@ Limits, from the xAI documentation (grok-4.5, 4.6 and 4.7 list
- JPEG and PNG only. WebP and GIF are refused.
There is **no dimension or pixel limit**. The validator reads the PNG or
-JPEG header to check the container, and never refuses on width or height; a
-declared 9000×9000 PNG is accepted and reaches the upstream. This differs from
+JPEG header to check the container. It has no upper bound on width or height
+(a declared 9000×9000 PNG is accepted and reaches the upstream); it refuses
+only a zero dimension. This differs from
Codex, whose 2048 px bound comes from its measured endpoint. The validator
checks canonical base64, MIME/container framing and header dimensions; it does
not decode pixels.
@@ -117,7 +118,7 @@ so it never queues behind a visual stream, and a declared length above the
visual cap is refused 413 before reading. Anonymous, wrong-scope and admin requests keep the
ordinary limit.
-**Per-principal visual share (B4).** In addition to the gate, each platform
+**Per-principal visual share.** In addition to the gate, each platform
identity (`sub` plus sorted `hostRefs`) may hold at most 2 visual entries
(running or queued) of the gate's 5. A token whose `sub` is missing, empty or
not a string is refused 401 before any gate or share is taken. When the share
@@ -932,16 +933,28 @@ Grok annotations. A new control-api also republishes on boot.
`GROK_LLM_PROXY_EXECUTION_ENABLED`. `MCP_HOST_GROK_SUBSCRIPTION_ENABLED`
follows automatically through HCC and WRC.
-Image input (#784) on a deployment where the Grok flags are already on:
-deploy control-api and `grok-llm-proxy` first, wait until every pod of both
-runs the new image, and only then deploy the four Host images. V2 has no flag
-of its own, so a new Host sends an image-bearing request as soon as it runs.
-An old control-api refuses it (400 `invalid_request`, or 413 above its 24 MiB
-route parser), and an old proxy refuses it after the attempt was authorized
-(400 `invalid_request`, or 413 above its 8 MiB parser, which the user sees as
-"Conversation Too Long"). Step 4's Host-before-proxy rule protects a
-response-side bound, `maxToolCalls`, whose band a new proxy would bill and an
-old Host would discard. #784 leaves `maxToolCalls` (256) unchanged, so the rule
+Image input (#784) on a deployment where the Grok flags are already on: roll
+out `grok-llm-proxy` first, then control-api, then the four Host images, and
+wait until every pod of each runs the new image before starting the next.
+V2 has no version negotiation and no flag of its own: a new Host sends an
+image-bearing request as soon as it runs, and nothing tells it what the
+control-api or the proxy behind it accepts. Each mixed-version pairing fails
+closed, and what the user sees is:
+
+| Pairing | Request | What happens | What the user sees |
+| --- | --- | --- | --- |
+| new Host, old control-api | V2 within the old route parser | refused at authorize with 400 `invalid_request`; no attempt row, nothing sent | "Connection Error" (`LLM_API_CALL_FAILED`, not retryable) |
+| new Host, old control-api | V2 above the old route parser (24 MiB) | refused at authorize with 413 `payload_too_large` | "Conversation Too Long" (`LLM_CONTEXT_LENGTH_EXCEEDED`); shortening the text does not help |
+| new Host, new control-api, old proxy | V2 within the old proxy parser | authorized (ticket and attempt row written), refused by the proxy with 400 `invalid_request`; one attempt consumed, nothing sent upstream | "Connection Error" |
+| new Host, new control-api, old proxy | V2 above the old proxy parser (8 MiB) | authorized, refused by the proxy with 413 `payload_too_large` | "Conversation Too Long" |
+| old Host, any control-api and proxy | V1 only | unchanged | nothing new |
+
+The order proxy, control-api, Host keeps a V2 request from being authorized
+against a proxy that will refuse it: with the proxy already new, an old
+control-api refuses V2 before any attempt is recorded. Step 4's
+Host-before-proxy rule protects a response-side bound, `maxToolCalls`, whose
+band a new proxy would bill and an old Host would discard. #784 leaves
+`maxToolCalls` (256) unchanged, so the rule
does not apply to this upgrade. #784 does tighten request-side V1 bounds: it
adds `maxRequestContainers` and `maxRequestMembers` (262144 each) and lowers
the element bound from 8388608 to `maxRequestElements` (1048576). A request
@@ -977,7 +990,11 @@ the flags stay off until step 6, and steps 1-6 apply as written.
Image input (#784) alone, with the Grok flags left on: roll back the four Host
images first and wait until no Host pod runs a #784 image, then roll back
-`grok-llm-proxy` and control-api — the upgrade order reversed. V2 has no flag
+control-api and `grok-llm-proxy` — the upgrade order reversed. A visual request
+already queued at the proxy waits at most until its 60 s admission deadline
+(see "Proxy admission"), so wait at least that long after the last Host is
+rolled back, and for any running visual stream to end, before replacing the
+proxy pods. V2 has no flag
of its own, so a #784 Host keeps sending image-bearing V2 requests; an older
control-api refuses them at authorize (400 `invalid_request`, or 413 above its
24 MiB route parser) and an older proxy refuses them after the attempt was
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 601af23c9..4a3694e8a 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.470",
+ "version": "0.1.471",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.470",
+ "version": "0.1.471",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index a9d4f6471..5fb1bfddd 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.470",
+ "version": "0.1.471",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
index 3e8f3cb1b..2ffaddb4f 100644
--- a/mcp-host/src/llm/__tests__/codexSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
@@ -1227,6 +1227,36 @@ describe('CodexSubscriptionProvider', () => {
expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
})
+ it('classifies image_source_invalid as a non-retryable ApiCallFailed with no failover', () => {
+ const provider = new CodexSubscriptionProvider('gpt-5.6-luna', deps() as never)
+ const message = 'image part has no usable provenance source (missing source)'
+
+ const classified = provider.classifyError(
+ new CodexAuthorizeError('image_source_invalid', message)
+ )
+
+ expect(classified).toEqual({
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: false,
+ message,
+ providerCode: 'image_source_invalid',
+ providerDispatched: false,
+ })
+ expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
+
+ // Liveness witness: a retryable code classified by the same provider does
+ // retry and fail over, so the assertions above are not satisfied by a
+ // classifier that never retries.
+ const retryable = provider.classifyError(
+ new CodexProxyError(
+ 'provider_unavailable',
+ 'proxy stream failed with 503 (provider_unavailable)'
+ )
+ )
+ expect(retryable.retryable).toBe(true)
+ expect(classifyFailoverClass(retryable.code, retryable.retryable)).not.toBeNull()
+ })
+
it.each(METHODS)('rejects an image part without provenance through %s', async method => {
const wired = deps()
const provider = new CodexSubscriptionProvider('gpt-5.6-luna', wired as never)
diff --git a/mcp-host/src/llm/__tests__/grokSubscription.test.ts b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
index 5f2505e08..420eb5599 100644
--- a/mcp-host/src/llm/__tests__/grokSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
@@ -1296,6 +1296,36 @@ describe('GrokSubscriptionProvider image input (#784)', () => {
}
)
+ it('T-G4b-6c classifies image_source_invalid as a non-retryable ApiCallFailed with no failover', () => {
+ const provider = new GrokSubscriptionProvider('grok-4.6', deps() as never)
+ const message = 'image part has no usable provenance source (missing source)'
+
+ const classified = provider.classifyError(
+ new CodexAuthorizeError('image_source_invalid', message)
+ )
+
+ expect(classified).toEqual({
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: false,
+ message,
+ providerCode: 'image_source_invalid',
+ providerDispatched: false,
+ })
+ expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
+
+ // Liveness witness: a retryable code classified by the same provider does
+ // retry and fail over, so the assertions above are not satisfied by a
+ // classifier that never retries.
+ const retryable = provider.classifyError(
+ new GrokProxyError(
+ 'provider_unavailable',
+ 'proxy stream failed with 503 (provider_unavailable)'
+ )
+ )
+ expect(retryable.retryable).toBe(true)
+ expect(classifyFailoverClass(retryable.code, retryable.retryable)).not.toBeNull()
+ })
+
const MIB = 1024 * 1024
const GROK_ATTACHMENT_REFUSALS: Array<{
name: string
diff --git a/mcp-host/src/llm/codexSubscription.ts b/mcp-host/src/llm/codexSubscription.ts
index 5fba1c046..1204c0e50 100644
--- a/mcp-host/src/llm/codexSubscription.ts
+++ b/mcp-host/src/llm/codexSubscription.ts
@@ -10,10 +10,8 @@ import {
CompletionResponse,
ChatMessage as CoreChatMessage,
FinishReason,
- MessageContentImageSource,
ToolCompletionResponse,
ToolDefinition,
- textContentFromParts,
} from '../core/types'
import { logger } from '../logger'
import {
@@ -22,7 +20,7 @@ import {
} from './attachmentBudgetRefusal'
import { CodexLlmProxyClient, CodexProxyError } from './codexLlmProxyClient'
import { classifyUnknown } from './errorClassification'
-import { projectImageSource } from './imageSource'
+import { IMAGE_SOURCE_INVALID, isContextLengthRefusal, projectMessage } from './imageSource'
import { CodexAuthorizeError, ProviderAttemptAuthorizer } from './providerAttemptAuthorizer'
import { rateLimitRetryDelayMs, waitBeforeRetry } from './rateLimitRetry'
import { type LlmProvider, descriptorFor } from './registryCore'
@@ -42,65 +40,6 @@ export type CodexAttemptContext = {
userId?: string
}
-/**
- * The contract `limit` refusals that mean "this turn carries too much".
- *
- * Of the `fail('limit', …)` checks on a request, only these are about
- * conversation volume, all in `llm-provider-attempt-contract/index.cjs`: the
- * real byte bound and its non-image share on a V2 request (both in
- * `parseCodexCompletionRequestRoot`), the independent element bound
- * (`checkStructure`), and `maxMessages` and `messages[i].toolCalls` (both in
- * `parseMessages`).
- * All five are request-volume refusals mapped to `ContextLengthExceeded` —
- * "Conversation Too Long" in the UI. Compaction reaches them unevenly. The
- * context manager counts bytes and, through the registry's `maxMessages`,
- * the message count; it does not count JSON values. A single turn holding
- * more than `maxMessages` messages stays unshrinkable, because the cut never
- * lands inside a turn. A large tool definition is also not compactable.
- * `maxToolCalls` also bounds every response, so only history produced by
- * another provider can carry an over-long `toolCalls` array.
- *
- * The others are not. Nesting depth (`checkStructure`, `assertFiniteTree`),
- * `generation.maxOutputTokens` (`parseGeneration`) and `deadlineMs`
- * (`parseCodexCompletionRequestRoot`) out of range are malformed or
- * out-of-range parameters, and a shorter conversation fixes none of them;
- * labelling them a context-length failure would send the user into a
- * compaction loop that cannot converge. They stay `invalid_request`, which is
- * what "fails an over-deep tool schema locally without a stack overflow" in
- * `subscriptionRequestHash.test.ts` pins for the over-deep schema.
- * The image budgets belong to the attachments, not the conversation: a `size`
- * one is `attachment_too_large` (see `ATTACHMENT_BUDGET_REFUSALS`), the
- * `maxImages` `count` one stays `invalid_request`. The structural volume bounds
- * (`maxRequestContainers` and `maxRequestMembers`, both from `checkStructure`)
- * are volume too, but they are not listed: each carries `kind: 'size'`, so it
- * reaches the user as `payload_too_large`, which classifies the same way
- * (T-C3b for containers, T-C3d for members; the proxy's raw-body member 413 is
- * T-C3c).
- *
- * `hashCanonicalCodexRequest` also returns a `kind`, but it cannot replace the
- * message here: `size` covers the conversation bytes and the image byte and
- * dimension budgets alike, and `count` covers `maxMessages` and `maxImages`
- * alike. A shorter conversation fixes the first of each pair and none of the
- * second, so the message stays the discriminator at this boundary (#731). The
- * byte pattern is a prefix so it covers the `outside image data` check of a
- * V2 request. The element bound has its own explicit pattern.
- *
- * `messages exceed` is defence in depth rather than a reachable branch: the
- * guard below raises that exact message with this same classification before
- * `hashCanonicalCodexRequest` runs, so the contract's own copy of it only
- * arrives here if that guard is ever removed.
- */
-const CONTEXT_LENGTH_REFUSALS = [
- /^request exceeds maxRequestBodyBytes/,
- /^request exceeds maxRequestElements$/,
- /^messages exceed \d+$/,
- /^messages\[\d+\]\.toolCalls exceed \d+$/,
-]
-
-function isContextLengthRefusal(code: string, message: string): boolean {
- return code === 'limit' && CONTEXT_LENGTH_REFUSALS.some(pattern => pattern.test(message))
-}
-
/**
* The Codex image budget refusals, built from the Codex contract limits (see
* `buildAttachmentBudgetRefusals` for the rows and their order).
@@ -165,24 +104,6 @@ const CODEX_REQUEST_INVALID = 'invalid_request'
/** A local image budget refusal (`ATTACHMENT_BUDGET_REFUSALS`). */
const CODEX_ATTACHMENT_TOO_LARGE = 'attachment_too_large'
-/** One image part as the Codex V2 contract serializes it. */
-type ProjectedImagePart = {
- type: 'image'
- mimeType: 'image/jpeg' | 'image/png'
- data: string
- source: MessageContentImageSource
-}
-
-/** One message as either contract version serializes it. */
-type ProjectedMessage = {
- role: CoreChatMessage['role']
- content: string
- contentParts?: Array<{ type: 'text'; text: string } | ProjectedImagePart>
- name?: string
- toolCallId?: string
- toolCalls?: Array<{ id: string; name: string; arguments: Record<string, unknown> }>
-}
-
function assertTerminalCodexOutcome(result: {
text: string
toolCalls: Array<{ id: string; name: string; arguments: Record<string, unknown> }>
@@ -348,6 +269,19 @@ export class CodexSubscriptionProvider implements SingleTurnProvider {
...(providerDispatched !== undefined ? { providerDispatched } : {}),
}
}
+ if (code === IMAGE_SOURCE_INVALID) {
+ // A host producer attached an image with no usable provenance source. The
+ // same messages fail the same way on every provider, so it is terminal:
+ // neither a retry nor a failover can fix it. The arm is explicit so a
+ // change to the generic arm below cannot make it retryable.
+ return {
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
// `payload_too_large` is the proxy's 413 for an envelope over its body
// limit: the same size refusal of this conversation, one hop later.
// `context_length_exceeded` is the upstream's refusal of a request over the
@@ -613,57 +547,14 @@ export class CodexSubscriptionProvider implements SingleTurnProvider {
}
}
- /**
- * Project the loop's messages onto the wire contract.
- *
- * A turn with no parts stays byte-identical to V1. As soon as one message
- * carries parts the whole request moves to V2, where the text parts are
- * authoritative for `content` — that is what keeps a redacted (text-only)
- * message consistent with the contract's equality rule.
- */
- private projectMessage(message: CoreChatMessage): ProjectedMessage {
- const projected: ProjectedMessage = {
- role: message.role,
- content: message.content ?? '',
- ...(message.name ? { name: message.name } : {}),
- ...(message.tool_call_id ? { toolCallId: message.tool_call_id } : {}),
- ...(message.role === 'assistant' && message.tool_calls && message.tool_calls.length > 0
- ? {
- toolCalls: message.tool_calls.map(call => ({
- id: call.id,
- name: call.name,
- arguments: call.arguments,
- })),
- }
- : {}),
- }
- const parts = message.contentParts
- if (!parts || parts.length === 0) return projected
- if (message.role !== 'user') {
- throw new CodexAuthorizeError(
- CODEX_REQUEST_INVALID,
- `content parts are only supported on user messages (role=${message.role})`
- )
- }
- const contentParts: NonNullable<ProjectedMessage['contentParts']> = parts.map(part =>
- part.type === 'text'
- ? { type: 'text', text: part.text }
- : {
- type: 'image',
- mimeType: part.mimeType,
- data: part.data,
- source: projectImageSource(part),
- }
- )
- return { ...projected, content: textContentFromParts(contentParts), contentParts }
- }
-
private buildRequest(
messages: CoreChatMessage[],
tools: ToolDefinition[] | undefined,
options?: { max_tokens?: number; temperature?: number; tool_choice?: string }
): CodexCompletionRequest {
- const projectedMessages = messages.map(message => this.projectMessage(message))
+ const projectedMessages = messages.map(message =>
+ projectMessage(message, CODEX_REQUEST_INVALID)
+ )
const presentedTools =
tools && tools.length > 0
? tools.map(tool => ({
diff --git a/mcp-host/src/llm/grokLlmProxyClient.ts b/mcp-host/src/llm/grokLlmProxyClient.ts
index 0c7a3fbec..073ebedf0 100644
--- a/mcp-host/src/llm/grokLlmProxyClient.ts
+++ b/mcp-host/src/llm/grokLlmProxyClient.ts
@@ -1,7 +1,7 @@
import {
+ type GrokCompletionRequest,
SCHEMA_VERSION_V2,
buildGrokProxyEnvelope,
- parseGrokCompletionRequest,
} from '@clerum/grok-provider-attempt-contract'
import { fetchCauseCode, isConnectPhaseFailure } from './controlPlaneReachability'
import { rateLimitedCode, retryAfterMs } from './retryAfter'
@@ -126,21 +126,13 @@ export class GrokLlmProxyClient {
// A V2 request carries its deadline inside the hashed request, and
// grok-llm-proxy refuses an outer one. The envelope is the contract's own,
// so a request the proxy would refuse never leaves this process (#784).
+ // The envelope builder parses and hashes the request itself, so the request
+ // is parsed once here; the deadline is compared with the parsed value.
if ((input.request as { schemaVersion?: string } | null)?.schemaVersion === SCHEMA_VERSION_V2) {
- const parsed = parseGrokCompletionRequest(input.request)
- if (!parsed.ok)
- throw new GrokProxyError('invalid_request', parsed.message, { dispatched: false })
- if (input.deadlineMs !== undefined && input.deadlineMs !== parsed.value.deadlineMs) {
- throw new GrokProxyError(
- 'invalid_request',
- 'Grok deadline must match the authorized request',
- { dispatched: false }
- )
- }
const envelope = buildGrokProxyEnvelope({
executionTicket: input.executionTicket,
requestHash: input.requestHash,
- request: parsed.value,
+ request: input.request as GrokCompletionRequest,
})
if (!envelope.ok) {
const code =
@@ -151,6 +143,16 @@ export class GrokLlmProxyClient {
: 'invalid_request'
throw new GrokProxyError(code, envelope.message, { dispatched: false })
}
+ if (
+ input.deadlineMs !== undefined &&
+ input.deadlineMs !== envelope.value.request.deadlineMs
+ ) {
+ throw new GrokProxyError(
+ 'invalid_request',
+ 'Grok deadline must match the authorized request',
+ { dispatched: false }
+ )
+ }
body = envelope.value
}
const jwt = this.options.readPlatformJwt()
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
index cb58fe9a0..9b9d650b0 100644
--- a/mcp-host/src/llm/grokSubscription.ts
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -11,10 +11,8 @@ import {
CompletionResponse,
ChatMessage as CoreChatMessage,
FinishReason,
- MessageContentImageSource,
ToolCompletionResponse,
ToolDefinition,
- textContentFromParts,
} from '../core/types'
import { logger } from '../logger'
import {
@@ -23,7 +21,7 @@ import {
} from './attachmentBudgetRefusal'
import { classifyUnknown } from './errorClassification'
import { GrokLlmProxyClient, GrokProxyError } from './grokLlmProxyClient'
-import { projectImageSource } from './imageSource'
+import { IMAGE_SOURCE_INVALID, isContextLengthRefusal, projectMessage } from './imageSource'
import { CodexAuthorizeError, ProviderAttemptAuthorizer } from './providerAttemptAuthorizer'
import { rateLimitRetryDelayMs, waitBeforeRetry } from './rateLimitRetry'
import { type LlmProvider, descriptorFor } from './registryCore'
@@ -43,74 +41,6 @@ export type GrokAttemptContext = {
userId?: string
}
-/**
- * The contract `limit` refusals that mean "this turn carries too much".
- *
- * The Grok twin of `CONTEXT_LENGTH_REFUSALS` in `codexSubscription.ts`. The two
- * are deliberate duplicates, not an accident: the header of
- * `grok-provider-attempt-contract/index.cjs` states that this package does
- * not import the Codex contract's LIMITS, and a
- * shared predicate would either recreate that coupling or pin prose rather than
- * code. The cost of the duplication is that each copy needs its own tests, which
- * is what T-C-grok, T-C2-grok, T-C3-grok and T-C5-grok are for. If you change
- * one list, read the other.
- *
- * Of the `fail('limit', …)` checks on a request, only these are about volume:
- * the real byte bound and its non-image share on a V2 request (both in
- * `parseGrokCompletionRequestRoot`), the independent element bound
- * (`checkStructure`), and `maxMessages` and `messages[i].toolCalls` (both in
- * `parseMessages`).
- * All five are request-volume refusals mapped to `ContextLengthExceeded` —
- * "Conversation Too Long" in the UI. Compaction reaches them unevenly. The
- * context manager counts bytes and, through the registry's `maxMessages`,
- * the message count; it does not count JSON values. A single turn holding
- * more than `maxMessages` messages stays unshrinkable, because the cut never
- * lands inside a turn. A large tool definition is also not compactable.
- * `maxToolCalls` also bounds every response, so only history produced by
- * another provider can carry an over-long `toolCalls` array.
- *
- * The others are not. Nesting depth (`checkStructure`, `assertFiniteTree`),
- * `generation.maxOutputTokens` (`parseGeneration`) and `deadlineMs`
- * (`parseGrokCompletionRequestRoot`) out of range are malformed or
- * out-of-range parameters, and a shorter conversation fixes none of them;
- * labelling them a context-length failure would send the user into a
- * compaction loop that cannot converge. They stay `invalid_request`, which is
- * what "fails an over-deep tool schema locally without a stack overflow" in
- * `subscriptionRequestHash.test.ts` pins for the over-deep schema across both
- * providers. The image budgets belong to the attachments, not the
- * conversation: a `size` one is `attachment_too_large` (see
- * `ATTACHMENT_BUDGET_REFUSALS`), the `maxImages` `count` one stays
- * `invalid_request`. The structural volume bounds (`maxRequestContainers` and
- * `maxRequestMembers`, both from `checkStructure`) are volume too, but they are
- * not listed: each carries `kind: 'size'`, so it reaches the user as
- * `payload_too_large`, which classifies the same way (T-C3b-grok for
- * containers, T-C3d-grok for members; the proxy's raw-body member 413 is
- * T-C3c-grok).
- *
- * `hashCanonicalGrokRequest` also returns a `kind` (#784), but it cannot
- * replace the message here: `size` covers the conversation bytes and the image
- * byte budgets alike, and a shorter conversation fixes the first and not the
- * second. `count` is only ever `maxImages`; the `maxMessages` and tool-call
- * refusals carry no `kind`. So the message stays the discriminator at this
- * boundary (#731). The byte pattern is a prefix so it covers the `outside
- * image data` check of a V2 request. The element bound has its own pattern.
- *
- * `messages exceed` is defence in depth rather than a reachable branch: the
- * guard in `execute` raises that exact message with this same classification
- * before `hashCanonicalGrokRequest` runs, so the contract's own copy of it only
- * arrives here if that guard is ever removed.
- */
-const CONTEXT_LENGTH_REFUSALS = [
- /^request exceeds maxRequestBodyBytes/,
- /^request exceeds maxRequestElements$/,
- /^messages exceed \d+$/,
- /^messages\[\d+\]\.toolCalls exceed \d+$/,
-]
-
-function isContextLengthRefusal(code: string, message: string): boolean {
- return code === 'limit' && CONTEXT_LENGTH_REFUSALS.some(pattern => pattern.test(message))
-}
-
/**
* The Grok image budget refusals, built from the Grok contract limits (see
* `buildAttachmentBudgetRefusals`). Grok has no dimension or pixel limit, so
@@ -130,24 +60,6 @@ const GROK_REQUEST_INVALID = 'invalid_request'
/** A local image budget refusal (`ATTACHMENT_BUDGET_REFUSALS`). */
const GROK_ATTACHMENT_TOO_LARGE = 'attachment_too_large'
-/** One image part as the Grok V2 contract serializes it. */
-type ProjectedImagePart = {
- type: 'image'
- mimeType: 'image/jpeg' | 'image/png'
- data: string
- source: MessageContentImageSource
-}
-
-/** One message as either contract version serializes it. */
-type ProjectedMessage = {
- role: CoreChatMessage['role']
- content: string
- contentParts?: Array<{ type: 'text'; text: string } | ProjectedImagePart>
- name?: string
- toolCallId?: string
- toolCalls?: Array<{ id: string; name: string; arguments: Record<string, unknown> }>
-}
-
function mapGrokUsage(usage?: { inputTokens: number; outputTokens: number }): {
usage: { input_tokens: number; output_tokens: number; total_tokens: number }
usage_reported: boolean
@@ -349,6 +261,19 @@ export class GrokSubscriptionProvider implements SingleTurnProvider {
...(providerDispatched !== undefined ? { providerDispatched } : {}),
}
}
+ if (code === IMAGE_SOURCE_INVALID) {
+ // A host producer attached an image with no usable provenance source. The
+ // same messages fail the same way on every provider, so it is terminal:
+ // neither a retry nor a failover can fix it. The arm is explicit so a
+ // change to the generic arm below cannot make it retryable.
+ return {
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
// Same family as `request_limit_exceeded`, from the response side: the
// transport refused a tool call whose arguments overran its size budget.
// Treating it as an outage would retry the identical oversized call and,
@@ -620,58 +545,12 @@ export class GrokSubscriptionProvider implements SingleTurnProvider {
}
}
- /**
- * Project the loop's messages onto the wire contract.
- *
- * A turn with no parts stays byte-identical to V1. As soon as one message
- * carries parts the whole request moves to V2, where the text parts are
- * authoritative for `content` — that is what keeps a redacted (text-only)
- * message consistent with the contract's equality rule. The twin of
- * `projectMessage` in `codexSubscription.ts` (#784).
- */
- private projectMessage(message: CoreChatMessage): ProjectedMessage {
- const projected: ProjectedMessage = {
- role: message.role,
- content: message.content ?? '',
- ...(message.name ? { name: message.name } : {}),
- ...(message.tool_call_id ? { toolCallId: message.tool_call_id } : {}),
- ...(message.role === 'assistant' && message.tool_calls && message.tool_calls.length > 0
- ? {
- toolCalls: message.tool_calls.map(call => ({
- id: call.id,
- name: call.name,
- arguments: call.arguments,
- })),
- }
- : {}),
- }
- const parts = message.contentParts
- if (!parts || parts.length === 0) return projected
- if (message.role !== 'user') {
- throw new CodexAuthorizeError(
- GROK_REQUEST_INVALID,
- `content parts are only supported on user messages (role=${message.role})`
- )
- }
- const contentParts: NonNullable<ProjectedMessage['contentParts']> = parts.map(part =>
- part.type === 'text'
- ? { type: 'text', text: part.text }
- : {
- type: 'image',
- mimeType: part.mimeType,
- data: part.data,
- source: projectImageSource(part),
- }
- )
- return { ...projected, content: textContentFromParts(contentParts), contentParts }
- }
-
private buildRequest(
messages: CoreChatMessage[],
tools: ToolDefinition[] | undefined,
options?: { max_tokens?: number; temperature?: number; tool_choice?: string }
): GrokCompletionRequest {
- const projectedMessages = messages.map(message => this.projectMessage(message))
+ const projectedMessages = messages.map(message => projectMessage(message, GROK_REQUEST_INVALID))
const request: Omit<GrokCompletionRequestV2, 'schemaVersion'> = {
requestId: randomUUID(),
idempotencyKey: randomUUID(),
diff --git a/mcp-host/src/llm/imageSource.ts b/mcp-host/src/llm/imageSource.ts
index b413c1eb6..f8701845b 100644
--- a/mcp-host/src/llm/imageSource.ts
+++ b/mcp-host/src/llm/imageSource.ts
@@ -1,7 +1,15 @@
-import type { MessageContentImageSource, MessageContentPart } from '../core/types'
+import {
+ type ChatMessage,
+ type MessageContentImageSource,
+ type MessageContentPart,
+ textContentFromParts,
+} from '../core/types'
import { CodexAuthorizeError } from './providerAttemptAuthorizer'
-/** A pre-authorize refusal: known and non-retryable in both providers. */
+/**
+ * A pre-authorize refusal. Both providers' `classifyError` have an explicit
+ * arm that maps it to a non-retryable `ApiCallFailed`.
+ */
export const IMAGE_SOURCE_INVALID = 'image_source_invalid'
function imageSourceError(detail: string): CodexAuthorizeError {
@@ -45,3 +53,132 @@ export function projectImageSource(
}
throw imageSourceError('unknown source kind')
}
+
+/** One image part as the Codex and Grok V2 contracts serialize it. */
+export type ProjectedImagePart = {
+ type: 'image'
+ mimeType: 'image/jpeg' | 'image/png'
+ data: string
+ source: MessageContentImageSource
+}
+
+/** One message as either contract version serializes it. */
+export type ProjectedMessage = {
+ role: ChatMessage['role']
+ content: string
+ contentParts?: Array<{ type: 'text'; text: string } | ProjectedImagePart>
+ name?: string
+ toolCallId?: string
+ toolCalls?: Array<{ id: string; name: string; arguments: Record<string, unknown> }>
+}
+
+/**
+ * Project one loop message onto the wire contract, for both providers. The
+ * caller passes the provider's `invalid_request` code for the one refusal made
+ * here (content parts on a non-user message).
+ *
+ * A turn with no parts stays byte-identical to V1. As soon as one message
+ * carries parts the whole request moves to V2, where the text parts are
+ * authoritative for `content` - that is what keeps a redacted (text-only)
+ * message consistent with the contract's equality rule (#784).
+ */
+export function projectMessage(message: ChatMessage, invalidRequestCode: string): ProjectedMessage {
+ const projected: ProjectedMessage = {
+ role: message.role,
+ content: message.content ?? '',
+ ...(message.name ? { name: message.name } : {}),
+ ...(message.tool_call_id ? { toolCallId: message.tool_call_id } : {}),
+ ...(message.role === 'assistant' && message.tool_calls && message.tool_calls.length > 0
+ ? {
+ toolCalls: message.tool_calls.map(call => ({
+ id: call.id,
+ name: call.name,
+ arguments: call.arguments,
+ })),
+ }
+ : {}),
+ }
+ const parts = message.contentParts
+ if (!parts || parts.length === 0) return projected
+ if (message.role !== 'user') {
+ throw new CodexAuthorizeError(
+ invalidRequestCode,
+ `content parts are only supported on user messages (role=${message.role})`
+ )
+ }
+ const contentParts: NonNullable<ProjectedMessage['contentParts']> = parts.map(part =>
+ part.type === 'text'
+ ? { type: 'text', text: part.text }
+ : {
+ type: 'image',
+ mimeType: part.mimeType,
+ data: part.data,
+ source: projectImageSource(part),
+ }
+ )
+ return { ...projected, content: textContentFromParts(contentParts), contentParts }
+}
+
+/**
+ * The contract `limit` refusals that mean "this turn carries too much", shared
+ * by the Codex and Grok providers. Both contracts word these refusals
+ * identically, so one list serves both; each contract's own tests pin its
+ * refusals (T-C, T-C2, T-C3 and T-C5, with a `-grok` suffix for Grok).
+ *
+ * Of the `fail('limit', ...)` checks on a request, only these are about
+ * conversation volume, in `llm-provider-attempt-contract/index.cjs` and
+ * `grok-provider-attempt-contract/index.cjs`: the real byte bound and its
+ * non-image share on a V2 request (both in `parse{Codex,Grok}CompletionRequestRoot`),
+ * the independent element bound (`checkStructure`), and `maxMessages` and
+ * `messages[i].toolCalls` (both in `parseMessages`).
+ * All five are request-volume refusals mapped to `ContextLengthExceeded` -
+ * "Conversation Too Long" in the UI. Compaction reaches them unevenly. The
+ * context manager counts bytes and, through the registry's `maxMessages`,
+ * the message count; it does not count JSON values. A single turn holding
+ * more than `maxMessages` messages stays unshrinkable, because the cut never
+ * lands inside a turn. A large tool definition is also not compactable.
+ * `maxToolCalls` also bounds every response, so only history produced by
+ * another provider can carry an over-long `toolCalls` array.
+ *
+ * The others are not. Nesting depth (`checkStructure`, `assertFiniteTree`),
+ * `generation.maxOutputTokens` (`parseGeneration`) and `deadlineMs`
+ * (`parse{Codex,Grok}CompletionRequestRoot`) out of range are malformed or
+ * out-of-range parameters, and a shorter conversation fixes none of them;
+ * labelling them a context-length failure would send the user into a
+ * compaction loop that cannot converge. They stay `invalid_request`, which is
+ * what "fails an over-deep tool schema locally without a stack overflow" in
+ * `subscriptionRequestHash.test.ts` pins for the over-deep schema across both
+ * providers. The image budgets belong to the attachments, not the
+ * conversation: a `size` one is `attachment_too_large` (see
+ * `ATTACHMENT_BUDGET_REFUSALS` in each provider), the `maxImages` `count` one
+ * stays `invalid_request`. The structural volume bounds
+ * (`maxRequestContainers` and `maxRequestMembers`, both from `checkStructure`)
+ * are volume too, but they are not listed: each carries `kind: 'size'`, so it
+ * reaches the user as `payload_too_large`, which classifies the same way
+ * (T-C3b for containers, T-C3d for members; the proxy's raw-body member 413 is
+ * T-C3c; `-grok` suffix for Grok).
+ *
+ * `hashCanonical{Codex,Grok}Request` also returns a `kind` (#784), but it
+ * cannot replace the message here: `size` covers the conversation bytes and the
+ * image byte budgets alike (the Codex contract adds dimension budgets), and a
+ * shorter conversation fixes the first and not the second. `count` covers
+ * `maxImages` in both contracts and `maxMessages` in the Codex one. So the
+ * message stays the discriminator at this boundary (#731). The byte pattern is
+ * a prefix so it covers the `outside image data` check of a V2 request. The
+ * element bound has its own explicit pattern.
+ *
+ * `messages exceed` is defence in depth rather than a reachable branch: the
+ * guard in each provider's `execute` raises that exact message with this same
+ * classification before `hashCanonical{Codex,Grok}Request` runs, so the
+ * contract's own copy of it only arrives here if that guard is ever removed.
+ */
+const CONTEXT_LENGTH_REFUSALS = [
+ /^request exceeds maxRequestBodyBytes/,
+ /^request exceeds maxRequestElements$/,
+ /^messages exceed \d+$/,
+ /^messages\[\d+\]\.toolCalls exceed \d+$/,
+]
+
+export function isContextLengthRefusal(code: string, message: string): boolean {
+ return code === 'limit' && CONTEXT_LENGTH_REFUSALS.some(pattern => pattern.test(message))
+}
diff --git a/mcp-host/src/llm/providerAttemptAuthorizer.ts b/mcp-host/src/llm/providerAttemptAuthorizer.ts
index e1d1615a9..d98808a22 100644
--- a/mcp-host/src/llm/providerAttemptAuthorizer.ts
+++ b/mcp-host/src/llm/providerAttemptAuthorizer.ts
@@ -50,8 +50,11 @@ function requestContract(request: unknown): RequestContract {
* revisions, hashes and recipe names, a few hundred bytes in practice. The
* contract owns the value and control-api imports the same one, so a request
* control-api would accept is never refused here for its envelope (#739).
- * This is the Codex value; a Grok request uses the Grok contract's own
- * allowance through `requestContract`.
+ * Production code does not read this export: the authorizer takes the
+ * allowance from `requestContract(request).envelopeAllowanceBytes`, which
+ * selects the Grok contract's value for a Grok request. This export is the
+ * Codex value, kept so `providerAttemptAuthorizer.test.ts` can pin it to the
+ * contract.
*/
export const AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES = ENVELOPE_ALLOWANCE_BYTES
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index 5eb69fdcb..faac5975f 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -67,16 +67,17 @@ const LIMITS = Object.freeze({
// maxRequestBodyBytes with about four million of them, and three such
// bodies at once exhaust a proxy capped at --max-old-space-size=384. In
// the Grok proxy, three ordinary bodies and one visual body at twice this
- // bound kept 197 MiB resident after a full GC (A8 measurement). A
- // conversation needs a few thousand containers; tool results are strings
- // and never count. Must equal the Codex contract's value.
+ // bound kept 197 MiB resident after a full GC. A conversation needs a few
+ // thousand containers; tool results are strings and never count. Must equal
+ // the Codex contract's value.
maxRequestContainers: 262144,
// Object members in one request, counted over every object in the tree.
// JSON.parse keeps one property slot per member, so a body of short keys
// with tiny values fits the byte cap with millions of members and exhausts
- // the proxy heap before the request is ever authorized. A realistic
- // request is about 190k members (A9 model window), and this bound leaves
- // about 1.38 times that headroom. Must equal the Codex contract's value.
+ // the proxy heap before the request is ever authorized. A request that
+ // fills a 1M-token model window is about 190k members, and this bound
+ // leaves about 1.38 times that headroom. Must equal the Codex contract's
+ // value.
maxRequestMembers: MAX_REQUEST_MEMBERS,
// Total JSON values in one request, including the root. A compact array of
// zeros fits the byte cap while JSON.parse allocates an element per value.
@@ -298,15 +299,9 @@ function requestBodyLimitBytes(request) {
}
/**
- * 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.
+ * Copy of `messages` with the `data` of every image part replaced by an empty
+ * string. Only the touched objects are copied (shallow); the input is not
+ * modified.
*/
function blankImagePayloadsInMessages(messages) {
if (!Array.isArray(messages)) return messages
@@ -322,6 +317,17 @@ function blankImagePayloadsInMessages(messages) {
})
}
+/**
+ * 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 measureNonImageRequestBytes(input) {
return Buffer.byteLength(
JSON.stringify({ ...input, messages: blankImagePayloadsInMessages(input.messages) }),
diff --git a/packages/grok-provider-attempt-contract/index.test.cjs b/packages/grok-provider-attempt-contract/index.test.cjs
index 618671d64..3aa6b3c88 100644
--- a/packages/grok-provider-attempt-contract/index.test.cjs
+++ b/packages/grok-provider-attempt-contract/index.test.cjs
@@ -1748,6 +1748,32 @@ test('the body scan admits every request the contract admits, at each bound', ()
assert.ok(scanned.structuralBytes <= contract.measureNonImageCompletionBytes(completion) + '"":"",'.length)
})
+test('the body scan treats a container holding only whitespace as empty', () => {
+ const limits = contract.BODY_STRUCTURE_LIMITS
+ for (const [json, elements] of [
+ ['[ ]', 1],
+ ['{ \n }', 1],
+ ['[\n]', 1],
+ ['[\t\r\n ]', 1],
+ ['[[ ], { \n }, [\n]]', 4],
+ // Liveness witnesses: a container with a value inside is still counted.
+ ['[ 0 ]', 2],
+ ['{ "a" : 0 }', 2],
+ ['[\n[ ]\n]', 2],
+ ]) {
+ assert.equal(contract.scanJsonStructure(Buffer.from(json), limits).elements, elements, json)
+ }
+ // The element bound sees the same counts: three whitespace-only containers in
+ // an array make 4 values, and a fourth makes 5.
+ const tight = { ...limits, maxElements: 4 }
+ assert.equal(contract.scanJsonStructure(Buffer.from('[[ ],[\n],{ }]'), tight).elements, 4)
+ assert.throws(() => contract.scanJsonStructure(Buffer.from('[[ ],[\n],{ },[]]'), tight), {
+ name: 'BodyStructureError',
+ status: 413,
+ type: 'body.structure.too.many.elements',
+ })
+})
+
test('the verify hook refuses a charset other than UTF-8 and scans UTF-8 bodies', () => {
const verify = contract.createBodyStructureVerify(contract.BODY_STRUCTURE_LIMITS)
const body = Buffer.from('{"a":[1]}')
diff --git a/packages/llm-provider-attempt-contract/index.cjs b/packages/llm-provider-attempt-contract/index.cjs
index a3e704641..f88be0d23 100644
--- a/packages/llm-provider-attempt-contract/index.cjs
+++ b/packages/llm-provider-attempt-contract/index.cjs
@@ -53,16 +53,17 @@ const LIMITS = Object.freeze({
// maxRequestBodyBytes with about four million of them, and three such
// bodies at once exhaust a proxy capped at --max-old-space-size=384. A
// conversation needs a few thousand containers; tool results are strings
- // and never count. The A8 measurement at this bound is in
+ // and never count. The memory measurement at this bound is in
// codex-llm-proxy/src/requestLimits.ts. Must equal the Grok contract's
// value.
maxRequestContainers: 262144,
// Object members in one request, counted over every object in the tree.
// JSON.parse keeps one property slot per member, so a body of short keys
// with tiny values fits the byte cap with millions of members and exhausts
- // the proxy heap before the request is ever authorized. A realistic
- // request is about 190k members (A9 model window), and this bound leaves
- // about 1.38 times that headroom. Must equal the Grok contract's value.
+ // the proxy heap before the request is ever authorized. A request that
+ // fills a 1M-token model window is about 190k members, and this bound
+ // leaves about 1.38 times that headroom. Must equal the Grok contract's
+ // value.
maxRequestMembers: 262144,
// Total JSON values in one request, including the root. A compact array of
// zeros fits the byte cap while JSON.parse allocates an element per value.
@@ -267,15 +268,9 @@ function requestBodyLimitBytes(request) {
}
/**
- * 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 24 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.
+ * Copy of `messages` with the `data` of every image part replaced by an empty
+ * string. Only the touched objects are copied (shallow); the input is not
+ * modified.
*/
function blankImagePayloadsInMessages(messages) {
if (!Array.isArray(messages)) return messages
@@ -291,6 +286,17 @@ function blankImagePayloadsInMessages(messages) {
})
}
+/**
+ * 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 24 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 measureNonImageRequestBytes(input) {
return Buffer.byteLength(
JSON.stringify({ ...input, messages: blankImagePayloadsInMessages(input.messages) }),
diff --git a/packages/llm-provider-attempt-contract/index.test.cjs b/packages/llm-provider-attempt-contract/index.test.cjs
index 3981dcd63..0bd17e1df 100644
--- a/packages/llm-provider-attempt-contract/index.test.cjs
+++ b/packages/llm-provider-attempt-contract/index.test.cjs
@@ -2028,6 +2028,32 @@ test('the body scan counts values exactly and bounds elements before JSON.parse'
})
})
+test('the body scan treats a container holding only whitespace as empty', () => {
+ const limits = contract.BODY_STRUCTURE_LIMITS
+ for (const [json, elements] of [
+ ['[ ]', 1],
+ ['{ \n }', 1],
+ ['[\n]', 1],
+ ['[\t\r\n ]', 1],
+ ['[[ ], { \n }, [\n]]', 4],
+ // Liveness witnesses: a container with a value inside is still counted.
+ ['[ 0 ]', 2],
+ ['{ "a" : 0 }', 2],
+ ['[\n[ ]\n]', 2],
+ ]) {
+ assert.equal(contract.scanJsonStructure(Buffer.from(json), limits).elements, elements, json)
+ }
+ // The element bound sees the same counts: three whitespace-only containers in
+ // an array make 4 values, and a fourth makes 5.
+ const tight = { ...limits, maxElements: 4 }
+ assert.equal(contract.scanJsonStructure(Buffer.from('[[ ],[\n],{ }]'), tight).elements, 4)
+ assert.throws(() => contract.scanJsonStructure(Buffer.from('[[ ],[\n],{ },[]]'), tight), {
+ name: 'BodyStructureError',
+ status: 413,
+ type: 'body.structure.too.many.elements',
+ })
+})
+
test('the verify hook refuses a charset other than UTF-8 and scans UTF-8 bodies', () => {
const verify = contract.createBodyStructureVerify(contract.BODY_STRUCTURE_LIMITS)
const body = Buffer.from('{"a":[1]}')