Skip to content

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

TypeScript

fix(proxy): log unmapped errors, body-budget refusals and client aborts; simplify the Grok contract

Alfredo Lopez8aa81310a5ac
diff --git a/codex-llm-proxy/src/server.ts b/codex-llm-proxy/src/server.ts
index f36da2580..00e330d7b 100644
--- a/codex-llm-proxy/src/server.ts
+++ b/codex-llm-proxy/src/server.ts
@@ -144,6 +144,13 @@ function boundedErrorHandler(err: unknown, _req: Request, res: Response, _next:
reject(res, 400, 'invalid_request', type)
return
}
+ // The client closed the connection before it sent the whole body. Nobody
+ // reads a response, so none is written; the budget or visual slot is
+ // released by the response's `close` hook.
+ if (typed?.type === 'request.aborted') {
+ logger.info({ event: 'codex_proxy_request_aborted', type }, 'client aborted the request body')
+ return
+ }
// body-parser attaches the raw body to an error thrown by `verify` or by
// JSON.parse. Such an error is logged by its type and status only.
if (typed?.body !== undefined) {
@@ -247,7 +254,19 @@ function bodyAdmission(
next(err)
return
}
- if (!abort.signal.aborted) reject(res, 503, 'provider_unavailable')
+ if (abort.signal.aborted) return
+ // RequestLimitError messages are fixed strings with no request data.
+ logger.warn(
+ {
+ event: 'codex_proxy_admission_refused',
+ reason: 'body_budget',
+ code: err.code,
+ kind: err.kind,
+ detail: err.message,
+ },
+ 'admission refused'
+ )
+ reject(res, 503, 'provider_unavailable')
}
)
}
@@ -532,6 +551,8 @@ export function createProxyApps(
// Declaring V2 raises only the image budget. Text, tools and wrapper
// fields stay on the contract's maxRequestBodyBytes non-image ceiling, plus
// the same envelope allowance control-api's authorizer grants its wrapper.
+ // The min stays: `createProxyApps` accepts a config that did not pass
+ // `loadConfig` (bodyAdmission.test.ts builds one with a 16 KiB body limit).
if (
wholeBodyBytes > Math.min(configuredLimit, envelopeLimit) ||
measureNonImageCompletionBytes(req.body) >
@@ -589,8 +610,6 @@ export function createProxyApps(
// to req 'close' aborts the ChatGPT hop on every call (3–12ms canceled).
// Abort only when the client drops the response before we finish writing.
abortWhenClientDisconnects(req, res, abort)
- const visualRequest =
- (parsed.data.request as { schemaVersion?: unknown }).schemaVersion === SCHEMA_VERSION_V2
// One `codex_proxy_attempt_finished` line per attempt. Identifiers and
// counts only: never the body, ticket, frames, tool names or arguments.
const attempt = {
@@ -652,7 +671,7 @@ export function createProxyApps(
throw err
}
}
- if (visualRequest && wholeBodyBytes > config.maxBodyBytes) {
+ if (visualDeclared && wholeBodyBytes > config.maxBodyBytes) {
release = gated.codexStreamRelease
gated.codexStreamRelease = undefined
} else if (gated.codexStreamRelease) {
@@ -768,6 +787,9 @@ export function createProxyApps(
: {}),
// RequestLimitError messages are fixed strings with no request data.
...(err instanceof RequestLimitError ? { reason: err.message } : {}),
+ // An error no class above maps is a handler defect answered 503:
+ // the error itself is logged, or nothing would show it.
+ ...(isMappedError(err) ? {} : { err }),
// G1-4: a failed fetch's cause code only, never its message or URL.
...(causeCode ? { causeCode } : {}),
deliveredAs,
@@ -992,13 +1014,31 @@ function failureLabel(code: string): string {
return Object.hasOwn(ATTEMPT_ERROR_STATUS, code) ? code : 'other'
}
+type MappedError =
+ | OriginDeniedError
+ | RequestLimitError
+ | CodexTransportError
+ | ControlApiClientError
+
+/**
+ * True for the errors `mapError` answers with a status of their own. Anything
+ * else is a defect in the handler; it is answered 503 like an outage, so the
+ * caller logs the error itself to keep it visible.
+ */
+function isMappedError(err: unknown): err is MappedError {
+ return (
+ err instanceof OriginDeniedError ||
+ err instanceof RequestLimitError ||
+ err instanceof CodexTransportError ||
+ err instanceof ControlApiClientError
+ )
+}
+
function mapError(err: unknown): { status: number; code: string } {
+ if (!isMappedError(err)) return { status: 503, code: 'provider_unavailable' }
if (err instanceof OriginDeniedError) return { status: 403, code: 'origin_denied' }
if (err instanceof RequestLimitError) return { status: 503, code: 'provider_unavailable' }
- if (err instanceof CodexTransportError || err instanceof ControlApiClientError) {
- return { status: attemptErrorStatus(err.code), code: err.code }
- }
- return { status: 503, code: 'provider_unavailable' }
+ return { status: attemptErrorStatus(err.code), code: err.code }
}
/**
diff --git a/codex-llm-proxy/test/bodyAdmission.test.ts b/codex-llm-proxy/test/bodyAdmission.test.ts
index 425ef4f8b..8803b4214 100644
--- a/codex-llm-proxy/test/bodyAdmission.test.ts
+++ b/codex-llm-proxy/test/bodyAdmission.test.ts
@@ -368,9 +368,28 @@ describe('codex-llm-proxy body admission (#731 R3-2)', () => {
)
expect(await settle(proxy.redeemed)).toBe(BUDGET_BODIES)
- const overflow = await post(proxy.port, payload('overflow'))
- expect(overflow.status).toBe(503)
- expect(JSON.parse(overflow.body)).toEqual({ error: 'provider_unavailable' })
+ const warn = vi.spyOn(logger, 'warn')
+ try {
+ const overflow = await post(proxy.port, payload('overflow'))
+ // Witnesses: the refusal was answered, and the admission logged why.
+ expect(overflow.status).toBe(503)
+ expect(JSON.parse(overflow.body)).toEqual({ error: 'provider_unavailable' })
+ const logged = warn.mock.calls.map(call => call[0] as unknown as Record<string, unknown>)
+ expect(logged.filter(entry => entry?.event === 'codex_proxy_denied')).toEqual([
+ { event: 'codex_proxy_denied', code: 'provider_unavailable' },
+ ])
+ expect(logged.filter(entry => entry?.event === 'codex_proxy_admission_refused')).toEqual([
+ {
+ event: 'codex_proxy_admission_refused',
+ reason: 'body_budget',
+ code: 'provider_unavailable',
+ kind: 'queue_full',
+ detail: expect.any(String),
+ },
+ ])
+ } finally {
+ warn.mockRestore()
+ }
// Liveness: every queued request is still served once the budget frees.
proxy.releaseAll()
diff --git a/codex-llm-proxy/test/bodyStructure.test.ts b/codex-llm-proxy/test/bodyStructure.test.ts
index ba9894c5b..d27082ed7 100644
--- a/codex-llm-proxy/test/bodyStructure.test.ts
+++ b/codex-llm-proxy/test/bodyStructure.test.ts
@@ -1,5 +1,6 @@
import { generateKeyPairSync } from 'node:crypto'
import { createServer } from 'node:http'
+import { type Socket, createConnection } from 'node:net'
import jwt from 'jsonwebtoken'
import { afterEach, describe, expect, it, vi } from 'vitest'
import {
@@ -236,6 +237,33 @@ function post(
})
}
+/**
+ * Opens a connection, sends the headers of a POST that declares all of `body`
+ * and then only its first `sentBytes`. The caller closes the socket. `body`
+ * must be ASCII so a character is a byte.
+ */
+function sendPartialBody(
+ port: number,
+ body: string,
+ sentBytes: number
+): { socket: Socket; errors: Error[] } {
+ const errors: Error[] = []
+ const socket = createConnection({ host: '127.0.0.1', port })
+ socket.on('error', err => errors.push(err))
+ socket.write(
+ [
+ `POST ${COMPLETIONS_PATH} HTTP/1.1`,
+ 'Host: 127.0.0.1',
+ `Authorization: Bearer ${platformToken()}`,
+ 'Content-Type: application/json',
+ `Content-Length: ${body.length}`,
+ '',
+ body.slice(0, sentBytes),
+ ].join('\r\n')
+ )
+ return { socket, errors }
+}
+
function adminPermit(): string {
return sign(
{ sub: 'admin-1', typ: 'codex-admin-permit', operation: 'catalog_list' },
@@ -665,6 +693,74 @@ describe('codex proxy raw-body structure bounds', () => {
])
})
+ it('logs a client that leaves mid-body as an abort, not an error, and releases its budget reservation', async () => {
+ const info = vi.spyOn(logger, 'info')
+ const error = vi.spyOn(logger, 'error')
+ const acquire = vi.spyOn(BodyBudget.prototype, 'acquire')
+ const port = listen(createProxyApps(config()))
+ const body = bodyWithFiller('codex-completion-request.v1', '[]')
+
+ const client = sendPartialBody(port, body, Math.floor(body.length / 2))
+ // Witness: the body holds its reservation while it is being read.
+ await waitFor(() => acquire.mock.calls.length === 1, 'the body took no budget')
+ const budget = acquire.mock.contexts[0] as BodyBudget
+ await waitFor(() => budget.inFlightBytes === body.length, 'the body was not granted its bytes')
+
+ client.socket.destroy()
+ const aborted = (): unknown[] =>
+ info.mock.calls
+ .map(([entry]) => entry)
+ .filter(
+ entry =>
+ (entry as { event?: unknown } | undefined)?.event === 'codex_proxy_request_aborted'
+ )
+ await waitFor(() => aborted().length === 1, 'the abort was not logged')
+ expect(aborted()).toEqual([{ event: 'codex_proxy_request_aborted', type: 'request.aborted' }])
+ await waitFor(() => budget.inFlightBytes === 0, 'the reservation was not released')
+
+ // Witness: the budget is usable, a follow-up body is admitted and reaches the ticket check.
+ const admitted = await post(port, body)
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(error).not.toHaveBeenCalled()
+ expect(client.errors).toEqual([])
+ }, 15_000)
+
+ it('logs a client that leaves mid-way through a visual body as an abort and frees the visual slot', async () => {
+ const info = vi.spyOn(logger, 'info')
+ const error = vi.spyOn(logger, 'error')
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
+ const compact = bodyWithFiller('codex-completion-request.v2', '[]')
+ const body = `${compact}${' '.repeat(4096)}`
+ expect(body.length).toBeGreaterThan(4096)
+
+ const client = sendPartialBody(port, body, Math.floor(body.length / 2))
+ // Witness: the body holds the visual slot while it is being read.
+ await waitFor(() => visualStreamGate.snapshot().running === 1, 'the body took no visual slot')
+
+ client.socket.destroy()
+ const aborted = (): unknown[] =>
+ info.mock.calls
+ .map(([entry]) => entry)
+ .filter(
+ entry =>
+ (entry as { event?: unknown } | undefined)?.event === 'codex_proxy_request_aborted'
+ )
+ await waitFor(() => aborted().length === 1, 'the abort was not logged')
+ expect(aborted()).toEqual([{ event: 'codex_proxy_request_aborted', type: 'request.aborted' }])
+ await waitFor(() => visualStreamGate.snapshot().running === 0, 'the visual slot was not released')
+
+ // Witness: the gate is usable, a follow-up body takes the slot and reaches the ticket check.
+ const admitted = await post(port, body)
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(error).not.toHaveBeenCalled()
+ expect(client.errors).toEqual([])
+ }, 15_000)
+
it('logs only the type and status of an unmapped verify error', async () => {
const warn = vi.spyOn(logger, 'warn')
const error = vi.spyOn(logger, 'error')
diff --git a/codex-llm-proxy/test/server.security.test.ts b/codex-llm-proxy/test/server.security.test.ts
index 92bd05235..742acfb7c 100644
--- a/codex-llm-proxy/test/server.security.test.ts
+++ b/codex-llm-proxy/test/server.security.test.ts
@@ -1342,6 +1342,65 @@ describe('codex-llm-proxy attempt telemetry', () => {
})) as typeof fetch
}
+ it('logs the error of an unmapped handler failure while it still answers 503 provider_unavailable', async () => {
+ const boom = new Error('boom')
+ const failingClient = {
+ async redeem(): Promise<RedeemAttemptSuccess> {
+ throw boom
+ },
+ async finalize(): Promise<FinalizeAttemptSuccess> {
+ throw new Error('finalize must not run after a failed redeem')
+ },
+ } as unknown as ControlApiClient
+ const { res, lines } = await run('att-unmapped-error', 0, 0, undefined, undefined, {
+ controlApiClient: failingClient,
+ })
+ // Witnesses: the request reached the handler's catch and was logged once.
+ expect(res.status).toBe(503)
+ expect(res.body).toEqual({ error: 'provider_unavailable' })
+ expect(lines).toHaveLength(1)
+ expect(lines[0]).toMatchObject({
+ providerAttemptId: 'att-unmapped-error',
+ outcome: 'failed',
+ code: 'provider_unavailable',
+ httpStatus: 503,
+ })
+ expect(lines[0]?.err).toBe(boom)
+ })
+
+ it('logs a mapped transport failure without an err entry', async () => {
+ const { res, lines } = await run('att-mapped-transport-error', 0, 0, undefined, undefined, {
+ fetchFn: rateLimitedUpstream('7'),
+ })
+ // Witnesses: the failure reached the same catch and produced its attempt line.
+ expect(res.status).toBe(429)
+ expect(lines).toHaveLength(1)
+ expect(lines[0]).toMatchObject({
+ providerAttemptId: 'att-mapped-transport-error',
+ outcome: 'failed',
+ code: 'rate_limited',
+ })
+ expect('err' in (lines[0] ?? {})).toBe(false)
+ })
+
+ it('logs a mapped control-api failure without an err entry', async () => {
+ const { res, lines } = await run(
+ 'att-mapped-control-api-error',
+ 0,
+ 0,
+ undefined,
+ 'ticket_expired'
+ )
+ expect(res.status).toBeGreaterThanOrEqual(400)
+ expect(lines).toHaveLength(1)
+ expect(lines[0]).toMatchObject({
+ providerAttemptId: 'att-mapped-control-api-error',
+ outcome: 'failed',
+ code: 'ticket_expired',
+ })
+ expect('err' in (lines[0] ?? {})).toBe(false)
+ })
+
it('(g1-1a) answers 429 rate_limited and forwards a valid upstream Retry-After', async () => {
const { res, receipts, lines, metricsText } = await run(
'att-rate-http',
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 6e248e919..367afda39 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.654",
+ "version": "0.1.655",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.654",
+ "version": "0.1.655",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index 182cc1cf8..924123efd 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.654",
+ "version": "0.1.655",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts b/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
index 1cb8d623c..56df2364b 100644
--- a/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
+++ b/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
@@ -39,7 +39,7 @@ type MergedBodyStructureLimits = Readonly<
Record<keyof typeof BODY_STRUCTURE_LIMITS | keyof typeof GROK_BODY_STRUCTURE_LIMITS, number>
>
-function mergeBodyStructureLimits(
+export function mergeBodyStructureLimits(
...contracts: ReadonlyArray<Readonly<Record<string, number>>>
): MergedBodyStructureLimits {
const merged: Record<string, number> = {}
diff --git a/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts b/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
index 98bc5f3b7..5b0476eb4 100644
--- a/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
+++ b/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
@@ -15,6 +15,7 @@ import {
import {
MCP_HOST_BODY_STRUCTURE_LIMITS,
createMcpHostLlmProviderAttemptRoutes,
+ mergeBodyStructureLimits,
resolveHostAssignedAssignment,
} from '../src/routes/mcp-host/llmProviderAttempts.routes.js'
import { LlmProviderAttemptAuthorizeError } from '../src/services/llmProviderAttemptAuthorizer.js'
@@ -461,6 +462,18 @@ describe('authorize raw-body scan before JSON.parse', () => {
}
})
+ it('takes the larger value per key when the two contracts diverge, in either order', () => {
+ // Both contracts are equal today, so the merge over the real limits cannot
+ // tell a maximum from a copy of one input. Diverging inputs can: each
+ // contract holds the larger value for one key, and each holds a key alone.
+ const first = { maxContainers: 10, maxDepth: 90, onlyFirst: 3 }
+ const second = { maxContainers: 40, maxDepth: 70, onlySecond: 5 }
+ const expected = { maxContainers: 40, maxDepth: 90, onlyFirst: 3, onlySecond: 5 }
+ expect(mergeBodyStructureLimits(first, second)).toEqual(expected)
+ expect(mergeBodyStructureLimits(second, first)).toEqual(expected)
+ expect(Object.isFrozen(mergeBodyStructureLimits(first, second))).toBe(true)
+ })
+
it('refuses a gzip body and a non-UTF-8 charset with 415 without reading them as JSON', async () => {
const json = JSON.stringify({ request: { schemaVersion: 'codex-completion-request.v1' } })
await withRoute(async url => {
diff --git a/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts b/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
index fe7b812ba..a2b113633 100644
--- a/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
+++ b/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
@@ -6,7 +6,6 @@ import {
LIMITS,
computeGrokPolicyHash,
hashGrokCompletionRequest,
- hashGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
import { config } from '../src/config.js'
import {
@@ -305,7 +304,7 @@ describe('authorizeLlmProviderAttempt grok-subscription', () => {
expect(result).toMatchObject({
providerAttemptId: '33333333-3333-4333-8333-333333333333',
executionTicket: 'grok-ticket.jwt',
- requestHash: hashGrokCompletionRequestV1(REQUEST),
+ requestHash: hashGrokCompletionRequest(REQUEST),
})
expect(grokRepos.getConnection).toHaveBeenCalledWith(expect.anything(), 'team-grok')
expect(current.evaluateBudget).toHaveBeenCalledWith(
@@ -439,7 +438,7 @@ describe('authorizeLlmProviderAttempt grok-subscription', () => {
const result = await authorizeLlmProviderAttempt(claims(), payload, current)
expect(result).toMatchObject({
executionTicket: 'grok-ticket.jwt',
- requestHash: hashGrokCompletionRequestV1(request),
+ requestHash: hashGrokCompletionRequest(request),
})
expect(current.insertAttempt).toHaveBeenCalledTimes(1)
})
diff --git a/grok-llm-proxy/src/server.ts b/grok-llm-proxy/src/server.ts
index 7d4c3168d..034661742 100644
--- a/grok-llm-proxy/src/server.ts
+++ b/grok-llm-proxy/src/server.ts
@@ -148,6 +148,13 @@ function boundedErrorHandler(err: unknown, _req: Request, res: Response, _next:
reject(res, 400, 'invalid_request', type)
return
}
+ // The client closed the connection before it sent the whole body. Nobody
+ // reads a response, so none is written; the budget or visual slot is
+ // released by the response's `close` hook.
+ if (typed?.type === 'request.aborted') {
+ logger.info({ event: 'grok_proxy_request_aborted', type }, 'client aborted the request body')
+ return
+ }
// body-parser attaches the raw body to an error thrown by `verify` or by
// JSON.parse. Such an error is logged by its type and status only.
if (typed?.body !== undefined) {
@@ -250,7 +257,19 @@ function bodyAdmission(
next(err)
return
}
- if (!abort.signal.aborted) reject(res, 503, 'provider_unavailable')
+ if (abort.signal.aborted) return
+ // RequestLimitError messages are fixed strings with no request data.
+ logger.warn(
+ {
+ event: 'grok_proxy_admission_refused',
+ reason: 'body_budget',
+ code: err.code,
+ kind: err.kind,
+ detail: err.message,
+ },
+ 'admission refused'
+ )
+ reject(res, 503, 'provider_unavailable')
}
)
}
@@ -544,6 +563,8 @@ export function createProxyApps(
// Declaring V2 raises only the image budget. Text, tools and wrapper
// fields stay on the contract's maxRequestBodyBytes non-image ceiling, plus
// the same envelope allowance control-api's authorizer grants its wrapper.
+ // The min stays: `createProxyApps` accepts a config that did not pass
+ // `loadConfig` (bodyAdmission.test.ts builds one with a 16 KiB body limit).
if (
wholeBodyBytes > Math.min(configuredLimit, envelopeLimit) ||
measureNonImageCompletionBytes(req.body) >
@@ -601,8 +622,6 @@ export function createProxyApps(
// to req 'close' aborts the Grok hop on every call (3–12ms canceled).
// Abort only when the client drops the response before we finish writing.
abortWhenClientDisconnects(req, res, abort)
- const visualRequest =
- (parsed.data.request as { schemaVersion?: unknown }).schemaVersion === SCHEMA_VERSION_V2
// One `grok_proxy_attempt_finished` line per attempt. Identifiers and
// counts only: never the body, ticket, frames, tool names or arguments.
const attempt = {
@@ -664,7 +683,7 @@ export function createProxyApps(
throw err
}
}
- if (visualRequest && wholeBodyBytes > config.maxBodyBytes) {
+ if (visualDeclared && wholeBodyBytes > config.maxBodyBytes) {
release = gated.grokStreamRelease
gated.grokStreamRelease = undefined
} else if (gated.grokStreamRelease) {
@@ -780,6 +799,9 @@ export function createProxyApps(
: {}),
// RequestLimitError messages are fixed strings with no request data.
...(err instanceof RequestLimitError ? { reason: err.message } : {}),
+ // An error no class above maps is a handler defect answered 503:
+ // the error itself is logged, or nothing would show it.
+ ...(isMappedError(err) ? {} : { err }),
// G1-4: a failed fetch's cause code only, never its message or URL.
...(causeCode ? { causeCode } : {}),
deliveredAs,
@@ -1009,13 +1031,31 @@ function failureLabel(code: string): string {
return Object.hasOwn(ATTEMPT_ERROR_STATUS, code) ? code : 'other'
}
+type MappedError =
+ | OriginDeniedError
+ | RequestLimitError
+ | GrokTransportError
+ | ControlApiClientError
+
+/**
+ * True for the errors `mapError` answers with a status of their own. Anything
+ * else is a defect in the handler; it is answered 503 like an outage, so the
+ * caller logs the error itself to keep it visible.
+ */
+function isMappedError(err: unknown): err is MappedError {
+ return (
+ err instanceof OriginDeniedError ||
+ err instanceof RequestLimitError ||
+ err instanceof GrokTransportError ||
+ err instanceof ControlApiClientError
+ )
+}
+
function mapError(err: unknown): { status: number; code: string } {
+ if (!isMappedError(err)) return { status: 503, code: 'provider_unavailable' }
if (err instanceof OriginDeniedError) return { status: 403, code: 'origin_denied' }
if (err instanceof RequestLimitError) return { status: 503, code: 'provider_unavailable' }
- if (err instanceof GrokTransportError || err instanceof ControlApiClientError) {
- return { status: attemptErrorStatus(err.code), code: err.code }
- }
- return { status: 503, code: 'provider_unavailable' }
+ return { status: attemptErrorStatus(err.code), code: err.code }
}
/**
diff --git a/grok-llm-proxy/test/bodyAdmission.test.ts b/grok-llm-proxy/test/bodyAdmission.test.ts
index 83200587b..7e4ff9bc9 100644
--- a/grok-llm-proxy/test/bodyAdmission.test.ts
+++ b/grok-llm-proxy/test/bodyAdmission.test.ts
@@ -18,7 +18,7 @@ import type { AddressInfo } from 'node:net'
import { gzipSync } from 'node:zlib'
import {
LIMITS,
- hashGrokCompletionRequestV1,
+ hashGrokCompletionRequest,
parseGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
import type { GrokLlmProxyConfig } from '../src/config.js'
@@ -105,7 +105,7 @@ function completionBody(contentChars: number, attempt: string, ticketLifetimeSec
}
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
return JSON.stringify({
executionTicket: sign(
{
@@ -367,9 +367,28 @@ describe('grok-llm-proxy body admission (#731 R3-2)', () => {
)
expect(await settle(proxy.redeemed)).toBe(BUDGET_BODIES)
- const overflow = await post(proxy.port, payload('overflow'))
- expect(overflow.status).toBe(503)
- expect(JSON.parse(overflow.body)).toEqual({ error: 'provider_unavailable' })
+ const warn = vi.spyOn(logger, 'warn')
+ try {
+ const overflow = await post(proxy.port, payload('overflow'))
+ // Witnesses: the refusal was answered, and the admission logged why.
+ expect(overflow.status).toBe(503)
+ expect(JSON.parse(overflow.body)).toEqual({ error: 'provider_unavailable' })
+ const logged = warn.mock.calls.map(call => call[0] as unknown as Record<string, unknown>)
+ expect(logged.filter(entry => entry?.event === 'grok_proxy_denied')).toEqual([
+ { event: 'grok_proxy_denied', code: 'provider_unavailable' },
+ ])
+ expect(logged.filter(entry => entry?.event === 'grok_proxy_admission_refused')).toEqual([
+ {
+ event: 'grok_proxy_admission_refused',
+ reason: 'body_budget',
+ code: 'provider_unavailable',
+ kind: 'queue_full',
+ detail: expect.any(String),
+ },
+ ])
+ } finally {
+ warn.mockRestore()
+ }
// Liveness: every queued request is still served once the budget frees.
proxy.releaseAll()
diff --git a/grok-llm-proxy/test/bodyStructure.test.ts b/grok-llm-proxy/test/bodyStructure.test.ts
index 0966eb3f5..67bf7dd6b 100644
--- a/grok-llm-proxy/test/bodyStructure.test.ts
+++ b/grok-llm-proxy/test/bodyStructure.test.ts
@@ -1,5 +1,6 @@
import { generateKeyPairSync } from 'node:crypto'
import { createServer } from 'node:http'
+import { type Socket, createConnection } from 'node:net'
import jwt from 'jsonwebtoken'
import { afterEach, describe, expect, it, vi } from 'vitest'
import {
@@ -236,6 +237,33 @@ function post(
})
}
+/**
+ * Opens a connection, sends the headers of a POST that declares all of `body`
+ * and then only its first `sentBytes`. The caller closes the socket. `body`
+ * must be ASCII so a character is a byte.
+ */
+function sendPartialBody(
+ port: number,
+ body: string,
+ sentBytes: number
+): { socket: Socket; errors: Error[] } {
+ const errors: Error[] = []
+ const socket = createConnection({ host: '127.0.0.1', port })
+ socket.on('error', err => errors.push(err))
+ socket.write(
+ [
+ `POST ${COMPLETIONS_PATH} HTTP/1.1`,
+ 'Host: 127.0.0.1',
+ `Authorization: Bearer ${platformToken()}`,
+ 'Content-Type: application/json',
+ `Content-Length: ${body.length}`,
+ '',
+ body.slice(0, sentBytes),
+ ].join('\r\n')
+ )
+ return { socket, errors }
+}
+
function adminPermit(): string {
return sign(
{ sub: 'admin-1', typ: 'grok-admin-permit', operation: 'catalog_list' },
@@ -662,6 +690,74 @@ describe('grok proxy raw-body structure bounds', () => {
])
})
+ it('logs a client that leaves mid-body as an abort, not an error, and releases its budget reservation', async () => {
+ const info = vi.spyOn(logger, 'info')
+ const error = vi.spyOn(logger, 'error')
+ const acquire = vi.spyOn(BodyBudget.prototype, 'acquire')
+ const port = listen(createProxyApps(config()))
+ const body = bodyWithFiller('grok-completion-request.v1', '[]')
+
+ const client = sendPartialBody(port, body, Math.floor(body.length / 2))
+ // Witness: the body holds its reservation while it is being read.
+ await waitFor(() => acquire.mock.calls.length === 1, 'the body took no budget')
+ const budget = acquire.mock.contexts[0] as BodyBudget
+ await waitFor(() => budget.inFlightBytes === body.length, 'the body was not granted its bytes')
+
+ client.socket.destroy()
+ const aborted = (): unknown[] =>
+ info.mock.calls
+ .map(([entry]) => entry)
+ .filter(
+ entry =>
+ (entry as { event?: unknown } | undefined)?.event === 'grok_proxy_request_aborted'
+ )
+ await waitFor(() => aborted().length === 1, 'the abort was not logged')
+ expect(aborted()).toEqual([{ event: 'grok_proxy_request_aborted', type: 'request.aborted' }])
+ await waitFor(() => budget.inFlightBytes === 0, 'the reservation was not released')
+
+ // Witness: the budget is usable, a follow-up body is admitted and reaches the ticket check.
+ const admitted = await post(port, body)
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(error).not.toHaveBeenCalled()
+ expect(client.errors).toEqual([])
+ }, 15_000)
+
+ it('logs a client that leaves mid-way through a visual body as an abort and frees the visual slot', async () => {
+ const info = vi.spyOn(logger, 'info')
+ const error = vi.spyOn(logger, 'error')
+ const acquire = vi.spyOn(visualStreamGate, 'acquire')
+ const port = listen(createProxyApps(config({ maxBodyBytes: 4096 })))
+ const compact = bodyWithFiller('grok-completion-request.v2', '[]')
+ const body = `${compact}${' '.repeat(4096)}`
+ expect(body.length).toBeGreaterThan(4096)
+
+ const client = sendPartialBody(port, body, Math.floor(body.length / 2))
+ // Witness: the body holds the visual slot while it is being read.
+ await waitFor(() => visualStreamGate.snapshot().running === 1, 'the body took no visual slot')
+
+ client.socket.destroy()
+ const aborted = (): unknown[] =>
+ info.mock.calls
+ .map(([entry]) => entry)
+ .filter(
+ entry =>
+ (entry as { event?: unknown } | undefined)?.event === 'grok_proxy_request_aborted'
+ )
+ await waitFor(() => aborted().length === 1, 'the abort was not logged')
+ expect(aborted()).toEqual([{ event: 'grok_proxy_request_aborted', type: 'request.aborted' }])
+ await waitFor(() => visualStreamGate.snapshot().running === 0, 'the visual slot was not released')
+
+ // Witness: the gate is usable, a follow-up body takes the slot and reaches the ticket check.
+ const admitted = await post(port, body)
+ expect(admitted.status).toBe(403)
+ expect(await admitted.json()).toEqual({ error: 'ticket_invalid' })
+ expect(acquire).toHaveBeenCalledTimes(2)
+ expect(error).not.toHaveBeenCalled()
+ expect(client.errors).toEqual([])
+ }, 15_000)
+
it('logs only the type and status of an unmapped verify error', async () => {
const warn = vi.spyOn(logger, 'warn')
const error = vi.spyOn(logger, 'error')
diff --git a/grok-llm-proxy/test/deployManifest.test.ts b/grok-llm-proxy/test/deployManifest.test.ts
index 5a2c464a2..c0f4e83f1 100644
--- a/grok-llm-proxy/test/deployManifest.test.ts
+++ b/grok-llm-proxy/test/deployManifest.test.ts
@@ -30,6 +30,11 @@ const SHUTDOWN_MARGIN_SECONDS = 20
* (#739 measured 509.8);
* - D5 plus the visual slot (#784): the same load and one ~36 MB V2 stream
* (a 20 MiB PNG and 8 MiB of text), 775.4 MiB.
+ * Both were measured by hand, not by this suite. The 775.4 is the largest of
+ * three runs (771.3, 775.4, 765 MiB), taken on 2026-09-24 on macOS with
+ * Node v24.18.0 and recorded in the message of the commit that introduced
+ * this constant (`git log -S775.4 -- grok-llm-proxy/test/deployManifest.test.ts`).
+ * Re-measure before changing it.
*/
const CAPPED_PEAK_RSS_MIB = 775.4
const MEMORY_HEADROOM = 1.25
diff --git a/grok-llm-proxy/test/grokTransport.conformance.test.ts b/grok-llm-proxy/test/grokTransport.conformance.test.ts
index 27499de2a..4231c4e6b 100644
--- a/grok-llm-proxy/test/grokTransport.conformance.test.ts
+++ b/grok-llm-proxy/test/grokTransport.conformance.test.ts
@@ -6,7 +6,6 @@ import {
LIMITS,
type GrokCompletionRequestV2,
hashGrokCompletionRequest,
- hashGrokCompletionRequestV1,
parseGrokCompletionRequest,
parseGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
@@ -56,7 +55,7 @@ function headerOf(init: RequestInit | undefined, name: string): string | undefin
return (init?.headers as Record<string, string> | undefined)?.[name]
}
-const REQUEST_HASH = hashGrokCompletionRequestV1(REQUEST)
+const REQUEST_HASH = hashGrokCompletionRequest(REQUEST)
function accessTokenFor(label: string): string {
const encoded = Buffer.from(
@@ -1366,7 +1365,7 @@ describe('streamGrokCompletion', () => {
generation: { toolChoice: 'auto' as const },
transportHints: { promptCacheKey: 'sess-1' },
}
- const requestHash = hashGrokCompletionRequestV1(request)
+ const requestHash = hashGrokCompletionRequest(request)
const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
@@ -1431,7 +1430,7 @@ describe('streamGrokCompletion', () => {
{ role: 'tool' as const, content: 'previous result', toolCallId: 'previous', name },
],
}
- const requestHash = hashGrokCompletionRequestV1(request)
+ const requestHash = hashGrokCompletionRequest(request)
expect(parseGrokCompletionRequestV1(request).ok).toBe(true)
const original = structuredClone(request)
const emitted: unknown[] = []
@@ -1495,7 +1494,7 @@ describe('streamGrokCompletion', () => {
expect(result.outcome).toBe('success')
expect(emitted).toContainEqual({ type: 'tool_call', id: 'new-call', name, arguments: {} })
expect(request).toEqual(original)
- expect(hashGrokCompletionRequestV1(request)).toBe(requestHash)
+ expect(hashGrokCompletionRequest(request)).toBe(requestHash)
})
it('rejects an unregistered alias in a completed stream before emitting any calls', async () => {
@@ -1509,7 +1508,7 @@ describe('streamGrokCompletion', () => {
...REQUEST,
tools: [{ name: 'known.read', description: 'Read a record', parameters: { type: 'object' } }],
}
- const requestHash = hashGrokCompletionRequestV1(request)
+ const requestHash = hashGrokCompletionRequest(request)
const fetchFn = vi.fn(async (_url: unknown, init?: RequestInit) => {
const body = JSON.parse(String(init?.body))
return sseResponse([
@@ -1599,7 +1598,7 @@ describe('streamGrokCompletion', () => {
],
generation: { maxOutputTokens: 4096, temperature: 0.2 },
}
- const requestHash = hashGrokCompletionRequestV1(request)
+ const requestHash = hashGrokCompletionRequest(request)
const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
@@ -1632,7 +1631,7 @@ describe('streamGrokCompletion', () => {
// until a live SuperGrok probe confirms /v1/responses accepts it.
expect(GROK_UPSTREAM_TEMPERATURE_PROBE_CONFIRMED).toBe(false)
expect(body).not.toHaveProperty('temperature')
- expect(hashGrokCompletionRequestV1(request)).toBe(requestHash)
+ expect(hashGrokCompletionRequest(request)).toBe(requestHash)
expect(body).not.toHaveProperty('text')
expect(body).not.toHaveProperty('service_tier')
})
diff --git a/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts b/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
index 2fb06a27e..ad75b109a 100644
--- a/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
+++ b/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
@@ -26,7 +26,7 @@ import { type IncomingMessage, type Server, type ServerResponse, createServer }
import type { AddressInfo } from 'node:net'
import request from 'supertest'
import {
- hashGrokCompletionRequestV1,
+ hashGrokCompletionRequest,
parseGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
import type { GrokLlmProxyConfig } from '../src/config.js'
@@ -322,7 +322,7 @@ describe('hermetic Grok authorize → proxy → fixture upstream → finalize',
const original = structuredClone(raw)
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
const providerAttemptId = 'att-hermetic-grok-1'
const res = await request(servers.runtimeApp)
@@ -394,7 +394,7 @@ describe('hermetic Grok authorize → proxy → fixture upstream → finalize',
const raw = completionRequest()
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
const res = await request(servers.runtimeApp)
.post('/internal/runtime/v1/grok/completions')
@@ -449,7 +449,7 @@ describe('hermetic Grok authorize → proxy → fixture upstream → finalize',
const raw = completionRequest()
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
const res = await request(servers.runtimeApp)
.post('/internal/runtime/v1/grok/completions')
@@ -495,7 +495,7 @@ describe('hermetic per-response tool-call limit', () => {
const raw = { ...completionRequest(), tools: [structuredClone(UPDATE_TOOL)] }
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
const res = await request(proxy.runtimeApp)
.post('/internal/runtime/v1/grok/completions')
.set('Authorization', `Bearer ${platformToken(RECIPE_HOST_REF)}`)
diff --git a/grok-llm-proxy/test/server.security.test.ts b/grok-llm-proxy/test/server.security.test.ts
index f1bb49153..797f799d8 100644
--- a/grok-llm-proxy/test/server.security.test.ts
+++ b/grok-llm-proxy/test/server.security.test.ts
@@ -8,7 +8,6 @@ import {
ENVELOPE_ALLOWANCE_BYTES as CONTRACT_ENVELOPE_ALLOWANCE_BYTES,
LIMITS,
hashGrokCompletionRequest,
- hashGrokCompletionRequestV1,
parseGrokCompletionRequest,
parseGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
@@ -658,7 +657,7 @@ describe('grok-llm-proxy execution kill switch', () => {
}
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
const executionTicket = sign(
{
jti: '33333333-3333-4333-8333-333333333333',
@@ -968,7 +967,7 @@ describe('grok-llm-proxy attempt telemetry', () => {
}
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
// Applied after hashing: the ticket stays bound to the untampered request,
// so the transport's parser rejects the body before any hash comparison.
tamper?.(raw)
@@ -1310,6 +1309,64 @@ describe('grok-llm-proxy attempt telemetry', () => {
})) as typeof fetch
}
+ it('logs the error of an unmapped handler failure while it still answers 503 provider_unavailable', async () => {
+ const boom = new Error('boom')
+ const failingClient = {
+ async redeem(): Promise<RedeemAttemptSuccess> {
+ throw boom
+ },
+ async finalize(): Promise<FinalizeAttemptSuccess> {
+ throw new Error('finalize must not run after a failed redeem')
+ },
+ } as unknown as ControlApiClient
+ const { res, lines } = await run({
+ providerAttemptId: 'att-unmapped-error',
+ controlApiClient: failingClient,
+ })
+ // Witnesses: the request reached the handler's catch and was logged once.
+ expect(res.status).toBe(503)
+ expect(res.body).toEqual({ error: 'provider_unavailable' })
+ expect(lines).toHaveLength(1)
+ expect(lines[0]).toMatchObject({
+ providerAttemptId: 'att-unmapped-error',
+ outcome: 'failed',
+ code: 'provider_unavailable',
+ httpStatus: 503,
+ })
+ expect(lines[0]?.err).toBe(boom)
+ })
+
+ it('logs a mapped transport failure without an err entry', async () => {
+ const { res, lines } = await run({
+ providerAttemptId: 'att-mapped-transport-error',
+ fetchFn: rateLimitedUpstream('7'),
+ })
+ // Witnesses: the failure reached the same catch and produced its attempt line.
+ expect(res.status).toBe(429)
+ expect(lines).toHaveLength(1)
+ expect(lines[0]).toMatchObject({
+ providerAttemptId: 'att-mapped-transport-error',
+ outcome: 'failed',
+ code: 'rate_limited',
+ })
+ expect('err' in (lines[0] ?? {})).toBe(false)
+ })
+
+ it('logs a mapped control-api failure without an err entry', async () => {
+ const { res, lines } = await run({
+ providerAttemptId: 'att-mapped-control-api-error',
+ deniedCode: 'ticket_expired',
+ })
+ expect(res.status).toBeGreaterThanOrEqual(400)
+ expect(lines).toHaveLength(1)
+ expect(lines[0]).toMatchObject({
+ providerAttemptId: 'att-mapped-control-api-error',
+ outcome: 'failed',
+ code: 'ticket_expired',
+ })
+ expect('err' in (lines[0] ?? {})).toBe(false)
+ })
+
it('(g1-1a) answers 429 rate_limited and forwards a valid upstream Retry-After', async () => {
const { res, receipts, lines, metricsText } = await run({
providerAttemptId: 'att-rate-http',
@@ -1970,7 +2027,7 @@ describe('grok-llm-proxy ticket-aware stream-gate wait (#739 D1-bis)', () => {
}
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
const executionTicket = jwt.sign(
{
jti: '77777777-7777-4777-8777-777777777777',
@@ -2281,7 +2338,7 @@ describe('grok-llm-proxy body budget release on upstream acceptance (#739 D2)',
}
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
return JSON.stringify({
executionTicket:
executionTicket ??
@@ -2633,7 +2690,7 @@ describe('grok-llm-proxy graceful drain on shutdown (#739 D6)', () => {
}
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
const executionTicket = sign(
{
jti: '99999999-9999-4999-8999-999999999999',
diff --git a/grok-llm-proxy/test/sseBackpressure.test.ts b/grok-llm-proxy/test/sseBackpressure.test.ts
index 49a10e3dd..1ea7df3e7 100644
--- a/grok-llm-proxy/test/sseBackpressure.test.ts
+++ b/grok-llm-proxy/test/sseBackpressure.test.ts
@@ -5,7 +5,7 @@ import { EventEmitter } from 'node:events'
import { request as httpRequest } from 'node:http'
import type { AddressInfo } from 'node:net'
import {
- hashGrokCompletionRequestV1,
+ hashGrokCompletionRequest,
parseGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
import type { GrokLlmProxyConfig } from '../src/config.js'
@@ -122,7 +122,7 @@ describe('slow SSE consumer', () => {
}
const parsed = parseGrokCompletionRequestV1(raw)
if (!parsed.ok) throw new Error(parsed.message)
- const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
const finalizes: string[] = []
const client = {
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 4a3694e8a..1c438ffc3 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.471",
+ "version": "0.1.472",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.471",
+ "version": "0.1.472",
"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 5fb1bfddd..d0972e591 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.471",
+ "version": "0.1.472",
"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__/attachmentBudgetRefusal.test.ts b/mcp-host/src/llm/__tests__/attachmentBudgetRefusal.test.ts
index cf3a7968e..785b92fb0 100644
--- a/mcp-host/src/llm/__tests__/attachmentBudgetRefusal.test.ts
+++ b/mcp-host/src/llm/__tests__/attachmentBudgetRefusal.test.ts
@@ -133,12 +133,49 @@ const CODEX = {
}
// The one message no request can produce today: Codex `maxImagePixels` equals
-// `maxImageDimension` squared and the dimension check runs first. It is written
-// in the shape of the dimension message the contract does produce.
-const CODEX_PIXELS = CODEX.dimension.replace(
- `image dimension exceeds ${CODEX_VISUAL_LIMITS.maxImageDimension}`,
- `image pixel count exceeds ${CODEX_VISUAL_LIMITS.maxImagePixels}`
+// `maxImageDimension` squared and the dimension check runs first, so the
+// contract's pixel refusal is unreachable through `hashCanonicalCodexRequest`.
+// Its wording is read from the contract source, not copied: the template is
+// located in `visualPayload.cjs` and filled with the real limit, so a reworded
+// contract message stops this suite at load instead of leaving a stale copy.
+const codexPixelTemplate = /`(image pixel count exceeds \$\{VISUAL_LIMITS\.maxImagePixels\})`/.exec(
+ readFileSync(
+ join(__dirname, '../../../../packages/llm-provider-attempt-contract/visualPayload.cjs'),
+ 'utf8'
+ )
)
+if (!codexPixelTemplate) {
+ throw new Error('the Codex contract no longer has an image pixel count refusal')
+}
+const CODEX_PIXELS = `messages[0].contentParts[1]: ${codexPixelTemplate[1].replace(
+ /\$\{VISUAL_LIMITS\.maxImagePixels\}/,
+ String(CODEX_VISUAL_LIMITS.maxImagePixels)
+)}`
+
+/**
+ * Every row of `table` matches exactly one of the contract's image refusal
+ * `messages`, and every message matches exactly one row, so a row cannot be
+ * added, dropped or left matching nothing without this failing.
+ */
+function expectTableCoversExactly(
+ table: ReadonlyArray<{ pattern: RegExp }>,
+ messages: readonly string[]
+): void {
+ expect(messages.length).toBeGreaterThan(0)
+ expect(table.length).toBe(messages.length)
+ for (const message of messages) {
+ expect(
+ table.filter(row => row.pattern.test(message)),
+ message
+ ).toHaveLength(1)
+ }
+ for (const row of table) {
+ expect(
+ messages.filter(message => row.pattern.test(message)),
+ String(row.pattern)
+ ).toHaveLength(1)
+ }
+}
describe('attachmentBudgetRefusal (#784)', () => {
it('names the Grok limits in the per-image, total and whole-body sentences', () => {
@@ -166,8 +203,14 @@ describe('attachmentBudgetRefusal (#784)', () => {
expect(attachmentBudgetRefusalMessageFor(CODEX_TABLE, CODEX_PIXELS, true)).toBe(
`An attached image is too large: it has more than ${CODEX_VISUAL_LIMITS.maxImagePixels.toLocaleString('en-US')} pixels. Resize it and send it again.`
)
- expect(GROK_TABLE).toHaveLength(3)
- expect(CODEX_TABLE).toHaveLength(5)
+ expectTableCoversExactly(GROK_TABLE, [GROK.perImage, GROK.total, GROK.visualBody])
+ expectTableCoversExactly(CODEX_TABLE, [
+ CODEX.perImage,
+ CODEX.dimension,
+ CODEX_PIXELS,
+ CODEX.total,
+ CODEX.visualBody,
+ ])
expect(attachmentBudgetRefusalMessageFor(GROK_TABLE, CODEX.dimension, true)).toBeUndefined()
expect(attachmentBudgetRefusalMessageFor(GROK_TABLE, CODEX_PIXELS, true)).toBeUndefined()
})
diff --git a/mcp-host/src/llm/__tests__/subscriptionRequestHash.test.ts b/mcp-host/src/llm/__tests__/subscriptionRequestHash.test.ts
index e7b9f01dd..4498360b5 100644
--- a/mcp-host/src/llm/__tests__/subscriptionRequestHash.test.ts
+++ b/mcp-host/src/llm/__tests__/subscriptionRequestHash.test.ts
@@ -1,6 +1,6 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
import {
- hashGrokCompletionRequestV1,
+ hashGrokCompletionRequest,
parseGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
import {
@@ -63,7 +63,7 @@ const PROVIDERS = [
serverHash: (wire: unknown) => {
const parsed = parseGrokCompletionRequestV1(wire)
if (!parsed.ok) throw new Error(parsed.message)
- return hashGrokCompletionRequestV1(parsed.value)
+ return hashGrokCompletionRequest(parsed.value)
},
// Captured from the provider at a42dedf8, before canonical hashing.
goldenToolsHash: '507c127d04e04544ce92b2417e6d30c84033aef8609b501bfe305c1e61a526af',
diff --git a/mcp-host/src/llm/grokLlmProxyClient.ts b/mcp-host/src/llm/grokLlmProxyClient.ts
index 073ebedf0..3af37a3a7 100644
--- a/mcp-host/src/llm/grokLlmProxyClient.ts
+++ b/mcp-host/src/llm/grokLlmProxyClient.ts
@@ -30,6 +30,17 @@ export function grokProxyErrorMessage(code: string, status?: number): string {
: `proxy stream failed with ${status} (${code})`
}
+/**
+ * The code for an envelope the contract refused. Every `limit` failure maps to
+ * `payload_too_large` here, including the count, nesting and range kinds; the
+ * authorize and transport callers map only `kind: 'size'` that way.
+ */
+function envelopeRefusalCode(contractCode: string): string {
+ if (contractCode === 'limit') return 'payload_too_large'
+ if (contractCode === 'request_hash_mismatch') return 'request_hash_mismatch'
+ return 'invalid_request'
+}
+
export type GrokProxyErrorOptions = {
/**
* Whether a request had already left this process when the error was
@@ -135,13 +146,9 @@ export class GrokLlmProxyClient {
request: input.request as GrokCompletionRequest,
})
if (!envelope.ok) {
- const code =
- envelope.code === 'limit'
- ? 'payload_too_large'
- : envelope.code === 'request_hash_mismatch'
- ? 'request_hash_mismatch'
- : 'invalid_request'
- throw new GrokProxyError(code, envelope.message, { dispatched: false })
+ throw new GrokProxyError(envelopeRefusalCode(envelope.code), envelope.message, {
+ dispatched: false,
+ })
}
if (
input.deadlineMs !== undefined &&
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
index 9b9d650b0..8b4fb7c06 100644
--- a/mcp-host/src/llm/grokSubscription.ts
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -60,6 +60,17 @@ const GROK_REQUEST_INVALID = 'invalid_request'
/** A local image budget refusal (`ATTACHMENT_BUDGET_REFUSALS`). */
const GROK_ATTACHMENT_TOO_LARGE = 'attachment_too_large'
+/**
+ * The code for a canonical-request refusal that is not an attachment refusal:
+ * a conversation-volume limit is a context-length failure, any other `size`
+ * refusal is `payload_too_large`, and everything else is an invalid request.
+ */
+function canonicalRefusalCode(refusal: { code: string; message: string; kind?: string }): string {
+ if (isContextLengthRefusal(refusal.code, refusal.message)) return 'request_limit_exceeded'
+ if (refusal.kind === 'size') return 'payload_too_large'
+ return GROK_REQUEST_INVALID
+}
+
function mapGrokUsage(usage?: { inputTokens: number; outputTokens: number }): {
usage: { input_tokens: number; output_tokens: number; total_tokens: number }
usage_reported: boolean
@@ -466,14 +477,7 @@ export class GrokSubscriptionProvider implements SingleTurnProvider {
if (attachmentRefusal !== undefined) {
throw new CodexAuthorizeError(GROK_ATTACHMENT_TOO_LARGE, attachmentRefusal)
}
- throw new CodexAuthorizeError(
- isContextLengthRefusal(canonical.code, canonical.message)
- ? 'request_limit_exceeded'
- : canonical.kind === 'size'
- ? 'payload_too_large'
- : GROK_REQUEST_INVALID,
- canonical.message
- )
+ throw new CodexAuthorizeError(canonicalRefusalCode(canonical), canonical.message)
}
const { request, requestHash } = canonical.value
const context = this.deps.attemptContext({ model: this.model })
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index faac5975f..1fba17e56 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -711,10 +711,6 @@ function parseGrokCompletionRequestV1(input) {
return parseGrokCompletionRequestRoot(input, SCHEMA_VERSION, MESSAGE_KEYS)
}
-function hashGrokCompletionRequestV1(request) {
- return createHash('sha256').update(stableStringify(request)).digest('hex')
-}
-
/**
* Minimal image provenance for V2. Closed union: an attachment that arrived
* with a user message, or one produced by a tool call. It is hashed with the
@@ -1103,7 +1099,6 @@ module.exports = {
parseGrokCompletionRequestV1,
parseGrokCompletionRequestV2,
parseGrokCompletionRequest,
- hashGrokCompletionRequestV1,
hashGrokCompletionRequest,
hashCanonicalGrokRequest,
buildGrokProxyEnvelope,
diff --git a/packages/grok-provider-attempt-contract/index.d.ts b/packages/grok-provider-attempt-contract/index.d.ts
index 41a758612..ddfc73043 100644
--- a/packages/grok-provider-attempt-contract/index.d.ts
+++ b/packages/grok-provider-attempt-contract/index.d.ts
@@ -318,7 +318,6 @@ export declare function parseGrokCompletionRequestV2(
export declare function parseGrokCompletionRequest(
input: unknown
): ContractResult<GrokCompletionRequest>
-export declare function hashGrokCompletionRequestV1(request: GrokCompletionRequestV1): string
export declare function hashGrokCompletionRequest(request: GrokCompletionRequest): string
/**
* Canonical client hash: JSON wire round-trip, parseGrokCompletionRequest
diff --git a/packages/grok-provider-attempt-contract/index.test.cjs b/packages/grok-provider-attempt-contract/index.test.cjs
index 3aa6b3c88..3c23cb620 100644
--- a/packages/grok-provider-attempt-contract/index.test.cjs
+++ b/packages/grok-provider-attempt-contract/index.test.cjs
@@ -110,7 +110,7 @@ test('does not import Codex LIMITS or Codex provider id', () => {
test('parses the bounded V1 request and hashes with SHA-256', () => {
const parsed = contract.parseGrokCompletionRequestV1(BASE)
assert.equal(parsed.ok, true)
- const digest = contract.hashGrokCompletionRequestV1(parsed.value)
+ const digest = contract.hashGrokCompletionRequest(parsed.value)
assert.match(digest, /^[a-f0-9]{64}$/)
})
@@ -209,7 +209,7 @@ function serverHash(wireRequest) {
const onWire = JSON.parse(JSON.stringify({ request: wireRequest })).request
const parsed = contract.parseGrokCompletionRequestV1(onWire)
assert.equal(parsed.ok, true, parsed.message)
- return contract.hashGrokCompletionRequestV1(parsed.value)
+ return contract.hashGrokCompletionRequest(parsed.value)
}
test('golden digests: well-formed requests keep their pre-change hashes on every path', () => {
@@ -247,7 +247,7 @@ test('golden digests: well-formed requests keep their pre-change hashes on every
for (const entry of golden) {
const parsed = contract.parseGrokCompletionRequestV1(entry.request)
assert.equal(parsed.ok, true, `${entry.name}: ${parsed.message}`)
- assert.equal(contract.hashGrokCompletionRequestV1(parsed.value), entry.sha256, entry.name)
+ assert.equal(contract.hashGrokCompletionRequest(parsed.value), entry.sha256, entry.name)
const canonical = contract.hashCanonicalGrokRequest(entry.request)
assert.equal(canonical.ok, true, entry.name)
assert.equal(canonical.value.requestHash, entry.sha256, entry.name)