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.mdindex 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 fromCodex, whose 2048 px bound comes from its measured endpoint. The validatorchecks canonical base64, MIME/container framing and header dimensions; it doesnot decode pixels.@@ -117,7 +118,7 @@ so it never queues behind a visual stream, and a declared length above thevisual cap is refused 413 before reading. Anonymous, wrong-scope and admin requests keep theordinary limit.-**Per-principal visual share (B4).** In addition to the gate, each platform+**Per-principal visual share.** In addition to the gate, each platformidentity (`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 ornot 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 ruledoes not apply to this upgrade. #784 does tighten request-side V1 bounds: itadds `maxRequestContainers` and `maxRequestMembers` (262144 each) and lowersthe 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 Hostimages 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 flagof its own, so a #784 Host keeps sending image-bearing V2 requests; an oldercontrol-api refuses them at authorize (400 `invalid_request`, or 413 above its24 MiB route parser) and an older proxy refuses them after the attempt wasdiff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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 * 1024const GROK_ATTACHMENT_REFUSALS: Array<{name: stringdiff --git a/mcp-host/src/llm/codexSubscription.ts b/mcp-host/src/llm/codexSubscription.tsindex 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: stringtoolCalls: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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_BYTESdiff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjsindex 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.cjsindex 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.cjsindex 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.cjsindex 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]}')