Skip to content

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

TypeScript

Merge remote-tracking branch 'origin/dev' into fix/731-context-gauge-minified-json

Alfredo Lopez6a09cd78ce1b
diff --cc codex-llm-proxy/src/config.ts
index 50a43fc79,2aa9c3e08..69349ddc1
--- a/codex-llm-proxy/src/config.ts
+++ b/codex-llm-proxy/src/config.ts
@@@ -1,4 -1,4 +1,5 @@@
+ import { LIMITS } from '@clerum/llm-provider-attempt-contract'
+import { DEFAULT_MAX_BODY_BYTES } from './requestLimits.js'
export type CodexLlmProxyConfig = {
runtimePort: number
@@@ -58,15 -59,37 +60,37 @@@ function requiredNonEmpty(name: string
}
export function loadConfig(env: NodeJS.ProcessEnv = process.env): CodexLlmProxyConfig {
+ const maxBodyBytes = requiredPositiveInt(
+ 'CODEX_LLM_PROXY_MAX_BODY_BYTES',
+ env.CODEX_LLM_PROXY_MAX_BODY_BYTES,
- LIMITS.maxRequestBodyBytes
++ DEFAULT_MAX_BODY_BYTES
+ )
+ const maxVisualBodyBytes = requiredPositiveInt(
+ 'CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES',
+ env.CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES,
+ LIMITS.maxVisualRequestBodyBytes
+ )
+ if (maxVisualBodyBytes < LIMITS.maxVisualRequestBodyBytes) {
+ throw new Error('Visual Codex requests require the full shared envelope byte budget')
+ }
return {
- runtimePort: requiredPositiveInt('CODEX_LLM_PROXY_RUNTIME_PORT', env.CODEX_LLM_PROXY_RUNTIME_PORT, 8080),
- adminPort: requiredPositiveInt('CODEX_LLM_PROXY_ADMIN_PORT', env.CODEX_LLM_PROXY_ADMIN_PORT, 8081),
- probePort: requiredPositiveInt('CODEX_LLM_PROXY_PROBE_PORT', env.CODEX_LLM_PROXY_PROBE_PORT, 9090),
- maxBodyBytes: requiredPositiveInt(
- 'CODEX_LLM_PROXY_MAX_BODY_BYTES',
- env.CODEX_LLM_PROXY_MAX_BODY_BYTES,
- DEFAULT_MAX_BODY_BYTES
+ runtimePort: requiredPositiveInt(
+ 'CODEX_LLM_PROXY_RUNTIME_PORT',
+ env.CODEX_LLM_PROXY_RUNTIME_PORT,
+ 8080
+ ),
+ adminPort: requiredPositiveInt(
+ 'CODEX_LLM_PROXY_ADMIN_PORT',
+ env.CODEX_LLM_PROXY_ADMIN_PORT,
+ 8081
),
+ probePort: requiredPositiveInt(
+ 'CODEX_LLM_PROXY_PROBE_PORT',
+ env.CODEX_LLM_PROXY_PROBE_PORT,
+ 9090
+ ),
+ maxBodyBytes,
+ maxVisualBodyBytes,
maxStreamDurationMs: requiredPositiveInt(
'CODEX_LLM_PROXY_MAX_STREAM_DURATION_MS',
env.CODEX_LLM_PROXY_MAX_STREAM_DURATION_MS,
diff --cc codex-llm-proxy/src/requestLimits.ts
index 0f87e8f28,2356e88f4..667c1104c
--- a/codex-llm-proxy/src/requestLimits.ts
+++ b/codex-llm-proxy/src/requestLimits.ts
@@@ -1,30 -1,5 +1,33 @@@
import { LIMITS as CONTRACT_LIMITS } from '@clerum/llm-provider-attempt-contract'
+/**
+ * #731 — room for the runtime envelope around the contract-capped `request`:
+ * the execution ticket (a few KB by its claim bounds), the request hash, the
+ * deadline and the JSON keys. 16 KiB is several times that.
+ */
+export const ENVELOPE_ALLOWANCE_BYTES = 16 * 1024
+
+/**
+ * The default body limit, derived from the contract so the proxy never refuses,
+ * as a 413, a request the contract accepts.
+ */
+export const DEFAULT_MAX_BODY_BYTES = CONTRACT_LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES
+
+/**
+ * #731 R3-2 — how many maximum-size bodies may be read and parsed at once.
+ * About five copies of a body are alive while it is parsed and hashed (the raw
+ * buffer, the decoded string, the parsed object, the contract copy and the
+ * canonical serialization), so three 8 MiB bodies hold about 120 MiB of the
+ * pod's 256Mi. Without this bound the stream gate would let 24 bodies in.
++ * Bodies over the ordinary cap never take this budget: they are V2 visual
++ * envelopes, bounded by `visualStreamGate` instead, so the declared bodies a pod
++ * can hold at once are 3 x 8 MiB here plus 2 x 24 MiB there.
+ */
+export const IN_FLIGHT_BODY_BUDGET_BODIES = 3
+
+/** The deployed admission budget in bytes: about 24 MiB of declared bodies. */
+export const IN_FLIGHT_BODY_BUDGET_BYTES = IN_FLIGHT_BODY_BUDGET_BODIES * DEFAULT_MAX_BODY_BYTES
+
export const STREAM_LIMITS = {
maxConcurrentStreams: 8,
maxQueuedRequests: 16,
@@@ -96,84 -88,7 +116,89 @@@ export class StreamGate
}
export const streamGate = new StreamGate()
+
+ export const visualStreamGate = new StreamGate(
+ VISUAL_STREAM_LIMITS.maxConcurrentStreams,
+ VISUAL_STREAM_LIMITS.maxQueuedRequests
+ )
++
+type BodyWaiter = { bytes: number; grant: (release: () => void) => void }
+
+/**
+ * #731 R3-2 — a byte budget for request bodies, taken from the declared
+ * `Content-Length` before the body is read. Bodies that do not fit wait in a
+ * bounded FIFO queue; a full queue is refused with the same RequestLimitError
+ * the stream gate raises, so the client sees the existing overload response.
+ */
+export class BodyBudget {
+ private inFlight = 0
+ private readonly waiters: BodyWaiter[] = []
+
+ constructor(
+ private readonly capacityBytes: number,
+ private readonly maxQueued: number = STREAM_LIMITS.maxQueuedRequests
+ ) {}
+
+ get inFlightBytes(): number {
+ return this.inFlight
+ }
+
+ get queued(): number {
+ return this.waiters.length
+ }
+
+ /**
+ * Reserve `bytes` of the budget. The returned release is idempotent. When
+ * `signal` aborts while the caller is queued, the waiter is rejected and
+ * removed, and the waiters behind it are reconsidered.
+ */
+ async acquire(bytes: number, signal?: AbortSignal): Promise<() => void> {
+ if (!Number.isInteger(bytes) || bytes < 0 || bytes > this.capacityBytes) {
+ throw new RangeError(`a body of ${bytes} bytes cannot fit a budget of ${this.capacityBytes}`)
+ }
+ if (signal?.aborted) throw new RequestLimitError('body admission was aborted')
+ if (this.waiters.length === 0 && this.inFlight + bytes <= this.capacityBytes) {
+ return this.take(bytes)
+ }
+ if (this.waiters.length >= this.maxQueued) {
+ throw new RequestLimitError('body admission queue is full')
+ }
+ return new Promise<() => void>((resolve, reject) => {
+ const onAbort = () => {
+ const index = this.waiters.indexOf(waiter)
+ if (index === -1) return
+ this.waiters.splice(index, 1)
+ reject(new RequestLimitError('body admission was aborted'))
+ this.drain()
+ }
+ const waiter: BodyWaiter = {
+ bytes,
+ grant: release => {
+ signal?.removeEventListener('abort', onAbort)
+ resolve(release)
+ },
+ }
+ signal?.addEventListener('abort', onAbort, { once: true })
+ this.waiters.push(waiter)
+ })
+ }
+
+ private take(bytes: number): () => void {
+ this.inFlight += bytes
+ let released = false
+ return () => {
+ if (released) return
+ released = true
+ this.inFlight -= bytes
+ this.drain()
+ }
+ }
+
+ /** Grant queued bodies in arrival order while the head of the queue fits. */
+ private drain(): void {
+ while (this.waiters.length > 0 && this.inFlight + this.waiters[0]!.bytes <= this.capacityBytes) {
+ const waiter = this.waiters.shift()!
+ waiter.grant(this.take(waiter.bytes))
+ }
+ }
+}
diff --cc codex-llm-proxy/src/server.ts
index 68ac5c96c,5b4cf9abc..6d5e82e5a
--- a/codex-llm-proxy/src/server.ts
+++ b/codex-llm-proxy/src/server.ts
@@@ -17,19 -17,23 +17,30 @@@ import { ControlApiClient, ControlApiCl
import { logger } from './logger.js'
import { createProxyMetrics } from './metrics.js'
import {
- defaultAddressLookup,
OriginDeniedError,
type OriginPolicyOptions,
+ defaultAddressLookup,
} from './originPolicy.js'
+ import {
+ LIMITS,
+ SCHEMA_VERSION_V2,
+ measureNonImageCompletionBytes,
+ requestBodyLimitBytes,
+ } from '@clerum/llm-provider-attempt-contract'
-import { RequestLimitError, streamGate, visualStreamGate } from './requestLimits.js'
+import {
+ BodyBudget,
++ ENVELOPE_ALLOWANCE_BYTES,
+ IN_FLIGHT_BODY_BUDGET_BODIES,
+ RequestLimitError,
+ streamGate,
++ visualStreamGate,
+} from './requestLimits.js'
+ type GatedRequest = Request & { codexStreamRelease?: () => void }
+
const COMPLETION_KEYS = new Set(['executionTicket', 'requestHash', 'request', 'deadlineMs'])
const ADMIN_KEYS = new Set(['accessToken'])
+ const COMPLETION_PATH = '/internal/runtime/v1/codex/completions'
const completionBodySchema = z
.object({
@@@ -67,62 -82,6 +89,64 @@@ function boundedErrorHandler(err: unkno
reject(res, 500, 'internal_error')
}
+/**
+ * #731 R3-2 — memory-bounded admission, run before express.json. A body is
+ * read only once its declared `Content-Length` fits the shared byte budget, so
+ * the bodies in memory are bounded by bytes rather than by the stream gate's
+ * request count. A body of undeclared length is refused (411) instead of being
- * read unbounded. Bodies over the limit pass through so express.json answers
- * 413 from the header without buffering them. The reservation is released when
++ * read unbounded. Bodies over the limit pass through without a reservation:
++ * on the admin app express.json answers 413 from the header without buffering
++ * them, and on the runtime app `selectTransportBudget` either answers 413 or
++ * admits them through the visual gate. The reservation is released when
+ * the response closes, or the queued waiter is dropped if the client leaves
+ * first; a full queue gets the stream gate's overload response.
+ */
+function bodyAdmission(budget: BodyBudget, maxBodyBytes: number) {
+ return (req: Request, res: Response, next: NextFunction): void => {
+ if (req.headers['transfer-encoding'] !== undefined) {
+ reject(res, 411, 'length_required')
+ return
+ }
+ const declared = req.headers['content-length']
+ if (declared === undefined) {
+ next()
+ return
+ }
+ if (!/^\d+$/.test(declared)) {
+ reject(res, 400, 'invalid_request')
+ return
+ }
+ const bytes = Number(declared)
+ if (bytes === 0 || bytes > maxBodyBytes) {
+ next()
+ return
+ }
+ const abort = new AbortController()
+ let release: (() => void) | undefined
+ res.once('close', () => {
+ if (release) release()
+ else abort.abort()
+ })
+ budget.acquire(bytes, abort.signal).then(
+ granted => {
+ if (abort.signal.aborted) {
+ granted()
+ return
+ }
+ release = granted
+ next()
+ },
+ (err: unknown) => {
+ if (!(err instanceof RequestLimitError)) {
+ next(err)
+ return
+ }
+ if (!abort.signal.aborted) reject(res, 503, 'provider_unavailable')
+ }
+ )
+ }
+}
+
export type ProxyRuntimeDeps = {
controlApiClient?: ControlApiClient
fetchFn?: typeof fetch
@@@ -171,14 -135,72 +200,78 @@@ export function createProxyApps
legacyHeaders: false,
})
+ // One budget for both apps: every body this process reads counts against it.
+ const bodyBudget = new BodyBudget(IN_FLIGHT_BODY_BUDGET_BODIES * config.maxBodyBytes)
+
const runtimeApp = express()
++ // Ordinary bodies (up to maxBodyBytes) are bounded by bytes here; larger
++ // bodies pass through untouched and are bounded by the visual gate below.
+ runtimeApp.use(bodyAdmission(bodyBudget, config.maxBodyBytes))
- runtimeApp.use(express.json({ limit: config.maxBodyBytes }))
- runtimeApp.post('/internal/runtime/v1/codex/completions', runtimeRateLimit, (req, res) => {
+ const ordinaryJson = express.json({ limit: config.maxBodyBytes })
+ const visualJson = express.json({ limit: config.maxVisualBodyBytes })
+ // Selecting the transport budget needs the platform identity, so this runs as a
+ // route handler after the rate limiter: an unauthenticated caller cannot force
+ // token verification or body parsing ahead of the limit. Admin or
+ // unauthenticated requests keep the ordinary cap.
+ //
+ // schemaVersion is not known until the body is parsed, so the visual gate
+ // must not be taken for every platform JWT. Only a declared Content-Length
+ // above the ordinary cap can be a visual envelope. Those bodies take the
+ // 2-wide gate (the image bytes stay resident for the ChatGPT stream). Every
+ // smaller body, including every valid V1, stays on the ordinary parser and
+ // later the 8-wide stream gate. A missing length cannot be upgraded: it is
+ // parsed at the ordinary cap, so a chunked caller cannot occupy a visual slot.
+ const selectTransportBudget = (req: GatedRequest, res: Response, next: NextFunction): void => {
+ if (!verifyPlatformJwt(bearer(req), config)) {
+ ordinaryJson(req, res, next)
+ return
+ }
+ const declared = contentLengthBytes(req)
+ if (declared !== null && declared > config.maxVisualBodyBytes) {
+ reject(res, 413, 'payload_too_large')
+ return
+ }
+ if (declared === null || declared <= config.maxBodyBytes) {
+ ordinaryJson(req, res, next)
+ return
+ }
+ void (async () => {
+ let release: (() => void) | undefined
+ const parseAbort = new AbortController()
+ const abortParse = (): void => parseAbort.abort()
+ req.once('aborted', abortParse)
+ try {
+ release = await visualStreamGate.acquire(parseAbort.signal)
+ } catch (err) {
+ req.off('aborted', abortParse)
+ if (err instanceof RequestLimitError) {
+ reject(res, 503, err.code)
+ return
+ }
+ next()
+ return
+ }
+ req.off('aborted', abortParse)
+ req.codexStreamRelease = release
+ visualJson(req, res, err => {
+ if (err) {
+ req.codexStreamRelease?.()
+ req.codexStreamRelease = undefined
+ next(err)
+ return
+ }
+ next()
+ })
+ })()
+ }
+ runtimeApp.post(COMPLETION_PATH, runtimeRateLimit, selectTransportBudget, (req, res) => {
+ const gated = req as GatedRequest
+ const releaseAdmission = (): void => {
+ gated.codexStreamRelease?.()
+ gated.codexStreamRelease = undefined
+ }
if (!req.is('application/json')) {
+ releaseAdmission()
reject(res, 415, 'unsupported_media_type')
return
}
@@@ -191,8 -215,23 +286,31 @@@
reject(res, 401, 'Unauthorized')
return
}
+ const request = isRecord(req.body) ? req.body.request : undefined
+ const visualDeclared = isRecord(request) && request.schemaVersion === SCHEMA_VERSION_V2
+ const configuredLimit = visualDeclared ? config.maxVisualBodyBytes : config.maxBodyBytes
+ const wholeBodyBytes = Buffer.byteLength(JSON.stringify(req.body ?? {}), 'utf8')
++ // A V1 envelope carries the ticket, the hash and the deadline beside a
++ // request that may itself sit at the contract cap (#731), so its limit adds
++ // the envelope allowance. A V2 envelope stays on the contract's visual
++ // ceiling, the same one buildCodexProxyEnvelope enforces.
++ const envelopeLimit = visualDeclared
++ ? requestBodyLimitBytes(request)
++ : requestBodyLimitBytes(request) + ENVELOPE_ALLOWANCE_BYTES
+ // Declaring V2 raises only the image budget. Text, tools and wrapper
- // fields stay on the contract's 1 MiB non-image ceiling.
++ // fields stay on the contract's maxRequestBodyBytes non-image ceiling, plus
++ // the same envelope allowance control-api's authorizer grants its wrapper.
+ if (
- wholeBodyBytes > Math.min(configuredLimit, requestBodyLimitBytes(request)) ||
- measureNonImageCompletionBytes(req.body) > LIMITS.maxRequestBodyBytes
++ wholeBodyBytes > Math.min(configuredLimit, envelopeLimit) ||
++ measureNonImageCompletionBytes(req.body) > LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES
+ ) {
+ releaseAdmission()
+ reject(res, 413, 'payload_too_large')
+ return
+ }
const extra = Object.keys(req.body ?? {}).find(key => !COMPLETION_KEYS.has(key))
if (extra) {
+ releaseAdmission()
reject(res, 400, 'unknown_field')
return
}
@@@ -433,8 -497,7 +577,9 @@@ export function startProxy(config: Code
// bounded by the proxy.
const ATTEMPT_ERROR_STATUS: Record<string, number> = {
invalid_request: 400,
+ // The upstream's own status class for a request over the context window (#731).
+ context_length_exceeded: 400,
+ payload_too_large: 413,
Unauthorized: 401,
origin_denied: 403,
request_hash_mismatch: 403,
diff --cc codex-llm-proxy/test/bodyAdmission.test.ts
index d430c76b4,000000000..a5d6b40d2
mode 100644,000000..100644
--- a/codex-llm-proxy/test/bodyAdmission.test.ts
+++ b/codex-llm-proxy/test/bodyAdmission.test.ts
@@@ -1,293 -1,0 +1,294 @@@
+/**
+ * #731 R3-2 - body admission before `express.json`.
+ *
+ * At an 8 MiB request cap, parsing every body the stream gate lets in (8
+ * running plus 16 queued) holds about five copies of each in memory, far past
+ * the proxy's 256Mi. These tests drive the real runtime app over HTTP and use
+ * the control-api `redeem` call as the witness: it runs only after the whole
+ * body was read, JSON-parsed, contract-parsed and hash-checked, so the number
+ * of attempts held there is the number of bodies in memory.
+ */
+import { describe, expect, it } from 'vitest'
+import jwt from 'jsonwebtoken'
+import { generateKeyPairSync, randomUUID } from 'node:crypto'
+import { request as httpRequest } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import {
+ LIMITS,
+ hashCodexCompletionRequestV1,
+ parseCodexCompletionRequestV1,
+} from '@clerum/llm-provider-attempt-contract'
+import type { CodexLlmProxyConfig } from '../src/config.js'
+import type {
+ ControlApiClient,
+ FinalizeAttemptSuccess,
+ RedeemAttemptSuccess,
+} from '../src/controlApiClient.js'
+import { CODEX_CATALOG_ORIGIN, CODEX_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
+import { DEFAULT_MAX_BODY_BYTES, STREAM_LIMITS } from '../src/requestLimits.js'
+import { createProxyApps } from '../src/server.js'
+
+const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+ modulusLength: 2048,
+ publicKeyEncoding: { type: 'spki', format: 'pem' },
+ privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+})
+
+const HOST_REF = 'research-host'
+const COMPLETIONS_PATH = '/internal/runtime/v1/codex/completions'
+/** The admission budget holds this many bodies of the configured maximum size. */
+const BUDGET_BODIES = 3
+
+function sign(payload: Record<string, unknown>, audience: string): string {
+ return jwt.sign(payload, privateKey, {
+ algorithm: 'RS256',
+ issuer: 'control-api',
+ audience,
+ expiresIn: 60,
+ })
+}
+
+function config(maxBodyBytes: number): CodexLlmProxyConfig {
+ return {
+ runtimePort: 0,
+ adminPort: 0,
+ probePort: 0,
+ maxBodyBytes,
++ maxVisualBodyBytes: LIMITS.maxVisualRequestBodyBytes,
+ maxStreamDurationMs: 60_000,
+ maxDeadlineMs: 60_000,
+ jwtIssuer: 'control-api',
+ jwtPublicKey: publicKey,
+ executionEnabled: true,
+ controlApiBaseUrl: 'http://control-api.invalid/api/v1',
+ controlApiServiceName: 'codex-llm-proxy',
+ controlApiServiceToken: 'unused',
+ }
+}
+
+const platformToken = sign(
+ {
+ sub: `default/${HOST_REF}`,
+ hostRefs: [HOST_REF],
+ workflowControlScopes: ['llm:codex:execute'],
+ scope: 'workflow:approval:request',
+ },
+ 'workflow-approvals'
+)
+
+/** A runtime envelope whose request carries one user message of `contentChars`. */
+function completionBody(contentChars: number, attempt: string): string {
+ const raw = {
+ schemaVersion: 'codex-completion-request.v1',
+ requestId: `req-${attempt}`,
+ idempotencyKey: `idem-${attempt}`,
+ provider: 'codex-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'x'.repeat(contentChars) }],
+ }
+ const parsed = parseCodexCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashCodexCompletionRequestV1(parsed.value)
+ return JSON.stringify({
+ executionTicket: sign(
+ {
+ jti: randomUUID(),
+ typ: 'codex-execution-ticket',
+ hostRef: HOST_REF,
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId: `att-${attempt}`,
+ },
+ 'codex-llm-proxy'
+ ),
+ requestHash,
+ request: raw,
+ })
+}
+
+/**
+ * A proxy whose `redeem` holds every attempt until `releaseAll`, so an attempt
+ * that reached it keeps its parsed body in memory.
+ */
+async function heldProxy(maxBodyBytes: number) {
+ let redeemed = 0
+ let holding = true
+ const held: Array<() => void> = []
+ const client = {
+ async redeem(): Promise<RedeemAttemptSuccess> {
+ redeemed += 1
+ if (holding) await new Promise<void>(resolve => held.push(resolve))
+ return {
+ accessToken: 'test-access-admission',
+ chatgptAccountId: 'acct-admission',
+ transport: {
+ protocolVersion: 'codex-subscription-transport.v1',
+ completionsOrigin: CODEX_COMPLETIONS_ORIGIN,
+ catalogOrigin: CODEX_CATALOG_ORIGIN,
+ operation: 'completion_stream',
+ servedModel: 'gpt-5.1',
+ maxStreamDurationMs: 60_000,
+ },
+ expiryClass: 'short_lived',
+ attemptReceipt: 'b'.repeat(64),
+ }
+ },
+ async finalize(input: {
+ receipt: { providerAttemptId: string; outcome: FinalizeAttemptSuccess['outcome'] }
+ }): Promise<FinalizeAttemptSuccess> {
+ return {
+ providerAttemptId: input.receipt.providerAttemptId,
+ outcome: input.receipt.outcome,
+ duplicate: false,
+ }
+ },
+ } as unknown as ControlApiClient
+ const fetchFn = (async () =>
+ new Response('data: {"type":"response.completed","response":{"usage":{}}}\n\n', {
+ status: 200,
+ headers: { 'content-type': 'text/event-stream' },
+ })) as typeof fetch
+
+ const servers = createProxyApps(config(maxBodyBytes), {
+ controlApiClient: client,
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ })
+ await new Promise<void>(resolve => servers.runtime.listen(0, '127.0.0.1', () => resolve()))
+ const { port } = servers.runtime.address() as AddressInfo
+ return {
+ port,
+ redeemed: () => redeemed,
+ releaseAll: () => {
+ holding = false
+ for (const resolve of held.splice(0)) resolve()
+ },
+ close: () => servers.close(),
+ }
+}
+
+type Reply = { status: number; body: string }
+
+/** POST with a declared Content-Length, or with a chunked body of undeclared length. */
+function post(port: number, payload: string, options: { chunked?: boolean } = {}): Promise<Reply> {
+ return new Promise((resolve, reject) => {
+ const req = httpRequest(
+ {
+ host: '127.0.0.1',
+ port,
+ method: 'POST',
+ path: COMPLETIONS_PATH,
+ agent: false,
+ headers: {
+ 'content-type': 'application/json',
+ authorization: `Bearer ${platformToken}`,
+ ...(options.chunked
+ ? { 'transfer-encoding': 'chunked' }
+ : { 'content-length': Buffer.byteLength(payload) }),
+ },
+ },
+ res => {
+ const chunks: Buffer[] = []
+ res.on('data', chunk => chunks.push(chunk as Buffer))
+ res.on('end', () =>
+ resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks).toString('utf8') })
+ )
+ res.on('error', reject)
+ }
+ )
+ req.on('error', reject)
+ req.end(payload)
+ })
+}
+
+/** Waits until `read()` is positive and stops changing for one poll interval. */
+async function settle(read: () => number): Promise<number> {
+ const deadline = Date.now() + 20_000
+ let last = -1
+ while (Date.now() < deadline) {
+ await new Promise(resolve => setTimeout(resolve, 300))
+ const now = read()
+ if (now > 0 && now === last) return now
+ last = now
+ }
+ throw new Error(`count did not settle within 20s (last ${last})`)
+}
+
+describe('codex-llm-proxy body admission (#731 R3-2)', () => {
+ it('T-R3-2a holds at most three near-cap bodies at once and admits the rest as they finish', async () => {
+ const proxy = await heldProxy(DEFAULT_MAX_BODY_BYTES)
+ try {
+ const contentChars = Math.floor(LIMITS.maxRequestBodyBytes * 0.9)
+ const payloads = Array.from({ length: 6 }, (_, i) => completionBody(contentChars, `cap-${i}`))
+ const payloadBytes = Buffer.byteLength(payloads[0]!)
+ // Fixture check: three bodies fit the budget and a fourth does not.
+ expect(BUDGET_BODIES * payloadBytes).toBeLessThanOrEqual(
+ BUDGET_BODIES * DEFAULT_MAX_BODY_BYTES
+ )
+ expect((BUDGET_BODIES + 1) * payloadBytes).toBeGreaterThan(
+ BUDGET_BODIES * DEFAULT_MAX_BODY_BYTES
+ )
+
+ const replies = payloads.map(payload => post(proxy.port, payload))
+ expect(await settle(proxy.redeemed)).toBe(BUDGET_BODIES)
+
+ // Liveness: the three that waited are admitted once the first finish.
+ proxy.releaseAll()
+ const settled = await Promise.all(replies)
+ expect(settled.map(reply => reply.status)).toEqual([200, 200, 200, 200, 200, 200])
+ for (const reply of settled) expect(reply.body).toContain('"outcome":"success"')
+ expect(proxy.redeemed()).toBe(6)
+ } finally {
+ proxy.releaseAll()
+ await proxy.close()
+ }
+ }, 60_000)
+
+ it('T-R3-2b refuses a body of undeclared length with 411 before reading it', async () => {
+ const proxy = await heldProxy(DEFAULT_MAX_BODY_BYTES)
+ proxy.releaseAll()
+ try {
+ const refused = await post(proxy.port, completionBody(64, 'chunked'), { chunked: true })
+ expect(refused.status).toBe(411)
+ expect(JSON.parse(refused.body)).toEqual({ error: 'length_required' })
+ expect(proxy.redeemed()).toBe(0)
+
+ // Witness: the same request with a declared length is served.
+ const served = await post(proxy.port, completionBody(64, 'declared'))
+ expect(served.status).toBe(200)
+ expect(proxy.redeemed()).toBe(1)
+ } finally {
+ await proxy.close()
+ }
+ }, 30_000)
+
+ it('T-R3-2c answers provider_unavailable once the admission queue is full', async () => {
+ // A small body limit keeps this cheap; the budget scales with it.
+ const maxBodyBytes = 16 * 1024
+ const proxy = await heldProxy(maxBodyBytes)
+ try {
+ const payload = (attempt: string) => completionBody(12_000, attempt)
+ const payloadBytes = Buffer.byteLength(payload('probe'))
+ expect(payloadBytes).toBeLessThanOrEqual(maxBodyBytes)
+ expect((BUDGET_BODIES + 1) * payloadBytes).toBeGreaterThan(BUDGET_BODIES * maxBodyBytes)
+
+ const waiting = Array.from({ length: BUDGET_BODIES + STREAM_LIMITS.maxQueuedRequests }, (_, i) =>
+ post(proxy.port, payload(`queued-${i}`))
+ )
+ 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' })
+
+ // Liveness: every queued request is still served once the budget frees.
+ proxy.releaseAll()
+ const settled = await Promise.all(waiting)
+ expect(settled.every(reply => reply.status === 200)).toBe(true)
+ expect(proxy.redeemed()).toBe(BUDGET_BODIES + STREAM_LIMITS.maxQueuedRequests)
+ } finally {
+ proxy.releaseAll()
+ await proxy.close()
+ }
+ }, 60_000)
+})
diff --cc codex-llm-proxy/test/codexTransport.conformance.test.ts
index 2381fc238,b557f0f34..382801cc1
--- a/codex-llm-proxy/test/codexTransport.conformance.test.ts
+++ b/codex-llm-proxy/test/codexTransport.conformance.test.ts
@@@ -12,13 -16,11 +16,17 @@@ import type { RedeemAttemptSuccess } fr
import { CODEX_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
import { ToolNameMap } from '../src/toolNameMap.js'
import { eventaskUpdateTool, optionalMcpTools, webSearchTool } from './fixtures/optionalMcpTools.js'
+import {
+ UPSTREAM_CONTEXT_ERROR_EVENT,
+ UPSTREAM_CONTEXT_FAILED_EVENT,
+ UPSTREAM_CONTEXT_OVERFLOW_FRAMES,
+ sseFrame,
+} from './fixtures/upstreamContextOverflow.js'
+ const { declaredHeaderPng } = createRequire(import.meta.url)(
+ '../../packages/llm-provider-attempt-contract/testImageFixtures.cjs'
+ ) as { declaredHeaderPng: (width: number, height: number) => Buffer }
+
const REQUEST = {
schemaVersion: 'codex-completion-request.v1' as const,
requestId: 'req-001',
diff --cc codex-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
index a4cfa68bb,bbaf486d5..7ab37f68d
--- a/codex-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
+++ b/codex-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
@@@ -80,7 -79,8 +80,8 @@@ function config(): CodexLlmProxyConfig
runtimePort: 0,
adminPort: 0,
probePort: 0,
- maxBodyBytes: 1_048_576,
+ maxBodyBytes: DEFAULT_MAX_BODY_BYTES,
+ maxVisualBodyBytes: 24 * 1024 * 1024,
maxStreamDurationMs: 30_000,
maxDeadlineMs: 30_000,
jwtIssuer: 'control-api',
diff --cc codex-llm-proxy/test/server.security.test.ts
index 767693531,cdf01142f..b66bcd1e8
--- a/codex-llm-proxy/test/server.security.test.ts
+++ b/codex-llm-proxy/test/server.security.test.ts
@@@ -1,8 -1,8 +1,9 @@@
import { generateKeyPairSync } from 'node:crypto'
import jwt from 'jsonwebtoken'
import request from 'supertest'
+ import { describe, expect, it, vi } from 'vitest'
import {
+ LIMITS,
hashCodexCompletionRequestV1,
parseCodexCompletionRequestV1,
} from '@clerum/llm-provider-attempt-contract'
@@@ -18,8 -17,7 +18,9 @@@ import
} from '../src/controlApiClient.js'
import { logger } from '../src/logger.js'
import { CODEX_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
++import { DEFAULT_MAX_BODY_BYTES, ENVELOPE_ALLOWANCE_BYTES } from '../src/requestLimits.js'
import { createProxyApps } from '../src/server.js'
+import { UPSTREAM_CONTEXT_OVERFLOW_FRAMES } from './fixtures/upstreamContextOverflow.js'
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
modulusLength: 2048,
@@@ -162,6 -163,94 +166,97 @@@ describe('codex-llm-proxy security surf
expect(res.status).toBe(413)
})
+ it('reserves the larger transport budget for authenticated visual requests', async () => {
+ const { runtimeApp, adminApp } = createProxyApps(
+ config({ maxBodyBytes: 1_048_576 })
+ )
+ // Deliberately invalid ticket: this test checks parser admission and the
+ // unchanged ticket gate, without redeeming or contacting any model.
+ const payload = {
+ executionTicket: 'invalid-ticket',
+ requestHash: 'a'.repeat(64),
+ request: {
+ schemaVersion: 'codex-completion-request.v2',
+ messages: [
+ {
+ role: 'user',
+ contentParts: [{ type: 'image', data: 'A'.repeat(10 * 1024 * 1024) }],
+ },
+ ],
+ },
+ }
+ const admitted = await request(runtimeApp)
+ .post('/internal/runtime/v1/codex/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send(payload)
+ expect(admitted.status).toBe(403)
+ expect(admitted.body.error).toBe('ticket_invalid')
+
+ const anonymous = await request(runtimeApp)
+ .post('/internal/runtime/v1/codex/completions')
+ .send(payload)
+ expect(anonymous.status).toBe(413)
+ const noScope = await request(runtimeApp)
+ .post('/internal/runtime/v1/codex/completions')
+ .set('Authorization', `Bearer ${platformToken({ workflowControlScopes: [] })}`)
+ .send(payload)
+ expect(noScope.status).toBe(413)
+ const v1 = await request(runtimeApp)
+ .post('/internal/runtime/v1/codex/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send({
+ ...payload,
+ request: { ...payload.request, schemaVersion: 'codex-completion-request.v1' },
+ })
+ expect(v1.status).toBe(413)
+ const admin = await request(adminApp)
+ .post('/internal/admin/v1/codex/models')
+ .set('Authorization', `Bearer ${adminPermit()}`)
+ .send(payload)
+ expect(admin.status).toBe(413)
+ })
+
+ it('does not let a V2 declaration raise the non-image budget to 24 MiB', async () => {
- const { runtimeApp } = createProxyApps(config({ maxBodyBytes: 1_048_576 }))
++ const { runtimeApp } = createProxyApps(config({ maxBodyBytes: DEFAULT_MAX_BODY_BYTES }))
++ // One byte of text past the non-image ceiling plus its envelope allowance,
++ // far under the 24 MiB visual ceiling the V2 declaration opens.
++ const pad = 'x'.repeat(LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES + 1)
+ const res = await request(runtimeApp)
+ .post('/internal/runtime/v1/codex/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send({
+ executionTicket: 'invalid-ticket',
+ requestHash: 'a'.repeat(64),
- request: { schemaVersion: 'codex-completion-request.v2', pad: 'x'.repeat(2 * 1024 * 1024) },
++ request: { schemaVersion: 'codex-completion-request.v2', pad },
+ })
+ expect(res.status).toBe(413)
+ expect(res.body.error).toBe('payload_too_large')
+ })
+
+ it('rate limits the completion endpoint before body parsing and authorization', async () => {
+ const { runtimeApp } = createProxyApps(
+ config({ maxBodyBytes: 1024 })
+ )
+ const completion = () => request(runtimeApp).post('/internal/runtime/v1/codex/completions')
+ const oversized = {
+ executionTicket: 'invalid-ticket',
+ requestHash: 'a'.repeat(64),
+ request: { schemaVersion: 'codex-completion-request.v2', pad: 'x'.repeat(4096) },
+ }
+ // With budget left, an unauthenticated oversize request is stopped by the
+ // ordinary transport cap instead of the limiter.
+ const withinBudget = await completion().send(oversized)
+ expect(withinBudget.status).toBe(413)
+ for (let i = 0; i < 59; i += 1) {
+ const accepted = await completion().send({})
+ expect(accepted.status).toBe(401)
+ }
+ // The limiter runs first, so the exhausted window rejects before the identity
+ // check and body parsing turn the same request into a 413.
+ const limited = await completion().send(oversized)
+ expect(limited.status).toBe(429)
+ })
+
it('rejects a platform JWT whose hostRefs do not bind the ticket hostRef', async () => {
const { runtimeApp } = createProxyApps(config())
const foreign = sign(
diff --cc codex-llm-proxy/test/sseBackpressure.test.ts
index 23ee1721c,dae86e6e5..f7be72772
--- a/codex-llm-proxy/test/sseBackpressure.test.ts
+++ b/codex-llm-proxy/test/sseBackpressure.test.ts
@@@ -90,7 -89,8 +90,8 @@@ function config(): CodexLlmProxyConfig
runtimePort: 0,
adminPort: 0,
probePort: 0,
- maxBodyBytes: 1_048_576,
+ maxBodyBytes: DEFAULT_MAX_BODY_BYTES,
+ maxVisualBodyBytes: 24 * 1024 * 1024,
maxStreamDurationMs: 60_000,
maxDeadlineMs: 60_000,
jwtIssuer: 'control-api',
diff --cc codex-llm-proxy/test/streamGate.handoff.test.ts
index 000000000,9abda5974..253ca0327
mode 000000,100644..100644
--- a/codex-llm-proxy/test/streamGate.handoff.test.ts
+++ b/codex-llm-proxy/test/streamGate.handoff.test.ts
@@@ -1,0 -1,373 +1,376 @@@
+ import { generateKeyPairSync } from 'node:crypto'
+ import { createServer } from 'node:http'
+ import { connect as connectTcp } from 'node:net'
+ import jwt from 'jsonwebtoken'
+ import { afterEach, describe, expect, it } from 'vitest'
+ import {
+ hashCodexCompletionRequest,
+ parseCodexCompletionRequest,
+ } from '@clerum/llm-provider-attempt-contract'
+ import { type CodexLlmProxyConfig } from '../src/config.js'
+ import { createProxyApps } from '../src/server.js'
+ import {
+ STREAM_LIMITS,
+ VISUAL_STREAM_LIMITS,
+ streamGate,
+ visualStreamGate,
+ } from '../src/requestLimits.js'
+
+ const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+ modulusLength: 2048,
+ publicKeyEncoding: { type: 'spki', format: 'pem' },
+ privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+ })
+
+ function config(overrides: Partial<CodexLlmProxyConfig> = {}): CodexLlmProxyConfig {
+ return {
+ runtimePort: 8080,
+ adminPort: 8081,
+ probePort: 9090,
+ maxBodyBytes: 1_048_576,
+ maxVisualBodyBytes: 24 * 1024 * 1024,
+ maxStreamDurationMs: 300_000,
+ maxDeadlineMs: 300_000,
+ jwtIssuer: 'control-api',
+ jwtPublicKey: publicKey,
+ executionEnabled: true,
+ controlApiBaseUrl: '',
+ controlApiServiceName: 'codex-llm-proxy',
+ controlApiServiceToken: '',
+ ...overrides,
+ }
+ }
+
+ function sign(payload: Record<string, unknown>, audience: string): string {
+ return jwt.sign(payload, privateKey, {
+ algorithm: 'RS256',
+ issuer: 'control-api',
+ audience,
+ expiresIn: 60,
+ })
+ }
+
+ function platformToken(): string {
+ return sign(
+ {
+ sub: 'default/research-host',
+ hostRefs: ['research-host'],
+ workflowControlScopes: ['llm:codex:execute'],
+ scope: 'workflow:approval:request',
+ },
+ 'workflow-approvals'
+ )
+ }
+
+ let ticketSeq = 1
+
+ function ticket(requestHash: string): string {
+ ticketSeq += 1
+ return sign(
+ {
+ jti: `11111111-1111-4111-8111-${String(ticketSeq).padStart(12, '0')}`,
+ typ: 'codex-execution-ticket',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId: `att-${ticketSeq}`,
+ },
+ 'codex-llm-proxy'
+ )
+ }
+
+ function completionRequest(
+ schemaVersion: 'codex-completion-request.v1' | 'codex-completion-request.v2',
+ content = 'hi'
+ ) {
+ ticketSeq += 1
+ return {
+ schemaVersion,
+ requestId: `req-gate-${ticketSeq}`,
+ idempotencyKey: `idem-gate-${ticketSeq}`,
+ provider: 'codex-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content }],
+ }
+ }
+
+ function hangStream() {
+ let releaseHeld!: () => void
+ const held = new Promise<void>(resolve => {
+ releaseHeld = resolve
+ })
+ return {
+ release: () => releaseHeld(),
+ impl: async () => {
+ await held
+ return { outcome: 'canceled' as const }
+ },
+ }
+ }
+
+ async function waitFor(predicate: () => boolean, label: string): Promise<void> {
+ const started = Date.now()
+ while (!predicate()) {
+ if (Date.now() - started > 5_000) throw new Error(label)
+ await new Promise(resolve => setTimeout(resolve, 10))
+ }
+ }
+
+ function completionPayload(
+ schemaVersion: 'codex-completion-request.v1' | 'codex-completion-request.v2',
+ content = 'hi'
+ ): { token: string; body: string } {
+ const raw = completionRequest(schemaVersion, content)
+ const parsed = parseCodexCompletionRequest(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashCodexCompletionRequest(parsed.value)
+ return {
+ token: platformToken(),
+ body: JSON.stringify({
+ executionTicket: ticket(requestHash),
+ requestHash,
+ request: raw,
+ }),
+ }
+ }
+
+ async function postCompletion(
+ port: number,
+ schemaVersion: 'codex-completion-request.v1' | 'codex-completion-request.v2',
+ content = 'hi'
+ ): Promise<Response> {
+ const { token, body } = completionPayload(schemaVersion, content)
+ return fetch(`http://127.0.0.1:${port}/internal/runtime/v1/codex/completions`, {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'content-type': 'application/json',
+ },
+ body,
+ })
+ }
+
+ function postChunked(port: number, token: string): Promise<number> {
+ return new Promise((resolve, reject) => {
+ const socket = connectTcp(port, '127.0.0.1', () => {
+ const chunk = Buffer.from('{}')
+ socket.write(
+ `POST /internal/runtime/v1/codex/completions HTTP/1.1\r\n` +
+ `Host: 127.0.0.1:${port}\r\n` +
+ `Authorization: Bearer ${token}\r\n` +
+ `Content-Type: application/json\r\n` +
+ `Connection: close\r\n` +
+ `Transfer-Encoding: chunked\r\n` +
+ `\r\n` +
+ `${chunk.length.toString(16)}\r\n`
+ )
+ socket.write(chunk)
+ socket.write('\r\n0\r\n\r\n')
+ })
+ const chunks: Buffer[] = []
+ const finish = () => {
+ const raw = Buffer.concat(chunks).toString('utf8')
+ const match = /^HTTP\/1\.1 (\d+)/.exec(raw)
+ if (!match) {
+ reject(new Error(`no status in ${raw.slice(0, 180)}`))
+ return
+ }
+ resolve(Number(match[1]))
+ }
+ socket.setTimeout(2_000, () => {
+ socket.destroy()
+ finish()
+ })
+ socket.on('data', data => {
+ chunks.push(data)
+ if (Buffer.concat(chunks).toString('utf8').includes('\r\n\r\n')) {
+ socket.destroy()
+ finish()
+ }
+ })
+ socket.on('error', err => {
+ if ((err as NodeJS.ErrnoException).code !== 'ECONNRESET') reject(err)
+ })
+ socket.on('close', finish)
+ })
+ }
+
+ describe('visual stream-gate handoff', () => {
+ const hangs: Array<{ release: () => void }> = []
+ const serversToClose: Array<{ close: () => Promise<void> }> = []
+ const listeners: Array<ReturnType<typeof createServer>> = []
+
+ afterEach(async () => {
+ for (const hang of hangs.splice(0)) hang.release()
+ for (const server of serversToClose.splice(0)) await server.close()
+ await Promise.all(
+ listeners.splice(0).map(
+ listener =>
+ new Promise<void>((resolve, reject) =>
+ listener.close(err => (err ? reject(err) : resolve()))
+ )
+ )
+ )
+ await waitFor(
+ () =>
+ visualStreamGate.snapshot().running === 0 &&
+ visualStreamGate.snapshot().queued === 0 &&
+ streamGate.snapshot().running === 0 &&
+ streamGate.snapshot().queued === 0,
+ 'gates did not drain after release'
+ )
+ })
+
+ it('keeps small V1 text off the visual gate while large V2 streams hold it', async () => {
+ expect(VISUAL_STREAM_LIMITS.maxConcurrentStreams).toBe(2)
+ expect(STREAM_LIMITS.maxConcurrentStreams).toBe(8)
+
+ const small = completionPayload('codex-completion-request.v1')
+ const maxBodyBytes = Buffer.byteLength(small.body) + 512
+ const largeContent = 'x'.repeat(maxBodyBytes)
+ const large = completionPayload('codex-completion-request.v2', largeContent)
+ expect(Buffer.byteLength(large.body)).toBeGreaterThan(maxBodyBytes)
+
+ const hang = hangStream()
+ hangs.push(hang)
+ const servers = createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 }), {
+ streamCompletion: hang.impl,
+ })
+ serversToClose.push(servers)
+ const listener = createServer(servers.runtimeApp).listen(0)
+ listeners.push(listener)
+ const address = listener.address()
+ if (!address || typeof address === 'string') throw new Error('listener has no port')
+ const port = address.port
+
+ const firstVisual = postCompletion(port, 'codex-completion-request.v2', largeContent)
+ const secondVisual = postCompletion(port, 'codex-completion-request.v2', largeContent)
+ await waitFor(
+ () => visualStreamGate.snapshot().running === 2 && streamGate.snapshot().running === 0,
+ 'large V2 did not hold the visual gate'
+ )
+
+ const v1 = postCompletion(port, 'codex-completion-request.v1')
+ await waitFor(
+ () => streamGate.snapshot().running === 1 && visualStreamGate.snapshot().running === 2,
+ 'small V1 waited on the visual gate instead of the ordinary stream gate'
+ )
+
+ const queued = Array.from({ length: VISUAL_STREAM_LIMITS.maxQueuedRequests }, () =>
+ postCompletion(port, 'codex-completion-request.v2', largeContent)
+ )
+ await waitFor(
+ () => visualStreamGate.snapshot().queued === VISUAL_STREAM_LIMITS.maxQueuedRequests,
+ 'visual queue did not fill to 8'
+ )
+ const overflow = await postCompletion(port, 'codex-completion-request.v2', largeContent)
+ expect(overflow.status).toBe(503)
+ expect(await overflow.json()).toEqual({ error: 'provider_unavailable' })
+
+ const textWhileSaturated = postCompletion(port, 'codex-completion-request.v1')
+ await waitFor(
+ () => streamGate.snapshot().running === 2 && visualStreamGate.snapshot().running === 2,
+ 'a small V1 was rejected or queued behind saturated image streams'
+ )
+
+ hang.release()
+ await Promise.all([v1, textWhileSaturated, firstVisual, secondVisual, ...queued])
+ })
+
+ it('does not queue a chunked platform body behind saturated image streams', async () => {
+ const small = completionPayload('codex-completion-request.v1')
+ const maxBodyBytes = Buffer.byteLength(small.body) + 512
+ const largeContent = 'x'.repeat(maxBodyBytes)
+ const hang = hangStream()
+ hangs.push(hang)
+ const servers = createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 }), {
+ streamCompletion: hang.impl,
+ })
+ serversToClose.push(servers)
+ const listener = createServer(servers.runtimeApp).listen(0)
+ listeners.push(listener)
+ const address = listener.address()
+ if (!address || typeof address === 'string') throw new Error('listener has no port')
+ const port = address.port
+
+ const firstVisual = postCompletion(port, 'codex-completion-request.v2', largeContent)
+ const secondVisual = postCompletion(port, 'codex-completion-request.v2', largeContent)
+ await waitFor(
+ () => visualStreamGate.snapshot().running === 2 && visualStreamGate.snapshot().queued === 0,
+ 'large V2 did not fill the visual gate'
+ )
+
++ // #731 R3-2 body admission refuses a body of undeclared length before it
++ // reaches the transport budget, so the answer arrives while both visual
++ // slots are still held.
+ const status = await postChunked(port, platformToken())
- expect(status).toBe(400)
++ expect(status).toBe(411)
+ expect(visualStreamGate.snapshot()).toEqual({ running: 2, queued: 0 })
+
+ hang.release()
+ await Promise.all([firstVisual, secondVisual])
+ })
+
+ it('rejects a between-cap V1 with 413 and leaves the visual gate empty', async () => {
+ const small = completionPayload('codex-completion-request.v1')
+ const maxBodyBytes = Buffer.byteLength(small.body) + 512
+ const largeContent = 'x'.repeat(maxBodyBytes)
+ const large = completionPayload('codex-completion-request.v1', largeContent)
+ expect(Buffer.byteLength(large.body)).toBeGreaterThan(maxBodyBytes)
+
+ const servers = createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 }))
+ serversToClose.push(servers)
+ const listener = createServer(servers.runtimeApp).listen(0)
+ listeners.push(listener)
+ const address = listener.address()
+ if (!address || typeof address === 'string') throw new Error('listener has no port')
+ const port = address.port
+
+ const response = await fetch(`http://127.0.0.1:${port}/internal/runtime/v1/codex/completions`, {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${large.token}`,
+ 'content-type': 'application/json',
+ },
+ body: large.body,
+ })
+ expect(response.status).toBe(413)
+ expect(await response.json()).toEqual({ error: 'payload_too_large' })
+ expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ expect(streamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ })
+
+ it('releases the visual slot for a whitespace-padded small V2', async () => {
+ const small = completionPayload('codex-completion-request.v2')
+ const maxBodyBytes = Buffer.byteLength(small.body) + 64
+ const padded = `${small.body}${' '.repeat(maxBodyBytes - Buffer.byteLength(small.body) + 1)}`
+ expect(Buffer.byteLength(padded)).toBeGreaterThan(maxBodyBytes)
+
+ const hang = hangStream()
+ hangs.push(hang)
+ const servers = createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 }), {
+ streamCompletion: hang.impl,
+ })
+ serversToClose.push(servers)
+ const listener = createServer(servers.runtimeApp).listen(0)
+ listeners.push(listener)
+ const address = listener.address()
+ if (!address || typeof address === 'string') throw new Error('listener has no port')
+ const port = address.port
+
+ const response = fetch(`http://127.0.0.1:${port}/internal/runtime/v1/codex/completions`, {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${small.token}`,
+ 'content-type': 'application/json',
+ },
+ body: padded,
+ })
+ await waitFor(
+ () => streamGate.snapshot().running === 1 && visualStreamGate.snapshot().running === 0,
+ 'padded small V2 kept the visual slot instead of the ordinary stream gate'
+ )
+ hang.release()
+ await response
+ })
+ })
diff --cc control-api/package-lock.json
index a5035d477,716800e60..beaecc0fd
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@@ -1,12 -1,12 +1,12 @@@
{
"name": "clerum-control-api",
- "version": "0.1.607",
- "version": "0.1.601",
++ "version": "0.1.608",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.607",
- "version": "0.1.601",
++ "version": "0.1.608",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --cc control-api/package.json
index 59d3d2ffd,a4c6f4544..9919d7f2e
--- a/control-api/package.json
+++ b/control-api/package.json
@@@ -1,6 -1,6 +1,6 @@@
{
"name": "clerum-control-api",
- "version": "0.1.607",
- "version": "0.1.601",
++ "version": "0.1.608",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --cc control-api/src/services/llmProviderAttemptAuthorizer.ts
index 287e71bc3,3781cff6a..a17fe1942
--- a/control-api/src/services/llmProviderAttemptAuthorizer.ts
+++ b/control-api/src/services/llmProviderAttemptAuthorizer.ts
@@@ -150,16 -155,6 +155,17 @@@ export { computeCodexPolicyHash
// body root, and may itself nest maxNestingDepth containers.
const MAX_AUTHORIZE_BODY_DEPTH = Math.max(LIMITS.maxNestingDepth, GROK_LIMITS.maxNestingDepth) + 6
+/**
+ * #731 — room for the authorize envelope around the contract-capped `request`:
+ * ids, revisions, hashes and recipe names, a few hundred bytes in practice.
+ * The whole-body check bounds serialization cost before parsing; the request
+ * itself is held to maxRequestBodyBytes by the contract parser, so a request
+ * at the cap is never refused for its envelope. The gateway's
- * client_max_body_size on this route is the cap plus this allowance.
++ * client_max_body_size on this route is the larger of the cap plus this
++ * allowance and the V2 visual envelope (#660).
+ */
+export const AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES = 16 * 1024
+
/**
* Reject an over-deep body before anything serializes it. Iterative, so an
* attacker-controlled nesting depth cannot overflow the stack here; without it
@@@ -625,11 -617,17 +631,28 @@@ export async function authorizeLlmProvi
}
assertBodyNestingWithinLimit(body)
const serialized = JSON.stringify(body)
- if (Buffer.byteLength(serialized, 'utf8') > requestBodyLimitBytes(body.request)) {
++ // The larger of the two budgets wins, as on the gateway's client_max_body_size:
++ // the non-image cap plus the envelope allowance (#731), or the V2 visual
++ // envelope (#660). The contract parser below still holds `request` itself to
++ // its own schema's cap.
++ const wholeBodyLimit = Math.max(
++ requestBodyLimitBytes(body.request),
++ LIMITS.maxRequestBodyBytes + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES
++ )
++ if (Buffer.byteLength(serialized, 'utf8') > wholeBodyLimit) {
+ throw new LlmProviderAttemptAuthorizeError(
+ 'payload_too_large',
+ 'request body exceeds the limit'
+ )
+ }
- if (measureNonImageAuthorizeBytes(body) > LIMITS.maxRequestBodyBytes) {
+ if (
- Buffer.byteLength(serialized, 'utf8') >
++ measureNonImageAuthorizeBytes(body) >
+ LIMITS.maxRequestBodyBytes + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES
+ ) {
- throw new LlmProviderAttemptAuthorizeError('invalid_request', 'request body exceeds the limit')
+ throw new LlmProviderAttemptAuthorizeError(
+ 'payload_too_large',
+ 'authorize wrapper exceeds the non-image limit'
+ )
}
const unknown = firstUnknownKey(body)
if (unknown) {
diff --cc control-api/test/deploy.llmAuthorizeBodyLimit.test.ts
index 8151ee512,000000000..2318d6228
mode 100644,000000..100644
--- a/control-api/test/deploy.llmAuthorizeBodyLimit.test.ts
+++ b/control-api/test/deploy.llmAuthorizeBodyLimit.test.ts
@@@ -1,37 -1,0 +1,44 @@@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { LIMITS as GROK_LIMITS } from '@clerum/grok-provider-attempt-contract'
+import { LIMITS as CODEX_LIMITS } from '@clerum/llm-provider-attempt-contract'
+import { AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES } from '../src/services/llmProviderAttemptAuthorizer.js'
+
+const AUTHORIZE_LOCATION = 'location = /api/v1/mcp-host/llm/provider-attempts/authorize {'
+
+/** The body of one nginx `location` block, from its opening line to its closing brace. */
+function locationBlock(config: string, opening: string): string {
+ const start = config.indexOf(opening)
+ expect(start, `configmaps.yaml must declare ${opening}`).toBeGreaterThanOrEqual(0)
+ const end = config.indexOf('\n }', start)
+ expect(end).toBeGreaterThan(start)
+ return config.slice(start, end)
+}
+
+describe('LLM authorize route body limit (#731 R3-3)', () => {
- it('T-R3-3d sets the gateway body limit to the request cap plus the envelope allowance', () => {
++ it('T-R3-3d covers the request cap plus the envelope allowance with one gateway directive', () => {
+ const config = readFileSync(
+ new URL('../../deploy/base/control-plane/configmaps.yaml', import.meta.url),
+ 'utf-8'
+ )
+ const block = locationBlock(config, AUTHORIZE_LOCATION)
+ // Witness: this is the block that proxies to control-api.
+ expect(block).toContain('proxy_pass http://control_api_upstream;')
+ const directive = /client_max_body_size\s+(\d+);/.exec(block)
+ expect(
+ directive,
+ 'the authorize location must set client_max_body_size in bytes'
+ ).not.toBeNull()
++ // nginx refuses to start when a location repeats the directive.
++ expect(block.match(/client_max_body_size/g)).toHaveLength(1)
+ // Without the directive nginx applies its 1m default and refuses a
- // contract-valid request before control-api sees it.
++ // contract-valid request before control-api sees it. The same directive
++ // also carries the Codex V2 visual envelope (#660), so it is the larger of
++ // the two budgets.
+ const cap = Math.max(CODEX_LIMITS.maxRequestBodyBytes, GROK_LIMITS.maxRequestBodyBytes)
- expect(Number(directive![1])).toBe(cap + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES)
++ expect(Number(directive![1])).toBe(
++ Math.max(cap + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES, CODEX_LIMITS.maxVisualRequestBodyBytes)
++ )
++ expect(Number(directive![1])).toBeGreaterThanOrEqual(cap + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES)
+ })
+})
diff --cc control-api/test/network.gateway.intent.test.ts
index aa7ab77d0,b9358e863..e142493cf
--- a/control-api/test/network.gateway.intent.test.ts
+++ b/control-api/test/network.gateway.intent.test.ts
@@@ -369,6 -369,23 +369,25 @@@ describe('network/gateway intent (manif
expect(gatewayConf).not.toContain('/api/v1/external/')
})
+ it('keeps the Codex authorize route at the 24MiB visual envelope', () => {
+ const configmaps = read(`${BASE}/control-plane/configmaps.yaml`)
+ const gatewayConf = docContaining(yamlDocs(configmaps), 'name: nginx-workflow-approval-gateway')
+ const authorize = locationBlock(
+ gatewayConf,
+ 'location = /api/v1/mcp-host/llm/provider-attempts/authorize'
+ )
+ expect(authorize).toContain('client_max_body_size 25165824;')
+ expect(gatewayConf.match(/client_max_body_size/g)).toHaveLength(1)
+ })
+
+ it('pins the shipped Codex proxy visual envelope to 24MiB', () => {
+ const proxy = read(`${BASE}/control-plane/codex-llm-proxy.yaml`)
- expect(proxy).toContain('CODEX_LLM_PROXY_MAX_BODY_BYTES: "1048576"')
++ // #731: the ordinary body limit is derived from the contract cap plus the
++ // envelope allowance, so the manifest must not pin it to a literal.
++ expect(proxy).not.toMatch(/^\s*CODEX_LLM_PROXY_MAX_BODY_BYTES:/m)
+ expect(proxy).toContain('CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES: "25165824"')
+ })
+
it('keeps the profile-control-funnel body cap at gfsc write-cap parity (24MiB)', () => {
const configmaps = read(`${BASE}/profiles/configmaps.yaml`)
const funnelConf = docContaining(yamlDocs(configmaps), 'name: profile-control-funnel-nginx')
diff --cc control-api/test/services.llmProviderAttemptAuthorizer.test.ts
index d6556b078,a0a84d9ca..b17ac8419
--- a/control-api/test/services.llmProviderAttemptAuthorizer.test.ts
+++ b/control-api/test/services.llmProviderAttemptAuthorizer.test.ts
@@@ -1,7 -1,20 +1,21 @@@
import { beforeEach, describe, expect, it, vi } from 'vitest'
- import { LIMITS, hashCodexCompletionRequestV1 } from '@clerum/llm-provider-attempt-contract'
+ import { readFileSync } from 'node:fs'
+ import { createRequire } from 'node:module'
+ import {
+ LIMITS,
+ VISUAL_LIMITS,
+ hashCodexCompletionRequestV1,
+ } from '@clerum/llm-provider-attempt-contract'
+ import { streamCodexCompletion } from '../../codex-llm-proxy/src/codexTransport'
+ import {
+ CODEX_CATALOG_ORIGIN,
+ CODEX_COMPLETIONS_ORIGIN,
+ } from '../../codex-llm-proxy/src/originPolicy'
+ import { CodexLlmProxyClient } from '../../mcp-host/src/llm/codexLlmProxyClient'
+ import { CodexSubscriptionProvider } from '../../mcp-host/src/llm/codexSubscription'
+ import { ProviderAttemptAuthorizer } from '../../mcp-host/src/llm/providerAttemptAuthorizer'
import {
+ AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES,
LlmProviderAttemptAuthorizeError,
type LlmProviderAttemptAuthorizerDeps,
authorizeLlmProviderAttempt,
@@@ -226,6 -598,153 +599,160 @@@ describe('authorizeLlmProviderAttempt'
).rejects.toMatchObject({ code: 'unknown_field' })
})
+ it('rejects a V2 authorize wrapper whose invocationId is not a bounded id', async () => {
+ await expect(
+ authorizeLlmProviderAttempt(
+ claims(),
+ body({
+ request: { ...REQUEST, schemaVersion: 'codex-completion-request.v2' },
+ invocationId: 'x'.repeat(200),
+ }),
+ current
+ )
+ ).rejects.toMatchObject({ code: 'invalid_request' })
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+
+ it('maps a contract size limit to payload_too_large', async () => {
+ const oversizeBase64 = 'A'.repeat(4 * Math.ceil(VISUAL_LIMITS.maxImageBytes / 3) + 4)
+ await expect(
+ authorizeLlmProviderAttempt(
+ claims(),
+ body({
+ request: {
+ ...REQUEST,
+ schemaVersion: 'codex-completion-request.v2',
+ messages: [
+ {
+ role: 'user' as const,
+ content: 'look',
+ contentParts: [
+ { type: 'text' as const, text: 'look' },
+ {
+ type: 'image' as const,
+ mimeType: 'image/png',
+ data: oversizeBase64,
+ source: {
+ kind: 'attachment' as const,
+ attachmentId: 'att_1',
+ messageId: 'msg-1',
+ },
+ },
+ ],
+ },
+ ],
+ },
+ }),
+ current
+ )
+ ).rejects.toMatchObject({ code: 'payload_too_large' })
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ }, 30_000)
+
+ it('maps a contract count limit to invalid_request, not payload_too_large', async () => {
+ await expect(
+ authorizeLlmProviderAttempt(
+ claims(),
+ body({
+ request: {
+ ...REQUEST,
+ schemaVersion: 'codex-completion-request.v2',
+ messages: Array.from({ length: 1025 }, () => ({ role: 'user' as const, content: 'x' })),
+ },
+ }),
+ current
+ )
+ ).rejects.toMatchObject({ code: 'invalid_request' })
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+
+ it('maps a contract range limit to invalid_request, not payload_too_large', async () => {
+ await expect(
+ authorizeLlmProviderAttempt(
+ claims(),
+ body({
+ request: {
+ ...REQUEST,
+ schemaVersion: 'codex-completion-request.v2',
+ generation: { maxOutputTokens: 99_999 },
+ },
+ }),
+ current
+ )
+ ).rejects.toMatchObject({ code: 'invalid_request' })
+ await expect(
+ authorizeLlmProviderAttempt(
+ claims(),
+ body({
+ request: {
+ ...REQUEST,
+ schemaVersion: 'codex-completion-request.v2',
+ deadlineMs: LIMITS.maxDeadlineMs + 1,
+ },
+ }),
+ current
+ )
+ ).rejects.toMatchObject({ code: 'invalid_request' })
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+
- it('keeps the authorize wrapper on the 1 MiB non-image budget when the nested request is V2', async () => {
++ it('keeps the authorize wrapper on the non-image budget when the nested request is V2', async () => {
++ // One byte past the non-image cap plus the envelope allowance: well under
++ // the 24 MiB visual envelope a V2 declaration opens for image bytes.
+ await expect(
+ authorizeLlmProviderAttempt(
+ claims(),
+ body({
+ request: { ...REQUEST, schemaVersion: 'codex-completion-request.v2' },
- targetRef: 't'.repeat(2 * MIB),
++ targetRef: 't'.repeat(
++ LIMITS.maxRequestBodyBytes + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES + 1
++ ),
+ }),
+ current
+ )
- ).rejects.toMatchObject({ code: 'payload_too_large' })
++ ).rejects.toMatchObject({
++ code: 'payload_too_large',
++ message: 'authorize wrapper exceeds the non-image limit',
++ })
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+
+ it('maps an over-dimension image to payload_too_large', async () => {
+ const current = deps()
+ await expect(
+ authorizeLlmProviderAttempt(
+ claims(),
+ body({
+ request: {
+ ...REQUEST,
+ schemaVersion: 'codex-completion-request.v2',
+ messages: [
+ {
+ role: 'user' as const,
+ content: 'look',
+ contentParts: [
+ { type: 'text' as const, text: 'look' },
+ {
+ type: 'image' as const,
+ mimeType: 'image/png',
+ data: declaredHeaderPng(3000, 3000).toString('base64'),
+ source: {
+ kind: 'attachment' as const,
+ attachmentId: 'att_1',
+ messageId: 'msg-1',
+ },
+ },
+ ],
+ },
+ ],
+ },
+ }),
+ current
+ )
+ ).rejects.toMatchObject({ code: 'payload_too_large' })
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+
it('rejects a non-UUID Plugin Workload SDK attempt id', async () => {
await expect(
authorizeLlmProviderAttempt(
@@@ -661,66 -1180,4 +1188,66 @@@
).rejects.toMatchObject({ code: 'disabled' })
expect(current.insertAttempt).not.toHaveBeenCalled()
})
+
+ // #731 R3-3: the byte cap belongs to `request`; the authorize envelope around
+ // it gets its own allowance, as the proxies' body limit does (R2-6).
+ describe('request cap and envelope allowance (#731 R3-3)', () => {
+ /** REQUEST padded so that JSON.stringify(request) is exactly `bytes` long. */
+ function requestOfBytes(bytes: number) {
+ const base = Buffer.byteLength(JSON.stringify(REQUEST), 'utf8')
+ const content = 'x'.repeat(REQUEST.messages[0]!.content.length + bytes - base)
+ const request = { ...REQUEST, messages: [{ role: 'user' as const, content }] }
+ expect(Buffer.byteLength(JSON.stringify(request), 'utf8')).toBe(bytes)
+ return request
+ }
+
+ it('T-R3-3a authorizes a request just under the cap although the whole body is over it', async () => {
+ const request = requestOfBytes(LIMITS.maxRequestBodyBytes - 64)
+ const payload = body({ request })
+ // Fixture check: the envelope takes the whole body past the request cap.
+ expect(Buffer.byteLength(JSON.stringify(payload), 'utf8')).toBeGreaterThan(
+ LIMITS.maxRequestBodyBytes
+ )
+ const result = await authorizeLlmProviderAttempt(claims(), payload, current)
+ expect(result).toMatchObject({
+ executionTicket: 'ticket.jwt',
+ requestHash: hashCodexCompletionRequestV1(request),
+ })
+ expect(current.insertAttempt).toHaveBeenCalledTimes(1)
+ })
+
+ it('T-R3-3b refuses a request one byte over the cap with the contract message', async () => {
+ const request = requestOfBytes(LIMITS.maxRequestBodyBytes + 1)
+ await expect(
+ authorizeLlmProviderAttempt(claims(), body({ request }), current)
+ ).rejects.toMatchObject({
- code: 'invalid_request',
++ code: 'payload_too_large',
+ message: 'request exceeds maxRequestBodyBytes',
+ })
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ // Witness: the same authorizer admits the request once it fits.
+ await authorizeLlmProviderAttempt(
+ claims(),
+ body({ request: requestOfBytes(LIMITS.maxRequestBodyBytes) }),
+ current
+ )
+ expect(current.insertAttempt).toHaveBeenCalledTimes(1)
+ })
+
+ it('T-R3-3c refuses a body one byte past the cap plus the envelope allowance', async () => {
+ const request = requestOfBytes(LIMITS.maxRequestBodyBytes)
+ const withoutFiller = Buffer.byteLength(
+ JSON.stringify(body({ request, recipeName: '' })),
+ 'utf8'
+ )
+ const limit = LIMITS.maxRequestBodyBytes + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES
+ const payload = body({ request, recipeName: 'r'.repeat(limit + 1 - withoutFiller) })
+ expect(Buffer.byteLength(JSON.stringify(payload), 'utf8')).toBe(limit + 1)
+ await expect(authorizeLlmProviderAttempt(claims(), payload, current)).rejects.toMatchObject({
- code: 'invalid_request',
++ code: 'payload_too_large',
+ message: 'request body exceeds the limit',
+ })
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+ })
})
diff --cc deploy/base/control-plane/codex-llm-proxy.yaml
index c8d65be0e,d8cf25cb2..5a59bbdea
--- a/deploy/base/control-plane/codex-llm-proxy.yaml
+++ b/deploy/base/control-plane/codex-llm-proxy.yaml
@@@ -18,6 -18,10 +18,11 @@@ data
CODEX_LLM_PROXY_RUNTIME_PORT: "8080"
CODEX_LLM_PROXY_ADMIN_PORT: "8081"
CODEX_LLM_PROXY_PROBE_PORT: "9090"
- CODEX_LLM_PROXY_MAX_BODY_BYTES: "1048576"
++ # CODEX_LLM_PROXY_MAX_BODY_BYTES is deliberately unset: the proxy derives it
++ # from LIMITS.maxRequestBodyBytes plus the envelope allowance (#731), and it
++ # governs ordinary and anonymous requests.
+ # V2 visual envelope. Keep this equal to LIMITS.maxVisualRequestBodyBytes.
- # Ordinary and anonymous requests still use CODEX_LLM_PROXY_MAX_BODY_BYTES.
+ CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES: "25165824"
CODEX_LLM_PROXY_MAX_STREAM_DURATION_MS: "300000"
CODEX_LLM_PROXY_MAX_DEADLINE_MS: "300000"
CODEX_LLM_PROXY_JWT_ISSUER: control-api
diff --cc deploy/base/control-plane/configmaps.yaml
index b59a3b9c1,21da00271..ae88f8ac8
--- a/deploy/base/control-plane/configmaps.yaml
+++ b/deploy/base/control-plane/configmaps.yaml
@@@ -801,6 -799,9 +801,13 @@@ data
}
location = /api/v1/mcp-host/llm/provider-attempts/authorize {
+ # V2 carries bounded inline images; keep the larger body allowance
+ # on this authenticated authorization route, not the whole gateway.
++ # It also covers the #731 non-image request cap (8 MiB) plus
++ # control-api's 16 KiB authorize envelope allowance, which nginx's
++ # 1m default would refuse before control-api sees it. nginx refuses
++ # to start when a location repeats this directive.
+ client_max_body_size 25165824;
limit_except POST {
deny all;
}
diff --cc docs/architecture/codex-subscription-transport-contract.md
index d985f54ca,811f2f205..a3baf1b44
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@@ -2,6 -2,102 +2,110 @@@
Frozen protocol version: `codex-subscription-transport.v1`.
+ Request schemas: `codex-completion-request.v1` for ordinary text and
+ `codex-completion-request.v2` for ordered visual content (including text parts
+ left after media pruning). The transport, execution-ticket type and receipt
+ version remain V1. Request V2 does not imply a transport protocol upgrade.
+
+ ## Visual requests (issue #650)
+
+ V2 user messages may carry `contentParts`: ordered text parts or inline PNG/JPEG
+ parts. Images contain `mimeType`, canonical base64 `data`, and a closed `source`
+ identity: `{ kind: 'attachment', attachmentId, messageId }` or
+ `{ kind: 'tool', attachmentId, toolCallId }`. Sources are established by the Host
+ message/tool producers, included in the canonical request hash, and omitted from
+ the upstream projection. They are attribution inside the authorized request,
+ not permission to fetch another object. No arbitrary URL is accepted.
+
+ The text parts joined with a newline must equal the message's `content`.
+ Producers synchronize the fields when adding turn context. After media pruning,
+ the remaining text parts are authoritative, so redaction text is preserved.
+ Ordinary V1 textual requests retain their existing wire representation and hashes.
+
+ Tool-image source retention is enabled only when a configured primary or fallback
+ provider requires source identity. Pure API-key chains keep the existing loop
+ deduplication and message shape. Mixed chains retain distinct source identities
+ in canonical history; each provider adapter selects its own view without mutating
+ that history. The internal `sourceIdentityOnly` marker identifies extra copies and
+ never enters the Codex request schema. API-key adapters omit those copies when an
+ unmarked representative remains. If pruning removed that representative, they
+ retain one remaining image per MIME/bytes pair and its explanatory text. They do
+ not restore pixels removed by pruning. The user-facing attachment collection
+ keeps its existing deduplication behavior.
+
+ Local visual budgets have two layers. The usual product target is 5 MiB decoded
+ per image, 9 MiB decoded across a request, and a 14 MiB envelope at 2048 pixels
+ (the official Codex client size, with `detail: high`). The hard ceiling is 20
+ images, 16 MiB per image and 16 MiB aggregate so a poorly compressed 2048
+ PNG may exceed 10 MiB; the HTTP envelope stays 24 MiB so that encoded body
+ still fits. Dimensions above 2048 px are rejected here because the frozen
+ ChatGPT endpoint 400s them; that is a model/pixel limit, not a byte limit.
+ For `codex-subscription`, visual input is on by default for every catalog model.
+ Which non-Codex providers accept images is owned by issue #654 / PR #669
+ (models.dev). These byte numbers are conservative Evenfire limits, not
+ upstream facts.
+ The shared pure validator checks canonical base64, MIME/container framing and
+ header dimensions; it does not decode pixels or prove image decodability.
+ The fixtures contain independently decoded 2x2 PNG/JPEG images.
+
-V1 keeps its existing 1 MiB request/envelope ceiling. V2 has a 24 MiB ceiling
-for the complete serialized request and HTTP envelope, including base64,
-history and the signed execution ticket. V2 text, tools and other non-image
-fields remain bounded to 1 MiB, measured with only image data blanked in a
-temporary size projection; the actual request and its hash are not modified.
++V1 keeps the `maxRequestBodyBytes` request ceiling (8 MiB, #731); its envelope
++adds a 16 KiB allowance on the proxy and on the authorizer. V2 has a 24 MiB
++ceiling for the complete serialized request and HTTP envelope, including
++base64, history and the signed execution ticket. V2 text, tools and other
++non-image fields remain bounded to `maxRequestBodyBytes`, measured with only
++image data blanked in a temporary size projection; the actual request and its
++hash are not modified. The two caps are not additive: a V2 request carrying a
++hard-ceiling image (16 MiB decoded, about 21.3 MiB encoded) has about 2.7 MiB
++left for non-image data before the 24 MiB envelope refuses it.
+ The authorizer builds the exact V2 proxy envelope inside its transaction after
+ signing but before commit. Exceeding the bound rolls back the new attempt,
+ ticket and new reservation; it does not call the receipt finalizer before redeem.
+ The Host uses the same envelope builder. V2 has no outer deadline: its deadline
+ is `request.deadlineMs`, part of the authorized hash. A proxy configured below
+ the shared visual envelope budget refuses to start.
+
+ Desktop enforces the 16 MiB individual and 16 MiB combined hard attachment
+ budgets (usual target remains 5 / 9 MiB).
+ RPC and Host permit a 24 MiB JSON body only on their message POST routes; chat
+ non-image bytes stay on the 6 MiB share. Non-chat rpc-proxy and Host control
+ routes keep the 10 MB ordinary JSON cap. The proxy's larger
+ parser requires a valid platform identity on the visual completion route.
+ Admin and unauthenticated requests retain the ordinary configured body limit.
+ `CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES` controls the visual transport ceiling;
-`CODEX_LLM_PROXY_MAX_BODY_BYTES` continues to control ordinary requests.
++`CODEX_LLM_PROXY_MAX_BODY_BYTES` continues to control ordinary requests; the
++manifest leaves it unset so the proxy derives it from the contract cap plus the
++envelope allowance.
+ The internal authorization gateway also permits 24 MiB only at the exact
-`/api/v1/mcp-host/llm/provider-attempts/authorize` POST location. Other locations
++`/api/v1/mcp-host/llm/provider-attempts/authorize` POST location. That single
++`client_max_body_size` also covers the V1 cap plus the authorize envelope
++allowance, which is smaller. Other locations
+ retain their prior limits, and the Authorization header and method restrictions
+ are unchanged.
+
+ The proxy projects parts to Responses `input_text` and `input_image` items with
+ an inline data URL. The shape is grounded in the official Codex client
+ [ContentItem and ImageReference definitions](https://github.com/openai/codex/blob/fc2ea82e7eff22c618a56db29c68a6b1967cba7d/codex-rs/protocol/src/models.rs#L878).
+ This source evidence is not a successful call to Evenfire's frozen endpoint.
+
+ Visual input is on by default for every `codex-subscription` model. Catalog
+ authorization still decides which model a Host may call; this transport does
+ not keep a second model-vision allowlist. To stop all Codex traffic, use the
+ existing kill switches (`MCP_HOST_CODEX_SUBSCRIPTION_ENABLED` and
+ `CODEX_LLM_PROXY_EXECUTION_ENABLED`). Missing image provenance returns
+ `image_source_invalid`. Limit errors, including HTTP 413 without a JSON body,
+ remain non-retryable. Images are never silently stripped and do not trigger
+ automatic fallback.
+
+ Deploy accepting consumers before visual senders. An old consumer must reject
+ V2 explicitly; do not translate V2 to text to work around that rejection. On
+ rollback set `CODEX_LLM_PROXY_EXECUTION_ENABLED=false`, drain attempts, then
+ restore consumers.
+ Do not roll back to a sender that silently discards images without a front guard.
+ Committed abandoned attempts retain their audit identity. Existing ticket and
+ budget TTLs, rather than the receipt finalizer, bound their execution and pending
+ budget; a new physical attempt must have a fresh attempt binding. Tests of these
+ lifecycle guarantees and a real upstream image check are separate acceptance lanes.
+
This document is the Phase 0 architecture freeze for provider `codex-subscription`.
It is not a runtime client and does not authorize API-key billing.
diff --cc docs/testing/codex-subscription-validation.md
index 006d47bda,b74549aba..7ad52928c
--- a/docs/testing/codex-subscription-validation.md
+++ b/docs/testing/codex-subscription-validation.md
@@@ -2,6 -2,100 +2,101 @@@
Evidence lanes for `codex-subscription`. One lane does not stand in for another.
+ ## Image input validation (#650)
+
+ The shared package tests V1 golden-hash stability and V2 parsing, source identity,
+ ordered text/image content and local image/envelope budgets. Its
+ `fixtures/visual-requests.json` contains real 2x2 PNG/JPEG samples;
+ `fixtures/canonical-request-hashes.v2.json` freezes the new projection separately.
+ The image parser validates container structure and dimensions, not decoded pixels.
+
+ Capacity checks cover the usual 5 / 9 / 14 MiB target and the hard 16 MiB
+ per-image / 16 MiB aggregate / 24 MiB envelope ceiling, plus the 2048 px
+ model bound. Exercise 5 MiB, 12 MiB (exceptional, above 10 MiB), 10+5 MiB
-and 3x5 MiB acceptance, plus overflow above 16 MiB. V1 and V2 non-image fields keep a 1 MiB ceiling;
++and 3x5 MiB acceptance, plus overflow above 16 MiB. V1 and V2 non-image fields keep an 8 MiB ceiling
++(#731), and beside a hard-ceiling image the 24 MiB envelope leaves about 2.7 MiB of non-image data;
+ chat non-image bytes stay at 6 MiB; unrelated rpc-proxy and Host control routes keep the 10 MB ordinary JSON cap. The larger proxy parser must not admit an
+ anonymous, wrong-scope or admin request, or enlarge V1's effective body limit.
+ Changing these budgets does not change OAuth, grants, ticket binding, origins,
+ fallback, or connection selection. Local capacity evidence is separate from
+ successful image interpretation by a real model.
+
+ For an already bootstrapped local profile whose required public images are
+ present, `MINIKUBE_BUILD_IMAGE_ARGS=--skip-public` forwards the existing builder
+ option through the public Make entry point. This avoids pulling unrelated demo
+ images during a full source rebuild. Keep the normal image verification and
+ runtime readiness gates; this option is not a substitute for bootstrap.
+ When reconciling an existing profile configured through Control UI, use
+ `MINIKUBE_REAPPLY_INSTANCES=false` to preserve its Host and other bootstrap
+ instance configuration. This does not skip core manifests, CRDs, image checks,
+ or readiness. Leave the default enabled for initial bootstrap. Verify the
+ Host's provider/model/connection binding before and after the update.
+
+ Provider tests must cover both completion methods, direct/tool origins, prompt
+ context, redacted text parts and repeated bytes from distinct tool calls.
+ Proxy conformance inspects the final upstream body,
+ asserts provenance does not become model input, and retains tools/cancel/SSE
+ checks. Authorizer tests require a pre-commit exact-envelope check; its PostgreSQL
+ case must prove rollback against a real transaction. A mocked transaction result
+ does not satisfy that PostgreSQL gate.
+
+ Visual input is on by default for every `codex-subscription` model. No test
+ fixture or passing conformance suite certifies that the real endpoint or
+ selected model sees images.
+
+ Keep browser/Electron evidence separate: visible login and Host selection, upload
+ through Add context / Upload Files, preview, send, correlated task completion and
+ visible answer. Assert a business signal tied to the submitted image and current
+ task; an answer saying it saw an image is insufficient. Do not use SDK text-only
+ journeys or GFS file upload as substitutes for composer image input. Run the E2E
+ static auditor on changed browser specs and record external prerequisites rather
+ than silently skipping them.
+
+ ### Opt-in Desktop image lane
+
+ `desktop-app/test/e2e-playwright/codex-image-input.spec.ts` covers direct PNG/JPEG
+ uploads through the visible composer, including a 5 MiB JPEG, a 12 MiB PNG
+ (exceptional), a 10+5 MiB pair, three 5 MiB images, and composer refusals over
+ 16 MiB per image, a 21st image, and a non-PNG/JPEG type. The 16 MiB aggregate is
+ enforced on the hop, not the composer. It creates a fresh 64-bit hexadecimal
+ challenge rendered only into image pixels. Large cases pad that same image so
+ the answer stays in pixels while the decoded size matches the hop budget. The
+ filename and prompt do not carry the answer. A passing run requires that
+ answer (hexadecimal case is ignored), a non-error response, no tool steps
+ substituting OCR/loading for direct image input, and no fallback badge.
+ The selector's stable data attributes verify the actual selected Host, provider
+ and model. Composer budget and resolution refusals never send.
+
+ This is a real upstream lane, not a mock. Before running it, obtain separate
+ authorization for runtime, upstream access and the existing login fixture's
+ stored-session reset. Provision the owned Host and consumers first. Set:
+
+ - `E2E_CODEX_IMAGE_INPUT=1` and `CODEX_REAL_UPSTREAM_CONFIRM=1` only for that
+ authorized run; `E2E_CODEX_ALLOW_SESSION_RESET=1` acknowledges the fixture's
+ session reset.
+ - `E2E_HOST_REF` to the actual owned Host and `E2E_CODEX_HOST_LABEL` to its
+ exact visible label in the Agents list; there is no shared-host default.
+ - `E2E_CODEX_IMAGE_MODEL` and `E2E_CODEX_IMAGE_MODEL_LABEL` to its model ID and
+ visible picker label. The test does not change deployments or grants.
+
+ Install Host dependencies as well as Desktop dependencies: the neutral challenge
+ uses the existing Host canvas dependency. Node 24 and `verify:electron` remain
+ mandatory. After loading the approved branch-owned service URLs and prerequisites,
+ the command from `desktop-app` is:
+
+ ```bash
+ node node_modules/@playwright/test/cli.js test \
+ --config test/e2e-playwright/playwright.codex-image.config.ts --project codex-image-input
+ ```
+
+ The normal Desktop project excludes this spec. Its dedicated config rejects
+ missing authority or Host/model identity before global setup; it cannot
+ return a successful all-skipped run. The model ID must be the canonical ID
+ returned by the runtime, not an alias. Static audit/typecheck and local challenge-image
+ decoding do not count as browser or real-upstream execution. Typed tool-result
+ images remain a separate integration/runtime journey; this direct-input test
+ does not certify GFS producers or retained image history.
+
## Lanes
- **T0** — unit, schema, hash, contracts, typecheck, lint, build. The
diff --cc mcp-host/package-lock.json
index d3e602f93,cd947ff9e..fcce3d9b0
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@@ -1,12 -1,12 +1,12 @@@
{
"name": "clerum-mcp-host",
- "version": "0.1.405",
- "version": "0.1.368",
++ "version": "0.1.406",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.405",
- "version": "0.1.368",
++ "version": "0.1.406",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --cc mcp-host/package.json
index d48bbe38c,3dc925d7b..1e3a1fb1a
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@@ -1,6 -1,6 +1,6 @@@
{
"name": "clerum-mcp-host",
- "version": "0.1.405",
- "version": "0.1.368",
++ "version": "0.1.406",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --cc mcp-host/src/llm/__tests__/codexLlmProxyClient.test.ts
index 3606849c4,9fa3a9b52..b7e8a435d
--- a/mcp-host/src/llm/__tests__/codexLlmProxyClient.test.ts
+++ b/mcp-host/src/llm/__tests__/codexLlmProxyClient.test.ts
@@@ -108,103 -183,6 +183,103 @@@ describe('CodexLlmProxyClient', () =>
expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
})
+ // #731 — the proxy's body parser refuses an envelope over its limit with
+ // `reject(res, 413, 'payload_too_large')` (codex-llm-proxy/src/server.ts).
+ // That is a size refusal of this conversation, not a failed API call.
+ it('T-R2-6a classifies the proxy 413 payload_too_large as ContextLengthExceeded', async () => {
+ const fetchFn = vi.fn().mockResolvedValue({
+ ok: false,
+ status: 413,
+ json: async () => ({ error: 'payload_too_large' }),
+ })
+ const client = new CodexLlmProxyClient({
+ runtimeUrl: resolveCodexProxyRuntimeUrl(
+ 'http://codex-llm-proxy.control-plane.svc.cluster.local:8080'
+ ),
+ readPlatformJwt: () => 'platform-jwt',
+ fetchFn: fetchFn as unknown as typeof fetch,
+ })
+ const err = await client
+ .stream({ executionTicket: 'ticket-123456', requestHash: 'a'.repeat(64), request: {} })
+ .then(
+ () => undefined,
+ (e: unknown) => e
+ )
+ expect(fetchFn).toHaveBeenCalledTimes(1)
+ expect(err).toMatchObject({
+ code: 'payload_too_large',
- message: 'proxy stream failed with 413 (payload_too_large)',
++ message: 'Codex request is too large; use fewer or smaller images, or reduce context',
+ })
+
+ const classified = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never).classifyError(
+ err
+ )
+ expect(classified).toMatchObject({
+ code: LlmErrorCode.ContextLengthExceeded,
+ retryable: false,
+ providerCode: 'payload_too_large',
+ })
+ expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
+ })
+
+ // #731 — the upstream refuses a request over the model's context window with
+ // `context_length_exceeded`. The proxy forwards that code as a 400 before any
+ // frame, or as an SSE error frame after one. Retrying the same conversation
+ // cannot succeed, so it must not read as a transient outage.
+ it.each([
+ {
+ path: '400 JSON body before streaming',
+ response: {
+ ok: false,
+ status: 400,
+ json: async () => ({ error: 'context_length_exceeded' }),
+ },
+ message: 'proxy stream failed with 400 (context_length_exceeded)',
+ },
+ {
+ path: 'SSE error frame after a text frame',
+ response: {
+ ok: true,
+ body: sse([
+ { type: 'text', text: 'partial' },
+ { type: 'error', code: 'context_length_exceeded' },
+ ]),
+ },
+ message: 'proxy stream failed with context_length_exceeded',
+ },
+ ])(
+ 'T-R7-2d classifies the upstream context_length_exceeded from the $path as ContextLengthExceeded',
+ async ({ response, message }) => {
+ const fetchFn = vi.fn().mockResolvedValue(response)
+ const client = new CodexLlmProxyClient({
+ runtimeUrl: resolveCodexProxyRuntimeUrl(
+ 'http://codex-llm-proxy.control-plane.svc.cluster.local:8080'
+ ),
+ readPlatformJwt: () => 'platform-jwt',
+ fetchFn: fetchFn as unknown as typeof fetch,
+ })
+ const err = await client
+ .stream({ executionTicket: 'ticket-123456', requestHash: 'a'.repeat(64), request: {} })
+ .then(
+ () => undefined,
+ (e: unknown) => e
+ )
+ expect(fetchFn).toHaveBeenCalledTimes(1)
+ expect(err).toBeInstanceOf(CodexProxyError)
+ expect(err).toMatchObject({ code: 'context_length_exceeded', message })
+
+ const classified = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never).classifyError(
+ err
+ )
+ expect(classified).toMatchObject({
+ code: LlmErrorCode.ContextLengthExceeded,
+ retryable: false,
+ providerCode: 'context_length_exceeded',
+ })
+ expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
+ }
+ )
+
it('refuses a runtime URL that is not absolute', () => {
expect(
() =>
diff --cc mcp-host/src/llm/__tests__/codexSubscription.test.ts
index f80c6acd3,d794221cb..356178e1c
--- a/mcp-host/src/llm/__tests__/codexSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
@@@ -1,6 -1,9 +1,11 @@@
import { describe, expect, it, vi } from 'vitest'
+import { LIMITS } from '@clerum/llm-provider-attempt-contract'
+ import {
+ VISUAL_LIMITS,
+ hashCodexCompletionRequest,
+ parseCodexCompletionRequest,
+ } from '@clerum/llm-provider-attempt-contract'
+import { minifiedMcpResult } from '../../__tests__/fixtures/minifiedMcpResult'
import {
buildToolDescribeResponse,
buildToolSearchResponse,
@@@ -159,261 -164,6 +166,262 @@@ describe('CodexSubscriptionProvider', (
expect(wired.authorize).toHaveBeenCalledTimes(1)
expect(wired.stream).toHaveBeenCalledTimes(1)
})
+
+ it('T-C reports an over-sized request as request_limit_exceeded before authorize (#731)', async () => {
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+ // A single tool result over the byte cap. The message count is 4, far below
+ // `maxMessages`, so the refusal can only come from the canonical-hash path
+ // at `codexSubscription.ts:339-352` - the one that measures real bytes.
+ const oversized = [
+ { role: 'system' as const, content: 'you are a helpful assistant' },
+ { role: 'user' as const, content: 'list every contact' },
+ {
+ role: 'assistant' as const,
+ content: '',
+ tool_calls: [{ id: 'call_1', name: 'crm_search_contacts', arguments: { q: '*' } }],
+ },
+ {
+ role: 'tool' as const,
+ // Sized from the contract, so the payload stays over the cap whatever
+ // its value; the escaped quotes of minified JSON push it past.
+ content: minifiedMcpResult(3, LIMITS.maxRequestBodyBytes),
+ tool_call_id: 'call_1',
+ name: 'crm_search_contacts',
+ },
+ ]
+
+ const rejected = provider.completeSingleTurn(oversized)
+ await expect(rejected).rejects.toBeInstanceOf(CodexAuthorizeError)
+ await expect(rejected).rejects.toMatchObject({
+ code: 'request_limit_exceeded',
+ // The contract's own wording. Asserting it is the positive witness that
+ // the refusal came from the byte bound and not from some earlier guard,
+ // which is what keeps the `not.toHaveBeenCalled` below from being vacuous.
- message: 'request exceeds maxRequestBodyBytes',
++ message: 'codex completion request rejected: request exceeds maxRequestBodyBytes',
+ })
+ expect(wired.authorize).not.toHaveBeenCalled()
+ expect(wired.stream).not.toHaveBeenCalled()
+
+ const err = await rejected.catch((e: unknown) => e)
+ expect(provider.classifyError(err)).toMatchObject({
+ code: LlmErrorCode.ContextLengthExceeded,
+ retryable: false,
+ })
+
+ // Liveness witness: the same provider authorizes and streams a small turn,
+ // so the rejection above is a property of the payload, not of the wiring.
+ await provider.completeSingleTurn([{ role: 'user', content: 'hi' }])
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ expect(wired.stream).toHaveBeenCalledTimes(1)
+ })
+
+ it('T-R3-1c dispatches a 2 MiB conversation instead of refusing it (#731)', async () => {
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+ const large = [
+ { role: 'user' as const, content: 'summarize every contact' },
+ {
+ role: 'assistant' as const,
+ content: '',
+ tool_calls: [{ id: 'call_1', name: 'crm_search_contacts', arguments: { q: '*' } }],
+ },
+ {
+ role: 'tool' as const,
+ content: minifiedMcpResult(3, 2 * 1024 * 1024),
+ tool_call_id: 'call_1',
+ name: 'crm_search_contacts',
+ },
+ ]
+ expect(Buffer.byteLength(JSON.stringify(large), 'utf8')).toBeGreaterThan(2 * 1024 * 1024)
+
+ await provider.completeSingleTurn(large)
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ expect(wired.stream).toHaveBeenCalledTimes(1)
+ })
+
+ it('T-C2 reports a 257-call assistant message as request_limit_exceeded before authorize (#731)', async () => {
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+ // The `messages[i].toolCalls` bound has no guard ahead of it in this file -
+ // unlike the message count, which `execute` refuses itself. It can only be
+ // reached through the canonical hash, which makes it the one size refusal
+ // whose classification depends entirely on the regex list.
+ const calls = Array.from({ length: 257 }, (_, index) => ({
+ id: `call_${index}`,
+ name: 'echo',
+ arguments: {},
+ }))
+ const history = [
+ { role: 'user' as const, content: 'run everything' },
+ { role: 'assistant' as const, content: '', tool_calls: calls },
+ ]
+
+ const rejected = provider.completeSingleTurn(history)
+ await expect(rejected).rejects.toBeInstanceOf(CodexAuthorizeError)
+ await expect(rejected).rejects.toMatchObject({
+ code: 'request_limit_exceeded',
- message: 'messages[1].toolCalls exceed 256',
++ message: 'codex completion request rejected: messages[1].toolCalls exceed 256',
+ })
+ expect(wired.authorize).not.toHaveBeenCalled()
+ expect(wired.stream).not.toHaveBeenCalled()
+
+ const err = await rejected.catch((e: unknown) => e)
+ expect(provider.classifyError(err)).toMatchObject({
+ code: LlmErrorCode.ContextLengthExceeded,
+ retryable: false,
+ })
+
+ // Liveness witness: 256 calls on the same message authorize and stream.
+ await provider.completeSingleTurn([
+ history[0],
+ { ...history[1], tool_calls: calls.slice(0, 256) },
+ ])
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ expect(wired.stream).toHaveBeenCalledTimes(1)
+ })
+
+ it('T-C3 reports the element bound as request_limit_exceeded before authorize (#731)', async () => {
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+ // `checkStructure` runs before `JSON.stringify`, so a structure with more
+ // elements than the byte cap is refused by the element bound and never by
+ // the byte measurement. Its message carries a suffix the byte bound does
+ // not, which is why `CONTEXT_LENGTH_REFUSALS` matches the byte pattern as a
+ // prefix: anchoring it at both ends would drop this refusal back to
+ // `invalid_request` and no other test would notice.
+ const history = [
+ { role: 'user' as const, content: 'summarize the export' },
+ {
+ role: 'assistant' as const,
+ content: '',
+ tool_calls: [
+ {
+ id: 'call_1',
+ name: 'export_rows',
+ arguments: { ids: new Array<number>(LIMITS.maxRequestBodyBytes + 1).fill(0) },
+ },
+ ],
+ },
+ ]
+
+ const rejected = provider.completeSingleTurn(history)
+ await expect(rejected).rejects.toBeInstanceOf(CodexAuthorizeError)
+ await expect(rejected).rejects.toMatchObject({
+ code: 'request_limit_exceeded',
- message: 'request exceeds maxRequestBodyBytes element bound',
++ message:
++ 'codex completion request rejected: request exceeds maxRequestBodyBytes element bound',
+ })
+ expect(wired.authorize).not.toHaveBeenCalled()
+ expect(wired.stream).not.toHaveBeenCalled()
+
+ const err = await rejected.catch((e: unknown) => e)
+ expect(provider.classifyError(err)).toMatchObject({
+ code: LlmErrorCode.ContextLengthExceeded,
+ retryable: false,
+ })
+
+ // Liveness witness: the same call with a one-element array goes through.
+ await provider.completeSingleTurn([
+ history[0],
+ {
+ ...history[1],
+ tool_calls: [{ id: 'call_1', name: 'export_rows', arguments: { ids: [0] } }],
+ },
+ ])
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ expect(wired.stream).toHaveBeenCalledTimes(1)
+ })
+
+ it('T-C4 keeps a non-size limit refusal out of the context-length taxonomy (#731)', async () => {
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+ // The negative half of the partition. Nesting depth also fails with
+ // `code: 'limit'`, and compaction cannot fix it: a shorter conversation
+ // keeps whatever depth the surviving arguments have. Classifying it as a
+ // context-length failure would put the user in a compaction loop that never
+ // converges, so it has to stay `invalid_request`.
+ let nested: unknown = 'leaf'
+ for (let i = 0; i < 80; i++) nested = [nested]
+ const history = [
+ { role: 'user' as const, content: 'walk the tree' },
+ {
+ role: 'assistant' as const,
+ content: '',
+ tool_calls: [{ id: 'call_1', name: 'walk', arguments: { nested } }],
+ },
+ ]
+
+ const rejected = provider.completeSingleTurn(history)
+ await expect(rejected).rejects.toBeInstanceOf(CodexAuthorizeError)
+ await expect(rejected).rejects.toMatchObject({
+ code: 'invalid_request',
- message: 'request exceeds maximum nesting depth 64',
++ message: 'codex completion request rejected: request exceeds maximum nesting depth 64',
+ })
+ expect(wired.authorize).not.toHaveBeenCalled()
+ expect(wired.stream).not.toHaveBeenCalled()
+
+ const err = await rejected.catch((e: unknown) => e)
+ // The positive label, not only "not context-length": a remap of
+ // `invalid_request` to a retryable class would send the same refusal back
+ // to the contract on every retry.
+ expect(provider.classifyError(err)).toMatchObject({
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: false,
+ })
+
+ // Liveness witness: the same shape at a legal depth authorizes and streams,
+ // so the refusal is the depth and not the arguments payload as such.
+ let shallow: unknown = 'leaf'
+ for (let i = 0; i < 8; i++) shallow = [shallow]
+ await provider.completeSingleTurn([
+ history[0],
+ {
+ ...history[1],
+ tool_calls: [{ id: 'call_1', name: 'walk', arguments: { nested: shallow } }],
+ },
+ ])
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ expect(wired.stream).toHaveBeenCalledTimes(1)
+ })
+
+ it('T-C5 keeps an out-of-range maxOutputTokens out of the context-length taxonomy (#731)', async () => {
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+ // T-C4 and this test pin the same half of the partition from opposite
+ // distances, which is why both exist. `request exceeds maximum nesting
+ // depth 64` shares the prefix `request exceeds max` with the byte regex and
+ // diverges one character later, so T-C4 is the near miss: it fails the
+ // moment that regex is loosened at all. This message shares nothing with
+ // any of the three patterns, so it only fails under a broadening wide
+ // enough to swallow an unrelated field - the case T-C4 cannot see.
+ // `maxOutputTokens` reaches the contract from the caller unclamped
+ // (`codexSubscription.ts:267-270` -> `:452`), so this is a refusal a caller
+ // can actually provoke, not a synthetic one.
+ const history = [{ role: 'user' as const, content: 'summarize' }]
+
+ const rejected = provider.completeSingleTurn(history, { max_tokens: 16_385 })
+ await expect(rejected).rejects.toBeInstanceOf(CodexAuthorizeError)
+ await expect(rejected).rejects.toMatchObject({
+ code: 'invalid_request',
- message: 'generation.maxOutputTokens is out of range',
++ message: 'codex completion request rejected: generation.maxOutputTokens is out of range',
+ })
+ expect(wired.authorize).not.toHaveBeenCalled()
+ expect(wired.stream).not.toHaveBeenCalled()
+
+ const err = await rejected.catch((e: unknown) => e)
+ expect(provider.classifyError(err)).toMatchObject({
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: false,
+ })
+
+ // Liveness witness: the bound itself authorizes and streams, so the refusal
+ // is the range check and not the presence of `max_tokens` in the request.
+ await provider.completeSingleTurn(history, { max_tokens: 16_384 })
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ expect(wired.stream).toHaveBeenCalledTimes(1)
+ })
+
it('requires an explicit model plus authorizer and proxy dependencies', () => {
process.env.MCP_HOST_CODEX_SUBSCRIPTION_ENABLED = 'true'
expect(() => makeProvider('codex-subscription', {})).toThrow(/explicit model and runtime/)
diff --cc mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
index 0474716d8,000000000..47a94beae
mode 100644,000000..100644
--- a/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
+++ b/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
@@@ -1,342 -1,0 +1,342 @@@
+/**
+ * #731 — the journey tests.
+ *
+ * These prove the route, not the destination: a long MCP-heavy conversation is
+ * compacted by `PressureContextManager` and then dispatched through
+ * `CodexSubscriptionProvider`, which hashes the canonical request and refuses it
+ * when the attempt contract says it is too large. Every intermediate transition
+ * is asserted — the tier that ran, the shape of the history that came out, and
+ * the request the provider actually built — because a test that only asserts the
+ * final state would pass just as happily if compaction never ran and the request
+ * happened to fit.
+ *
+ * J1 is the success route: the history shrinks and the request is accepted. It
+ * runs twice. Under the deployed configuration, pre-prune alone brings the
+ * history under the threshold and no tier runs. With the kill switch
+ * (`CLERUM_COMPACTION_PRE_PRUNE=false`), the truncate tier does the work.
+ * J2 is the failure route: the history cannot shrink, the anti-thrash backoff
+ * lets the turn proceed uncompacted, and the contract refuses it. The two
+ * differ only in their fixture's shape, and the compaction counters are what
+ * tell the two no-op-looking outcomes apart.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { type Counter, register } from 'prom-client'
+import { LIMITS, hashCanonicalCodexRequest } from '@clerum/llm-provider-attempt-contract'
+import { minifiedMcpResult } from '../../__tests__/fixtures/minifiedMcpResult'
+import { config as appConfig } from '../../config'
+import { makeFakeConversation } from '../../core/conversation/__testing__/makeFakeConversation'
+import { LlmErrorCode } from '../../core/errors'
+import { PressureContextManager, clerumCompactionTotal } from '../../core/extensions/contextManager'
+import { clerumPrePruneSavingsTokensTotal } from '../../core/extensions/prePrune'
+import { SimpleEventEmitter } from '../../core/orchestration/eventEmitter'
+import { validateToolLinkages } from '../../core/orchestration/toolUseLoop'
+import type { AgentEvent, ChatMessage, ToolDefinition } from '../../core/types'
+import { logger } from '../../logger'
+import { CodexSubscriptionProvider } from '../codexSubscription'
+
+const requestHash = 'a'.repeat(64)
+
+/**
+ * The provider's dependencies, with `authorize` and `stream` as spies. Same
+ * shape as the `deps()` helper in `codexSubscription.test.ts`; replicated
+ * here rather than exported from that file so neither test file constrains the
+ * other's fixtures.
+ */
+function deps() {
+ const authorize = vi.fn().mockResolvedValue({
+ providerAttemptId: 'attempt-1',
+ requestHash,
+ executionTicket: 'ticket-123456',
+ expiresAt: '2026-08-20T10:00:00.000Z',
+ })
+ const stream = vi.fn().mockResolvedValue({
+ text: 'hello from proxy',
+ toolCalls: [],
+ outcome: 'success',
+ })
+ return {
+ authorizer: { authorize },
+ proxy: { stream },
+ attemptContext: vi.fn(() => ({
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ hostRef: 'chatllm',
+ })),
+ authorize,
+ stream,
+ }
+}
+
+const TOOLS: ToolDefinition[] = [
+ {
+ name: 'crm_search_contacts',
+ description: 'Search contacts that replied to a campaign.',
+ parameters: { type: 'object', properties: { campaignId: { type: 'string' } } },
+ },
+]
+
+/** Snapshot a counter's labeled value (0 when the series does not exist yet). */
+async function counterValue(
+ metric: Counter<string>,
+ labels: Record<string, string>
+): Promise<number> {
+ const data = await metric.get()
+ for (const v of data.values) {
+ if (Object.entries(labels).every(([k, val]) => v.labels[k] === val)) return v.value
+ }
+ return 0
+}
+
+/**
+ * The unshrinkable shape: a run of small exchanges followed by one MCP result
+ * that is larger than the contract's whole budget.
+ *
+ * `truncate` keeps the last 3 non-system messages, so the cut removes the 34
+ * small ones and keeps the payload that is the actual problem. The tier runs,
+ * it does remove messages, and the ratio still lands above `ineffectiveRatio`
+ * — which is what arms the anti-thrash backoff. A history of many equal-sized
+ * turns (`mcpHeavyHistory`) cannot do this: truncating it is effective, which
+ * is exactly why it is J1's fixture and not J2's.
+ */
+function unshrinkableHistory(finalResultBytes: number): ChatMessage[] {
+ const msgs: ChatMessage[] = [{ role: 'system', content: 'You are a helpful assistant.' }]
+ for (let i = 0; i < 17; i++) {
+ msgs.push({ role: 'user', content: `step ${i}` })
+ msgs.push({ role: 'assistant', content: 'ok' })
+ }
+ msgs.push({ role: 'user', content: 'Export every contact in the workspace.' })
+ msgs.push({
+ role: 'assistant',
+ content: '',
+ tool_calls: [
+ { id: 'call_final', name: 'crm_search_contacts', arguments: { campaignId: '*', limit: 0 } },
+ ],
+ })
+ msgs.push({
+ role: 'tool',
+ content: minifiedMcpResult(99, finalResultBytes),
+ tool_call_id: 'call_final',
+ name: 'crm_search_contacts',
+ })
+ return msgs
+}
+
+/**
+ * `turns` rounds of user → assistant (one tool call, small arguments) → tool
+ * result carrying `bytesPerResult` of minified JSON.
+ */
+/**
+ * J1's history is sized from the contract: enough equal turns to pass the byte
+ * cap by 10%. The result size stays fixed and the turn count grows with the
+ * cap, so the protected tail (the last three turns) stays small and pre-prune
+ * alone still brings pressure under the threshold.
+ */
+const J1_RESULT_BYTES = 35_000
+const J1_TURNS = Math.ceil((LIMITS.maxRequestBodyBytes * 1.1) / J1_RESULT_BYTES)
+/**
+ * J1's window sits between the two estimates of that history: the byte-based
+ * count fills it about 2.3 times, the word-based count #731 replaced about 0.55
+ * times. With a 100K window both overrun it and pre-prune runs either way, so
+ * J1 could not tell a regressed tokenizer from the fixed one.
+ */
+const J1_CONTEXT_WINDOW_TOKENS = 1_000_000
+
+function mcpHeavyHistory(turns: number, bytesPerResult: number): ChatMessage[] {
+ const msgs: ChatMessage[] = [{ role: 'system', content: 'You are a helpful assistant.' }]
+ for (let turn = 1; turn <= turns; turn++) {
+ msgs.push({ role: 'user', content: `Find the contacts that replied in campaign ${turn}.` })
+ msgs.push({
+ role: 'assistant',
+ content: '',
+ tool_calls: [
+ {
+ id: `call_${turn}`,
+ name: 'crm_search_contacts',
+ arguments: { campaignId: `camp_${turn}`, limit: 60 },
+ },
+ ],
+ })
+ msgs.push({
+ role: 'tool',
+ content: minifiedMcpResult(turn, bytesPerResult),
+ tool_call_id: `call_${turn}`,
+ name: 'crm_search_contacts',
+ })
+ }
+ return msgs
+}
+
+describe('#731 context-overrun journey', () => {
+ beforeEach(() => {
+ register.resetMetrics()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ it('J1 deployed config: pre-prune alone shrinks an MCP-heavy history and the contract accepts the request (#731)', async () => {
+ const msgs = mcpHeavyHistory(J1_TURNS, J1_RESULT_BYTES)
+ const inputBytes = Buffer.byteLength(JSON.stringify(msgs), 'utf8')
+ expect(inputBytes).toBeGreaterThan(LIMITS.maxRequestBodyBytes)
+
+ // Built the way `taskExecutor` builds it: pre-prune on or off, and its
+ // options, come from the deployed configuration.
+ const manager = new PressureContextManager(
+ J1_CONTEXT_WINDOW_TOKENS,
+ undefined,
+ undefined,
+ undefined,
+ {
+ prePruneEnabled: appConfig.compactionPrePruneEnabled,
+ prePruneOptions: {
+ protectedTailTurns: appConfig.compactionPrePruneProtectedTailTurns,
+ summaryThresholdTokens: appConfig.compactionPrePruneSummaryTokens,
+ maxArgsBytes: appConfig.compactionPrePruneMaxArgsBytes,
+ dedupEnabled: appConfig.compactionPrePruneDedup,
+ oneLineSummariesEnabled: appConfig.compactionPrePruneOneLine,
+ jsonSafeTruncateEnabled: appConfig.compactionPrePruneJsonTruncate,
+ stripMediaEnabled: appConfig.compactionPrePruneStripMedia,
+ },
+ }
+ )
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+
+ const managed = await manager.manage(msgs, makeFakeConversation())
+
+ // Route: pre-prune ran and saved tokens (the witness), and no tier ran.
+ expect(await counterValue(clerumPrePruneSavingsTokensTotal, {})).toBeGreaterThan(0)
+ const tierRuns = (await clerumCompactionTotal.get()).values.reduce((n, v) => n + v.value, 0)
+ expect(tierRuns).toBe(0)
+
+ // State: at least halved in bytes, linkages intact.
+ expect(Buffer.byteLength(JSON.stringify(managed), 'utf8')).toBeLessThan(inputBytes / 2)
+ expect(() => validateToolLinkages(managed)).not.toThrow()
+
+ await provider.completeSingleTurnWithTools(managed, TOOLS)
+
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ const req = wired.authorize.mock.calls[0][0].request
+ expect(Buffer.byteLength(JSON.stringify(req), 'utf8')).toBeLessThanOrEqual(
+ LIMITS.maxRequestBodyBytes
+ )
+ expect(hashCanonicalCodexRequest(req).ok).toBe(true)
+ })
+
+ it('J1 kill switch (CLERUM_COMPACTION_PRE_PRUNE=false): the truncate tier compacts and the contract accepts the request (#731)', async () => {
+ const msgs = mcpHeavyHistory(J1_TURNS, J1_RESULT_BYTES)
+ // Precondition, asserted rather than assumed: the uncompacted history is
+ // already past the contract's byte ceiling, so a request built from it
+ // cannot be accepted. Without this the rest of the test could pass on a
+ // history that never needed compacting.
+ expect(Buffer.byteLength(JSON.stringify(msgs), 'utf8')).toBeGreaterThan(
+ LIMITS.maxRequestBodyBytes
+ )
+
+ const manager = new PressureContextManager(100000, undefined, undefined, undefined, {
+ prePruneEnabled: false,
+ })
+ const conversation = makeFakeConversation()
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+
+ const managed = await manager.manage(msgs, conversation)
+
+ // Route: the emergency tier ran, and the backoff did not — those are the two
+ // paths that can return a shorter or an unchanged array respectively, and
+ // only one of them is this journey.
+ expect(await counterValue(clerumCompactionTotal, { tier: 'truncate', outcome: 'ok' })).toBe(1)
+ expect(
+ await counterValue(clerumCompactionTotal, { tier: 'truncate', outcome: 'thrashing' })
+ ).toBe(0)
+
+ // State: shorter history, linkages intact.
+ expect(managed.length).toBeLessThan(msgs.length)
+ expect(() => validateToolLinkages(managed)).not.toThrow()
+
+ await provider.completeSingleTurnWithTools(managed, TOOLS)
+
+ // Business signal: the provider got far enough to authorize, and what it
+ // built is a request the contract accepts and would hash.
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ const req = wired.authorize.mock.calls[0][0].request
+ expect(Buffer.byteLength(JSON.stringify(req), 'utf8')).toBeLessThanOrEqual(
+ LIMITS.maxRequestBodyBytes
+ )
+ expect(hashCanonicalCodexRequest(req).ok).toBe(true)
+ })
+
+ it('J2 a single long agentic turn reaches backoff and is refused as ContextLengthExceeded (#731)', async () => {
+ const warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => {})
+ const events = new SimpleEventEmitter()
+ const captured: AgentEvent[] = []
+ events.on('compaction:thrashing', e => captured.push(e))
+ // The backoff state lives on the conversation object; built here and never
+ // shared, so this journey cannot inherit a run from another test.
+ const conversation = makeFakeConversation()
+ const manager = new PressureContextManager(100000, undefined, undefined, undefined, {
+ ineffectiveRatio: 0.9,
+ ineffectiveMaxRun: 2,
+ events,
+ taskId: 'task-J2',
+ })
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+
+ // The final result alone passes the byte cap by 10%, whatever its value.
+ const first = await manager.manage(
+ unshrinkableHistory(Math.ceil(LIMITS.maxRequestBodyBytes * 1.1)),
+ conversation
+ )
+ const second = await manager.manage(first, conversation)
+ const third = await manager.manage(second, conversation)
+
+ // Route: the tier ran twice and was ineffective both times, then the third
+ // call took the backoff. The two counters separate the paths — `ok` means
+ // a tier produced a result, `thrashing` means it declined to.
+ expect(await counterValue(clerumCompactionTotal, { tier: 'truncate', outcome: 'ok' })).toBe(2)
+ expect(
+ await counterValue(clerumCompactionTotal, { tier: 'truncate', outcome: 'thrashing' })
+ ).toBe(1)
+ expect(captured).toHaveLength(1)
+ expect(captured[0].data).toMatchObject({ taskId: 'task-J2', consecutiveCount: 2 })
+ // The operator-facing half of the same transition: the event goes to the
+ // bus, this goes to the pod log. The thrashing counter above is the
+ // liveness witness that makes "exactly once" mean something here (#731).
+ expect(warnSpy).toHaveBeenCalledTimes(1)
+ expect(warnSpy).toHaveBeenCalledWith(
+ expect.objectContaining({ taskId: 'task-J2' }),
+ 'Compaction backoff: history cannot be shrunk; proceeding uncompacted'
+ )
+
+ // State: the backoff returns its input untouched. That unchanged array is
+ // the one legitimate no-op in this system, which is why J1 pins
+ // `thrashing` to 0 and this test pins it to 1 — the same shape, told apart
+ // by the counter rather than by inspection.
+ expect(third).toBe(second)
+ expect(() => validateToolLinkages(third)).not.toThrow()
+ // Precondition for the refusal below, asserted rather than assumed.
+ expect(Buffer.byteLength(JSON.stringify(third), 'utf8')).toBeGreaterThan(
+ LIMITS.maxRequestBodyBytes
+ )
+
+ // Business signal: the turn proceeds and the contract refuses it by name.
+ const rejected = provider.completeSingleTurnWithTools(third, TOOLS)
+ await expect(rejected).rejects.toMatchObject({
+ code: 'request_limit_exceeded',
- message: 'request exceeds maxRequestBodyBytes',
++ message: 'codex completion request rejected: request exceeds maxRequestBodyBytes',
+ })
+ expect(wired.authorize).not.toHaveBeenCalled()
+
+ const err = await rejected.catch((e: unknown) => e)
+ // What the user is shown depends on this: `ContextLengthExceeded` reads as
+ // "Conversation Too Long", while the `invalid_request` returned before #731
+ // reached the UI as "Connection Error", a label that reads as transient and
+ // invites a retry that reproduces the same failure.
+ expect(provider.classifyError(err)).toMatchObject({
+ code: LlmErrorCode.ContextLengthExceeded,
+ retryable: false,
+ })
+ })
+})
diff --cc mcp-host/src/llm/__tests__/providerAttemptAuthorizer.test.ts
index 194305de8,36f35c5f8..c2bec6968
--- a/mcp-host/src/llm/__tests__/providerAttemptAuthorizer.test.ts
+++ b/mcp-host/src/llm/__tests__/providerAttemptAuthorizer.test.ts
@@@ -1,8 -1,4 +1,9 @@@
import { describe, expect, it, vi } from 'vitest'
++import { LIMITS } from '@clerum/llm-provider-attempt-contract'
+import { LlmErrorCode } from '../../core/errors'
+import { CodexSubscriptionProvider } from '../codexSubscription'
+import { classifyFailoverClass } from '../failover/classify'
+import { GrokSubscriptionProvider } from '../grokSubscription'
import {
CodexAuthorizeError,
ProviderAttemptAuthorizer,
@@@ -17,6 -13,72 +18,72 @@@ const validAuthorize =
}
describe('ProviderAttemptAuthorizer', () => {
+ it('rejects the complete oversized envelope before dispatch', async () => {
+ const fetchFn = vi.fn()
+ const authorizer = new ProviderAttemptAuthorizer({
+ authorizeUrl: 'http://gateway/authorize',
+ readPlatformJwt: () => 'test-jwt',
+ fetchFn,
+ })
+ await expect(
+ authorizer.authorize({
- request: { content: 'a'.repeat(1048576) },
++ request: { content: 'a'.repeat(LIMITS.maxRequestBodyBytes) },
+ invocationId: 'inv-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ })
+ ).rejects.toMatchObject({ code: 'payload_too_large' })
+ expect(fetchFn).not.toHaveBeenCalled()
+ })
+
- it('dispatches a V2 envelope larger than the 1 MiB V1 ceiling', async () => {
++ it('dispatches a V2 envelope larger than the V1 ceiling', async () => {
+ const fetchFn = vi.fn().mockResolvedValue({
+ ok: true,
+ json: async () => validAuthorize,
+ })
+ const authorizer = new ProviderAttemptAuthorizer({
+ authorizeUrl: 'http://gateway/authorize',
+ readPlatformJwt: () => 'test-jwt',
+ fetchFn: fetchFn as unknown as typeof fetch,
+ })
+ await expect(
+ authorizer.authorize({
+ request: {
+ schemaVersion: 'codex-completion-request.v2',
- pad: 'a'.repeat(2 * 1024 * 1024),
++ pad: 'a'.repeat(LIMITS.maxRequestBodyBytes + 1024 * 1024),
+ },
+ invocationId: 'inv-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ })
+ ).resolves.toMatchObject({ executionTicket: 'ticket-123456' })
+ expect(fetchFn).toHaveBeenCalledOnce()
+ })
+
+ it('recognizes a non-JSON 413 as a request limit', async () => {
+ const fetchFn = vi.fn(async () => new Response('<h1>Too large</h1>', { status: 413 }))
+ const authorizer = new ProviderAttemptAuthorizer({
+ authorizeUrl: 'http://gateway/authorize',
+ readPlatformJwt: () => 'test-jwt',
+ fetchFn,
+ })
+ await expect(
+ authorizer.authorize({
+ request: {},
+ invocationId: 'inv-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ })
+ ).rejects.toMatchObject({ code: 'payload_too_large' })
+ expect(fetchFn).toHaveBeenCalledOnce()
+ })
+
it('posts the platform JWT to the server-owned gateway URL', async () => {
const fetchFn = vi.fn().mockResolvedValue({
ok: true,
@@@ -99,89 -161,6 +166,90 @@@
).rejects.toMatchObject({ code: 'insufficient_scope' })
})
+ // #731 — nginx on the authorize route answers an oversized body itself, with
+ // an HTML 413 that never reaches control-api. Recorded live on the branch
+ // profile before the gateway picked up `client_max_body_size`: every request
+ // over 1 MiB came back labelled provider_unavailable, a retryable outage.
+ function nginx(status: number, reason: string): Response {
+ return new Response(
+ `<html><head><title>${status} ${reason}</title></head><body><center><h1>${status} ${reason}</h1></center><hr><center>nginx</center></body></html>`,
+ { status, headers: { 'content-type': 'text/html' } }
+ )
+ }
+
+ async function authorizeFailure(response: Response) {
+ const fetchFn = vi.fn().mockResolvedValue(response)
+ const authorizer = new ProviderAttemptAuthorizer({
+ authorizeUrl: resolveCodexAuthorizeUrl('http://gateway:8092'),
+ readPlatformJwt: () => 'platform-jwt',
+ fetchFn: fetchFn as unknown as typeof fetch,
+ })
+ const err = await authorizer
+ .authorize({
+ request: {},
+ invocationId: 'inv-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ })
+ .then(
+ () => undefined,
+ (e: unknown) => e
+ )
+ return { err, fetchFn }
+ }
+
- it('T-R7-1a reads an HTML 413 from the gateway as request_limit_exceeded', async () => {
++ it('T-R7-1a reads an HTML 413 from the gateway as payload_too_large', async () => {
+ const { err, fetchFn } = await authorizeFailure(nginx(413, 'Request Entity Too Large'))
+ // Liveness witness: the authorize hop really ran and got the 413.
+ expect(fetchFn).toHaveBeenCalledTimes(1)
+ expect(err).toBeInstanceOf(CodexAuthorizeError)
+ expect(err).toMatchObject({
- code: 'request_limit_exceeded',
- message: 'authorize failed with 413',
++ code: 'payload_too_large',
++ message: 'Codex request is too large; use fewer or smaller images, or reduce context',
+ })
+ })
+
+ it('T-R7-1b keeps an HTML 502 from the gateway as provider_unavailable', async () => {
+ const { err, fetchFn } = await authorizeFailure(nginx(502, 'Bad Gateway'))
+ expect(fetchFn).toHaveBeenCalledTimes(1)
+ expect(err).toMatchObject({
+ code: 'provider_unavailable',
+ message: 'authorize failed with 502',
+ })
+ })
+
- it('T-R7-1c keeps a JSON error code on a 413 ahead of the status', async () => {
- const { err } = await authorizeFailure(
- new Response(JSON.stringify({ error: 'payload_too_large' }), {
++ it('T-R7-1c reads a 413 as payload_too_large whatever JSON code it carries', async () => {
++ const { err, fetchFn } = await authorizeFailure(
++ new Response(JSON.stringify({ error: 'invalid_request' }), {
+ status: 413,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
++ expect(fetchFn).toHaveBeenCalledTimes(1)
+ expect(err).toMatchObject({ code: 'payload_too_large' })
+ })
+
+ it.each([
+ ['codex-subscription', () => new CodexSubscriptionProvider('gpt-5.3-codex', {} as never)],
+ ['grok-subscription', () => new GrokSubscriptionProvider('grok-4.6', {} as never)],
+ ])(
+ 'T-R7-1d %s classifies a gateway 413 as a non-retryable ContextLengthExceeded',
+ async (_provider, build) => {
+ const { err, fetchFn } = await authorizeFailure(nginx(413, 'Request Entity Too Large'))
+ expect(fetchFn).toHaveBeenCalledTimes(1)
+ const classified = build().classifyError(err)
+ expect(classified).toMatchObject({
+ code: LlmErrorCode.ContextLengthExceeded,
+ retryable: false,
- providerCode: 'request_limit_exceeded',
++ providerCode: 'payload_too_large',
+ providerDispatched: false,
+ })
+ expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
+ }
+ )
+
it('refreshes the platform JWT once and retries authorize after HTTP 401', async () => {
let jwt = 'stale-jwt'
const refreshOnUnauthorized = vi.fn(async () => {
diff --cc mcp-host/src/llm/__tests__/registry.test.ts
index 30a7e6665,0dc2b79d1..221265b54
--- a/mcp-host/src/llm/__tests__/registry.test.ts
+++ b/mcp-host/src/llm/__tests__/registry.test.ts
@@@ -6,18 -6,10 +6,19 @@@
* guard in `isLlmProvider` (§1), and the factory fail-safe (§5.7).
*/
import { describe, expect, it, vi } from 'vitest'
+import { LIMITS as GROK_LIMITS } from '@clerum/grok-provider-attempt-contract'
+import { LIMITS as CODEX_LIMITS } from '@clerum/llm-provider-attempt-contract'
+ import { logger } from '../../logger'
import { apiKeysFromEnv, createLLMProvider } from '../index'
import { makeProvider } from '../registry'
-import { ALL_PROVIDERS, descriptorFor, isLlmProvider, primarySlot } from '../registryCore'
+import {
+ ALL_PROVIDERS,
+ SUBSCRIPTION_DEFAULT_CONTEXT_WINDOW_TOKENS,
+ descriptorFor,
+ isLlmProvider,
+ primarySlot,
+ resolveContextWindow,
+} from '../registryCore'
describe('provider registry — auto-detection order (§5.9)', () => {
it('preserves the dev priority prefix openai > claude > zai > bailian > vertex > bedrock', () => {
diff --cc mcp-host/src/llm/codexSubscription.ts
index 513a5fff9,59c604efe..daaf7ff0f
--- a/mcp-host/src/llm/codexSubscription.ts
+++ b/mcp-host/src/llm/codexSubscription.ts
@@@ -33,48 -36,6 +36,55 @@@ export type CodexAttemptContext =
userId?: string
}
+/**
+ * The contract `limit` refusals that mean "this turn carries too much".
+ *
- * `fail('limit', …)` guards eight checks, and only these are about volume: the
- * real byte bound (`index.cjs:391`), the element bound that proxies it
- * (`:193`), `maxMessages` (`:239`) and `messages[i].toolCalls` (`:266`).
++ * Of the `fail('limit', …)` checks on a request, only these are about
++ * conversation volume: the real byte bound (`index.cjs:570`) and its
++ * non-image share on a V2 request (`:579`), the element bound that proxies it
++ * (`:332`), `maxMessages` (`:389`) and `messages[i].toolCalls` (`:418`).
+ * All four are "this conversation is too long", which is exactly what
+ * `ContextLengthExceeded` — "Conversation Too Long" — promises the user.
+ * Compaction reaches them unevenly. The context manager counts bytes and,
+ * through the registry's `maxMessages`, the message count, so it compacts
+ * before either bound; a single turn holding more than `maxMessages`
+ * messages stays unshrinkable, because the cut never lands inside a turn.
+ * `maxToolCalls` also bounds every response, so only history produced by
+ * another provider can carry an over-long `toolCalls` array.
+ *
- * The other four are not. Nesting depth (`:180`, `:215`),
++ * The others are not. Nesting depth (`:313`, `:354`),
+ * `generation.maxOutputTokens` and `deadlineMs` 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 `subscriptionRequestHash.test.ts:155-168` pins for the over-deep schema.
++ * The image budgets (count, bytes, dimensions) belong to the attachments, not
++ * the conversation: a `size` one is `payload_too_large`, a `count` one
++ * `invalid_request`.
+ *
- * `hashCanonicalCodexRequest` returns `{ ok, code, message }` and nothing else,
- * so the message is the only discriminator available at this boundary (#731).
- * The byte pattern is a prefix so it keeps matching once the element bound gets
- * its own distinct wording.
++ * `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 both the element bound and the
++ * `outside image data` check of a V2 request.
+ *
+ * `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/,
+ /^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))
+}
+
function mapCodexUsage(usage?: { inputTokens: number; outputTokens: number }): {
usage: { input_tokens: number; output_tokens: number; total_tokens: number }
usage_reported: boolean
@@@ -356,20 -358,13 +427,25 @@@ export class CodexSubscriptionProvider
// requestHash mismatch. An invalid request never leaves the process.
const canonical = hashCanonicalCodexRequest(this.buildRequest(messages, tools, options))
if (!canonical.ok) {
- // A size refusal (bytes, element bound, message count, tool-call count)
- // is a context-length failure, not a malformed request; it is thrown
- // before authorize and dispatch so no provider attempt is spent.
- // Reported as `invalid_request` it reached the UI as "Connection Error",
- // a label that reads as transient, and invited a retry that reproduced it
- // (#731). The message-count guard above already used this classification.
++ // A conversation-volume refusal (bytes, element bound, message count,
++ // tool-call count) is a context-length failure, not a malformed request;
++ // it is thrown before authorize and dispatch so no provider attempt is
++ // spent. Reported as `invalid_request` it reached the UI as "Connection
++ // Error", a label that reads as transient, and invited a retry that
++ // reproduced it (#731). The message-count guard above already used this
++ // classification. Any other `size` refusal is an image budget and stays
++ // `payload_too_large`; both reach the user as a context-length failure.
throw new CodexAuthorizeError(
- canonical.kind === 'size' ? 'payload_too_large' : CODEX_REQUEST_INVALID,
+ isContextLengthRefusal(canonical.code, canonical.message)
+ ? 'request_limit_exceeded'
- : 'invalid_request',
- canonical.message
++ : canonical.kind === 'size'
++ ? 'payload_too_large'
++ : CODEX_REQUEST_INVALID,
+ `codex completion request rejected: ${canonical.message}`
)
}
- const { request, requestHash } = canonical.value
+ const wireRequest = canonical.value.request
+ const requestHash = canonical.value.requestHash
const context = this.deps.attemptContext({ model: this.model })
if (
!Number.isInteger(context.policyRevision) ||
diff --cc mcp-host/src/llm/providerAttemptAuthorizer.ts
index ef5d876d4,49a36d1d8..e1feb9cbc
--- a/mcp-host/src/llm/providerAttemptAuthorizer.ts
+++ b/mcp-host/src/llm/providerAttemptAuthorizer.ts
@@@ -96,16 -107,18 +107,21 @@@ export class ProviderAttemptAuthorizer
await this.options.refreshOnUnauthorized()
return this.authorizeOnce(body, false, signal)
}
- // A 413 without a JSON code comes from the gateway in front of control-api
- // (nginx `client_max_body_size`), not from control-api: it is a size
- // refusal of this request, never a provider outage (#731).
++ // Every 413 is a size refusal of this request, never a provider outage
++ // (#731): control-api answers `payload_too_large`, and the gateway in
++ // front of it (nginx `client_max_body_size`) answers with no JSON code.
const code =
- typeof payload.error === 'string'
- ? payload.error
- : response.status === 413
- ? 'request_limit_exceeded'
+ response.status === 413
+ ? 'payload_too_large'
+ : typeof payload.error === 'string'
+ ? payload.error
: 'provider_unavailable'
- throw new CodexAuthorizeError(code, `authorize failed with ${response.status}`)
+ throw new CodexAuthorizeError(
+ code,
+ code === 'payload_too_large'
+ ? 'Codex request is too large; use fewer or smaller images, or reduce context'
+ : `authorize failed with ${response.status}`
+ )
}
for (const key of LEAK_KEYS) {
if (key in payload) {
diff --cc mcp-host/src/llm/registryCore.ts
index 5a169014e,3c178e772..592ddeafa
--- a/mcp-host/src/llm/registryCore.ts
+++ b/mcp-host/src/llm/registryCore.ts
@@@ -223,18 -202,9 +226,19 @@@ const RUNTIME_FIELDS: Record<LlmProvide
// data-driven baseURL arm. Tokenizer 'openai' (it serves OpenAI models) and
// defaultModel is the Azure DEPLOYMENT name the operator expects by default.
azure: { defaultModel: 'gpt-4.1', tokenizer: 'openai' },
- // Broker: explicit model required later; no Secret slot and no default.
- 'codex-subscription': { tokenizer: 'fallback', requiresImageSourceIdentity: true },
- 'grok-subscription': { tokenizer: 'fallback' },
+ // Broker: explicit model required later; no Secret slot and no default. The
+ // message bound is read from each contract, never written as a literal.
+ 'codex-subscription': {
+ tokenizer: 'fallback',
++ requiresImageSourceIdentity: true,
+ maxMessages: CODEX_CONTRACT_LIMITS.maxMessages,
+ defaultContextWindowTokens: SUBSCRIPTION_DEFAULT_CONTEXT_WINDOW_TOKENS,
+ },
+ 'grok-subscription': {
+ tokenizer: 'fallback',
+ maxMessages: GROK_CONTRACT_LIMITS.maxMessages,
+ defaultContextWindowTokens: SUBSCRIPTION_DEFAULT_CONTEXT_WINDOW_TOKENS,
+ },
}
// Order = dev auto-detection priority (first present key wins), inherited from
diff --cc packages/llm-provider-attempt-contract/index.cjs
index b6c88fa3c,97faf4814..193796831
--- a/packages/llm-provider-attempt-contract/index.cjs
+++ b/packages/llm-provider-attempt-contract/index.cjs
@@@ -13,12 -16,21 +16,26 @@@ const PROVIDER_ID = 'codex-subscription
const TICKET_TYP = 'codex-execution-ticket'
const LIMITS = Object.freeze({
- // V1 ceiling, and the V2 ceiling for everything that is not image data. The
- // measurement that enforces the second half lives in
- // `measureNonImageRequestBytes` below.
- maxRequestBodyBytes: 1048576,
+ // 8 MiB of serialized request (#731). A 1M-token window is about 4 MB of
+ // text, and escaped JSON tool results cost 1.3-1.5x that, so this covers the
+ // largest listed model window; past it the model refuses on tokens first.
- // It is a non-image cap: image bytes get their own ceiling (#660), and the
++ // It is the V1 ceiling, and the V2 ceiling for everything that is not image
++ // data; `measureNonImageRequestBytes` below enforces the second half. The
+ // element bound in checkStructure follows this value 1:1.
+ maxRequestBodyBytes: 8388608,
+ /**
- * V2 request/envelope ceiling. It is deliberately larger than
- * `maxRequestBodyBytes` because a V2 body carries base64 image payloads, and
- * it is deliberately larger than one hard-ceiling image (16 MiB decoded ≈
- * 21.3 MiB encoded) plus the 1 MiB non-image share. Typical 5 / 9 requests
- * fit in 14 MiB (`VISUAL_LIMITS.typicalEnvelopeBytes`); this 24 MiB number is
- * the HTTP/nginx hard envelope, not the usual product target. It is not a
- * text/tool allowance: `measureNonImageRequestBytes` keeps that share on the
- * V1 ceiling.
++ * V2 request/envelope ceiling. It is larger than `maxRequestBodyBytes`
++ * because a V2 body carries base64 image payloads. It holds one hard-ceiling
++ * image (16 MiB decoded ≈ 21.3 MiB encoded) plus about 2.7 MiB of non-image
++ * data, so a V2 request carrying both a hard-ceiling image and more non-image
++ * data than that is refused here even though each share is under its own
++ * cap. Typical 5 / 9 requests fit in 14 MiB
++ * (`VISUAL_LIMITS.typicalEnvelopeBytes`); this 24 MiB number is the
++ * HTTP/nginx hard envelope, not the usual product target. It is not a
++ * text/tool allowance: `measureNonImageRequestBytes` keeps that share on
++ * `maxRequestBodyBytes`.
+ */
+ maxVisualRequestBodyBytes: 25165824,
maxMessages: 1024,
// Bound calls in each assistant message independently of advertised definitions.
// A turn of N calls adds N+1 messages, so N stays <= maxMessages/4. At this
@@@ -150,6 -183,96 +188,96 @@@ function unknownKeys(obj, allowed)
return Object.keys(obj).filter(k => !allowed.has(k))
}
+ /**
+ * Request/envelope byte ceiling for a schema version. V2 raises the ceiling so
+ * a body can carry image payloads; every other value keeps the V1 ceiling, so a
+ * missing, unknown or lower version can never buy the larger budget.
+ */
+ function schemaRequestBodyLimit(schemaVersion) {
+ return schemaVersion === SCHEMA_VERSION_V2
+ ? LIMITS.maxVisualRequestBodyBytes
+ : LIMITS.maxRequestBodyBytes
+ }
+
+ /**
+ * Ceiling for a request body, or for the envelope that carries it, BEFORE
+ * parsing. Callers that must size an HTTP body — the client, the authorizer and
+ * the proxy — only have the declared document at that point, so this keys off
+ * the declaration and falls back to the V1 ceiling for anything else.
+ */
+ function requestBodyLimitBytes(request) {
+ return schemaRequestBodyLimit(isPlainObject(request) ? request.schemaVersion : undefined)
+ }
+
+ /**
+ * UTF-8 length of a request with every image payload replaced by an empty
+ * string: the caller-controlled text/tool share of the body.
+ *
+ * V2's larger ceiling exists for image data only, so this share stays on the V1
+ * budget and declaring V2 never buys 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 blankImagePayloadsInMessages(messages) {
+ if (!Array.isArray(messages)) return messages
+ return messages.map(message => {
+ const parts = isPlainObject(message) ? message.contentParts : undefined
+ if (!Array.isArray(parts)) return message
+ return {
+ ...message,
+ contentParts: parts.map(part =>
+ isPlainObject(part) && part.type === 'image' ? { ...part, data: '' } : part
+ ),
+ }
+ })
+ }
+
+ function measureNonImageRequestBytes(input) {
+ return Buffer.byteLength(
+ JSON.stringify({ ...input, messages: blankImagePayloadsInMessages(input.messages) }),
+ 'utf8'
+ )
+ }
+
+ /**
+ * Authorize JSON is a different document from a Codex request or proxy
+ * envelope. `requestBodyLimitBytes(body.request)` still gates the whole
+ * wrapper (24 MiB only when the nested request declares V2). This helper
+ * blanks image payloads inside `body.request` so wrapper fields — ids,
- * hashes, ticket links — stay on the 1 MiB non-image budget.
++ * hashes, ticket links — stay on the `maxRequestBodyBytes` non-image budget.
+ */
+ function measureNonImageAuthorizeBytes(body) {
+ if (!isPlainObject(body)) {
+ return Buffer.byteLength(JSON.stringify(body ?? null), 'utf8')
+ }
+ const request = body.request
+ if (!isPlainObject(request)) {
+ return Buffer.byteLength(JSON.stringify(body), 'utf8')
+ }
+ return Buffer.byteLength(
+ JSON.stringify({
+ ...body,
+ request: { ...request, messages: blankImagePayloadsInMessages(request.messages) },
+ }),
+ 'utf8'
+ )
+ }
+
+ /**
+ * Proxy completion JSON includes `executionTicket`, which authorize never
+ * measured. Blank images and drop the ticket so a body that sat under the
- * 1 MiB authorize budget is not 413'd on redeem by ~1 KB of JWT.
++ * `maxRequestBodyBytes` authorize budget is not 413'd on redeem by ~1 KB of JWT.
+ */
+ function measureNonImageCompletionBytes(body) {
+ if (!isPlainObject(body)) {
+ return measureNonImageAuthorizeBytes(body)
+ }
+ const { executionTicket: _executionTicket, ...rest } = body
+ return measureNonImageAuthorizeBytes(rest)
+ }
+
function isBoundedId(value) {
return typeof value === 'string' && ID_PATTERN.test(value)
}
@@@ -187,17 -314,7 +319,17 @@@ function checkStructure(value, maxDepth
const children = Array.isArray(node) ? node : Object.values(node).filter(child => child !== undefined)
elements += children.length
if (elements > LIMITS.maxRequestBodyBytes) {
- return fail('limit', 'request exceeds maxRequestBodyBytes', 'size')
+ // Named distinctly from the byte measurement below, which refuses with
+ // the bare `request exceeds maxRequestBodyBytes`. Both are `limit`
- // failures and `fail()` carries no field beyond code and message, so the
- // wording is the only thing that tells a user report which guard fired.
++ // failures of kind `size`, so the wording is the only thing that tells a
++ // user report which guard fired.
+ // The remedy is the same for both - compaction - and the bound is reused
+ // rather than given a constant of its own: every element serializes to
+ // at least one byte, so a request of plain JSON data with more elements
+ // than the byte cap cannot fit under it either (#731). A value that
+ // JSON.stringify drops (a function, a symbol) is still counted here, so
+ // for such input this bound can only refuse earlier, never later.
- return fail('limit', 'request exceeds maxRequestBodyBytes element bound')
++ return fail('limit', 'request exceeds maxRequestBodyBytes element bound', 'size')
}
for (const child of children) {
if (child !== null && typeof child === 'object') stack.push(child, depth + 1)
@@@ -382,7 -520,21 +535,21 @@@ function parseTransportHints(raw)
return ok({ promptCacheKey: raw.promptCacheKey })
}
- function parseCodexCompletionRequestV1(input) {
+ /**
+ * One root parser for every request version: the same closed root field set,
+ * the same ordered checks and the same projection. Only the schema version
+ * literal and the message field set differ, so a new version cannot become a
+ * looser root by accident.
+ *
+ * Two size gates run first, before any key, id or payload work:
- * 1. the whole body against this version's ceiling (24 MiB for V2, 1 MiB
++ * 1. the whole body against this version's ceiling (24 MiB for V2, 8 MiB
+ * otherwise), then
+ * 2. for V2 only, the body with every image payload blanked against the V1
+ * ceiling — the images, not the text, are what the larger budget buys.
+ * Both are pure measurements, so the projected value and its hash are
+ * unaffected by them.
+ */
+ function parseCodexCompletionRequestRoot(input, schemaVersion, messageKeys) {
if (!isPlainObject(input)) return fail('invalid', 'request must be an object')
// Runs before JSON.stringify: a deeply nested body would otherwise throw a
// RangeError out of the parser instead of failing closed.
@@@ -394,12 -547,17 +562,21 @@@
} catch {
return fail('invalid', 'request is not JSON-serializable')
}
+ // The byte count covers the whole request, tool definitions included. A
+ // tool catalog that alone exceeds the cap is refused with this message and
+ // the Host labels it context length, although compaction shrinks only the
+ // conversation and cannot bring such a request under the cap.
- if (encoded > LIMITS.maxRequestBodyBytes) {
- return fail('limit', 'request exceeds maxRequestBodyBytes')
+ if (encoded > schemaRequestBodyLimit(schemaVersion)) {
+ return fail(
+ 'limit',
+ visualSchema
+ ? 'request exceeds maxVisualRequestBodyBytes'
+ : 'request exceeds maxRequestBodyBytes',
+ 'size'
+ )
+ }
+ if (visualSchema && measureNonImageRequestBytes(input) > LIMITS.maxRequestBodyBytes) {
+ return fail('limit', 'request exceeds maxRequestBodyBytes outside image data', 'size')
}
const extra = rejectUnknown(input, ROOT_KEYS, 'request')
if (extra) return extra
@@@ -454,11 -616,189 +635,190 @@@ function hashCodexCompletionRequestV1(r
return createHash('sha256').update(stableStringify(request)).digest('hex')
}
+ /**
+ * Minimal image provenance for V2. Closed union: an attachment that arrived
+ * with a user message, or one produced by a tool call. It is hashed with the
+ * rest of the part and never becomes model text.
+ *
+ * Identifier shape reuses the existing bounded ID pattern. Evidence from the
+ * current producers: attachment ids are `att_<epoch>_<rand>`
+ * (mcp-host/src/core/tools/desktop/screenshotUtil.ts), channel message ids are
+ * values such as `telegram:tg-chat-1:42` or `1700000001.000001`
+ * (mcp-host/src/workflow/providerWorkflowCallerContextClient.test.ts), and
+ * tool-call ids come from the assistant tool call. All fit
+ * `[A-Za-z0-9._:/-]{1,128}`; no producer needs a different alphabet.
+ */
+ function parseImageSource(raw, label) {
+ if (!isPlainObject(raw)) return fail('invalid', `${label} must be an object`)
+ if (raw.kind !== 'attachment' && raw.kind !== 'tool') {
+ return fail('invalid', `${label}.kind is not allowed`)
+ }
+ const fromAttachment = raw.kind === 'attachment'
+ const extra = rejectUnknown(
+ raw,
+ fromAttachment ? IMAGE_SOURCE_ATTACHMENT_KEYS : IMAGE_SOURCE_TOOL_KEYS,
+ label
+ )
+ if (extra) return extra
+ if (!isBoundedId(raw.attachmentId)) return fail('invalid', `${label}.attachmentId is invalid`)
+ const ownerKey = fromAttachment ? 'messageId' : 'toolCallId'
+ if (!isBoundedId(raw[ownerKey])) return fail('invalid', `${label}.${ownerKey} is invalid`)
+ if (fromAttachment) {
+ return ok({ kind: 'attachment', attachmentId: raw.attachmentId, messageId: raw.messageId })
+ }
+ return ok({ kind: 'tool', attachmentId: raw.attachmentId, toolCallId: raw.toolCallId })
+ }
+
+ /**
+ * Ordered content parts. Order is significant and preserved verbatim; nothing
+ * is merged, reordered or dropped. Text parts must agree with the message
+ * `content` string, so the textual projection and the part projection cannot
+ * contradict each other. Parts are optional and may be text-only (a compacted
+ * message that no longer carries an image is valid); images are bounded by
+ * count, per-image bytes, total bytes, dimension and pixel budgets.
+ */
+ function parseContentParts(raw, label, visualBudget) {
+ if (!Array.isArray(raw) || raw.length === 0) {
+ return fail('invalid', `${label} must be a non-empty array`)
+ }
+ const parts = []
+ const textBits = []
+ for (let i = 0; i < raw.length; i++) {
+ const part = raw[i]
+ const partLabel = `${label}[${i}]`
+ if (!isPlainObject(part)) return fail('invalid', `${partLabel} must be an object`)
+ if (part.type === 'text') {
+ const extra = rejectUnknown(part, CONTENT_PART_TEXT_KEYS, partLabel)
+ if (extra) return extra
+ if (typeof part.text !== 'string') {
+ return fail('invalid', `${partLabel}.text must be a string`)
+ }
+ parts.push({ type: 'text', text: part.text })
+ textBits.push(part.text)
+ continue
+ }
+ if (part.type === 'image') {
+ const extra = rejectUnknown(part, CONTENT_PART_IMAGE_KEYS, partLabel)
+ if (extra) return extra
+ if (part.mimeType !== 'image/jpeg' && part.mimeType !== 'image/png') {
+ return fail('invalid', `${partLabel}.mimeType is not allowed`)
+ }
+ const source = parseImageSource(part.source, `${partLabel}.source`)
+ if (!source.ok) return source
+ const image = inspectVisualImage({ mimeType: part.mimeType, data: part.data })
+ if (!image.ok) return fail(image.code, `${partLabel}: ${image.message}`, image.kind)
+ // Request-scoped budgets: history can carry more messages than one, so a
+ // per-message counter would let a request exceed the declared limits.
+ visualBudget.images += 1
+ if (visualBudget.images > VISUAL_LIMITS.maxImages) {
+ return fail('limit', `request exceeds ${VISUAL_LIMITS.maxImages} images`, 'count')
+ }
+ visualBudget.totalBytes += image.value.bytes
+ if (visualBudget.totalBytes > VISUAL_LIMITS.maxTotalImageBytes) {
+ return fail(
+ 'limit',
+ `request exceeds ${VISUAL_LIMITS.maxTotalImageBytes} total image bytes`,
+ 'size'
+ )
+ }
+ parts.push({
+ type: 'image',
+ mimeType: part.mimeType,
+ data: part.data,
+ source: source.value,
+ })
+ continue
+ }
+ return fail('invalid', `${partLabel}.type is not allowed`)
+ }
+ return ok({ parts, text: textBits.join('\n') })
+ }
+
+ /**
+ * V2 root: the shared root parser with the V2 schema version and the message
+ * field set that additionally allows `contentParts`.
+ */
+ function parseCodexCompletionRequestV2(input) {
+ return parseCodexCompletionRequestRoot(input, SCHEMA_VERSION_V2, MESSAGE_KEYS_V2)
+ }
+
+ /**
+ * Single dispatcher for every supported version. It only selects the version
+ * and defers all validation to that version's parser, so an unknown or missing
+ * schemaVersion fails closed instead of falling through to a loose path.
+ */
+ function parseCodexCompletionRequest(input) {
+ if (!isPlainObject(input)) return fail('invalid', 'request must be an object')
+ if (input.schemaVersion === SCHEMA_VERSION) return parseCodexCompletionRequestV1(input)
+ if (input.schemaVersion === SCHEMA_VERSION_V2) return parseCodexCompletionRequestV2(input)
+ return fail(
+ 'invalid',
+ 'schemaVersion must be codex-completion-request.v1 or codex-completion-request.v2'
+ )
+ }
+
+ function hashCodexCompletionRequest(request) {
+ return createHash('sha256').update(stableStringify(request)).digest('hex')
+ }
+
+ /**
+ * Exact proxy request envelope shared by the authorizer and the proxy.
+ *
+ * The outer `deadlineMs` is never emitted: a V2 request carries its deadline in
+ * `request.deadlineMs`, already bound by the request hash, and a caller must
+ * not be able to add an independent deadline after the envelope was measured.
+ *
+ * The returned envelope is re-parsed and re-hashed here, so it cannot carry a
+ * request the contract rejects or a hash that disagrees with the request it
+ * carries. Its exact UTF-8 byte length (JSON.stringify minus whitespace, the
+ * same serialization the transport sends) must fit the ceiling of the schema it
- * carries — `requestBodyLimitBytes(request)`, i.e. 24 MiB for V2 and 1 MiB
- * otherwise — which is the number the proxy enforces through
- * CODEX_LLM_PROXY_MAX_BODY_BYTES. A deployment that lowers that proxy limit
- * below the contract limit is not covered by this measurement.
++ * carries — `requestBodyLimitBytes(request)`, i.e. 24 MiB for V2 and 8 MiB
++ * otherwise. The Host and the authorizer build it for V2 only, where 24 MiB is
++ * the number the proxy enforces through CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES.
++ * A deployment that lowers that proxy limit below the contract limit is not
++ * covered by this measurement.
+ *
+ * The request inside the envelope already passed the V2 non-image budget, so
+ * the V2 headroom here can only be spent by the ticket and the digest the
+ * authorizer produced; a caller cannot reach this ceiling with text.
+ */
+ function buildCodexProxyEnvelope(input) {
+ if (!isPlainObject(input)) return fail('invalid', 'proxy envelope must be an object')
+ const extra = rejectUnknown(input, ENVELOPE_KEYS, 'proxy envelope')
+ if (extra) return extra
+ const ticket = input.executionTicket
+ if (typeof ticket !== 'string' || ticket.length < 8 || /[\p{Cc}\p{Cs}]/u.test(ticket)) {
+ return fail('invalid', 'executionTicket is invalid')
+ }
+ if (typeof input.requestHash !== 'string' || !SHA256_HEX.test(input.requestHash)) {
+ return fail('invalid', 'requestHash must be a SHA-256 hex digest')
+ }
+ const parsed = parseCodexCompletionRequest(input.request)
+ if (!parsed.ok) return parsed
+ const requestHash = hashCodexCompletionRequest(parsed.value)
+ if (requestHash !== input.requestHash) {
+ return fail('request_hash_mismatch', 'requestHash does not match the request')
+ }
+ const envelope = { executionTicket: ticket, requestHash, request: parsed.value }
+ const visualSchema = parsed.value.schemaVersion === SCHEMA_VERSION_V2
+ const encoded = Buffer.byteLength(JSON.stringify(envelope), 'utf8')
+ if (encoded > requestBodyLimitBytes(parsed.value)) {
+ return fail(
+ 'limit',
+ visualSchema
+ ? 'proxy envelope exceeds maxVisualRequestBodyBytes'
+ : 'proxy envelope exceeds maxRequestBodyBytes',
+ 'size'
+ )
+ }
+ return ok(Object.freeze(envelope))
+ }
+
/**
* Client-side canonical hashing. Serializes `raw` exactly as a JSON peer
- * receives it, parses that wire form with parseCodexCompletionRequestV1, and
- * hashes the validated projection — the same steps control-api authorize and
- * codex-llm-proxy perform. Callers send `value.request` with
+ * receives it, parses that wire form with parseCodexCompletionRequest (v1 or
+ * v2), and hashes the validated projection — the same steps control-api
+ * authorize and the proxy perform. Callers send `value.request` with
* `value.requestHash`, so shapes the parser normalizes away (empty
* generation/tools/transportHints, undefined leaves) cannot make the two ends
* disagree. For an already well-formed request the digest is identical to
diff --cc packages/llm-provider-attempt-contract/index.d.ts
index 9c76691c5,17ed6820b..a08539820
--- a/packages/llm-provider-attempt-contract/index.d.ts
+++ b/packages/llm-provider-attempt-contract/index.d.ts
@@@ -6,6 -6,18 +6,19 @@@
* Hashing uses the same lexicographic stableStringify semantics as
* control-api/src/utils/stableStringify.ts. Non-finite numbers are rejected
* before hashing (stringify would otherwise coerce them to null).
+ *
+ * Two request versions share one dispatcher and one hash:
+ * `codex-completion-request.v1` (text messages, unchanged) and
+ * `codex-completion-request.v2` (the same closed root plus optional ordered
+ * `contentParts` on user messages). V2 shares the V1 root field set on
+ * purpose: it is not a looser schema.
+ *
- * Two size ceilings, one policy: V1 keeps the 1 MiB body ceiling, and V2 raises
- * it to 24 MiB so one exceptional 2048-px image larger than 10 MiB still fits
- * after base64. Everything a caller writes that is not image data — content,
- * tool definitions, ids — stays on the 1 MiB budget in both versions, and
++ * Two size ceilings, one policy: V1 keeps the 8 MiB `maxRequestBodyBytes`
++ * ceiling (#731), and V2 raises it to 24 MiB so one exceptional 2048-px image
++ * larger than 10 MiB still fits after base64. Everything a caller writes that
++ * is not image data — content, tool definitions, ids — stays on the 8 MiB
++ * budget in both versions, and
+ * `requestBodyLimitBytes` is the number a pre-parse HTTP body cap should use.
*/
export declare const SCHEMA_VERSION: 'codex-completion-request.v1'
@@@ -14,7 -27,10 +28,10 @@@ export declare const PROVIDER_ID: 'code
export declare const TICKET_TYP: 'codex-execution-ticket'
export declare const LIMITS: {
+ /** V1 ceiling, and the V2 ceiling for everything that is not image data. */
- readonly maxRequestBodyBytes: 1048576
- /** V2 request/envelope ceiling; covers image payloads plus the V1 share. */
+ readonly maxRequestBodyBytes: 8388608
++ /** V2 request/envelope ceiling; covers image payloads plus the non-image share. */
+ readonly maxVisualRequestBodyBytes: 25165824
readonly maxMessages: 1024
readonly maxToolCalls: 256
readonly maxOutputTokens: 16384
@@@ -133,6 -235,29 +236,31 @@@ export type CodexAttemptReceiptV1 =
}
export declare function stableStringify(value: unknown): string
+ /**
+ * Byte ceiling for a request body, or for the envelope that carries it, applied
+ * BEFORE parsing: 24 MiB for a document that declares
- * `codex-completion-request.v2`, 1 MiB for anything else. Declaring V2 does not
- * raise the budget for text or tool definitions — the parser measures the body
- * with every image payload blanked and keeps that share on the 1 MiB ceiling.
++ * `codex-completion-request.v2`, `maxRequestBodyBytes` (8 MiB) for anything
++ * else. Declaring V2 does not raise the budget for text or tool definitions —
++ * the parser measures the body with every image payload blanked and keeps that
++ * share on the `maxRequestBodyBytes` ceiling.
+ */
+ export declare function requestBodyLimitBytes(request: unknown): number
+ /**
+ * Byte length of an authorize document after every image payload inside
- * `body.request` is blanked. Wrapper fields stay on the 1 MiB non-image
- * budget even when the nested request declares V2.
++ * `body.request` is blanked. Wrapper fields stay on the non-image budget
++ * (`maxRequestBodyBytes` plus the caller's envelope allowance) even when the
++ * nested request declares V2.
+ */
+ export declare function measureNonImageAuthorizeBytes(body: unknown): number
+ /**
+ * Byte length of a proxy completion document after image payloads inside
+ * `body.request` are blanked and `executionTicket` is omitted. The ticket is
- * issued after authorize, so it must not consume the 1 MiB non-image budget
++ * issued after authorize, so it must not consume the non-image budget
+ * that authorize already applied to the pre-ticket wrapper.
+ */
+ export declare function measureNonImageCompletionBytes(body: unknown): number
+ /** Closed identifier used by request ids, ticket claims, and authorize ids. */
+ export declare function isBoundedId(value: unknown): value is string
export declare function parseCodexCompletionRequestV1(
input: unknown
): ContractResult<CodexCompletionRequestV1>
diff --cc packages/llm-provider-attempt-contract/index.test.cjs
index e14ee191a,933067387..12b14b0fe
--- a/packages/llm-provider-attempt-contract/index.test.cjs
+++ b/packages/llm-provider-attempt-contract/index.test.cjs
@@@ -314,65 -366,12 +366,70 @@@ test('large catalogs remain bounded by
})
})
+// A conversation whose size is data, not tools: tool calls answered by
+// minified JSON exports, the shape that filled the subscription paths.
+function dataHeavyConversation(targetBytes) {
+ const row = JSON.stringify({ id: 'c_0001', company: 'Northwind Labs', score: 42.5, tags: ['saas', 'partner'] })
+ const chunk = `[${new Array(Math.ceil((256 * 1024) / (row.length + 1))).fill(row).join(',')}]`
+ const request = {
+ ...BASE,
+ tools: [{ name: 'crm__export', description: 'Export CRM rows', parameters: { type: 'object' } }],
+ messages: [{ role: 'user', content: 'Summarize the CRM export.' }],
+ }
+ for (let i = 0; Buffer.byteLength(JSON.stringify(request), 'utf8') < targetBytes; i++) {
+ const id = `call-${i}`
+ request.messages.push({ role: 'assistant', content: '', toolCalls: [{ id, name: 'crm__export', arguments: { page: i } }] })
+ request.messages.push({ role: 'tool', content: chunk, toolCallId: id, name: 'crm__export' })
+ }
+ return request
+}
+
+// R3-1 (#731): the non-image request cap is 8 MiB. Customer workloads reached
+// the former 1 MiB with data, and 8 MiB carries a 1M-token window as escaped
+// JSON. The two byte-bound tests above derive their payload from LIMITS, so
+// they keep pinning the exact boundary at the new value.
+test('T-R3-1a maxRequestBodyBytes is 8 MiB', () => {
+ assert.equal(contract.LIMITS.maxRequestBodyBytes, 8 * 1024 * 1024)
+})
+
+test('T-R3-1b a 4 MiB conversation of tool results is accepted', () => {
+ const request = dataHeavyConversation(4 * 1024 * 1024)
+ assert.ok(Buffer.byteLength(JSON.stringify(request), 'utf8') >= 4 * 1024 * 1024)
+ const parsed = contract.parseCodexCompletionRequestV1(request)
+ assert.equal(parsed.ok, true, parsed.message)
+})
+
+test('T-E2 the element bound reports itself distinctly from the byte bound', () => {
+ // Before #731 two different guards refused with the identical sentence: the
+ // element count inside `checkStructure` and the real byte measurement that
+ // the two tests above pin. A user reporting `request exceeds
+ // maxRequestBodyBytes` therefore could not say which one fired. Compaction is the remedy either way;
+ // the distinct wording buys diagnosis, not a different fix (#731).
+ //
+ // What makes the two guards separable here is ORDER, not size:
+ // `checkStructure` runs before `JSON.stringify`, so the element count is
+ // refused first. The payload below is also ~3x the byte cap once serialized
+ // — by construction it has to be, since more elements than the byte cap
+ // cannot encode under it — so without that ordering the byte bound would
+ // claim it and this test would be pinning the wrong guard.
+ const refused = contract.parseCodexCompletionRequestV1({
+ ...BASE,
+ messages: new Array(contract.LIMITS.maxRequestBodyBytes + 1).fill({}),
+ })
+ assert.deepEqual(refused, {
+ ok: false,
+ code: 'limit',
++ kind: 'size',
+ message: 'request exceeds maxRequestBodyBytes element bound',
+ })
+})
+
test('validates the last definition beyond the former count boundary', () => {
- for (const invalid of [{ name: 'invalid\u0000name' }, { parameters: { value: Infinity } }, { headers: {} }]) {
+ for (const invalid of [
+ { name: 'invalid\u0000name' },
+ { parameters: { value: Infinity } },
+ { headers: {} },
+ ]) {
const tools = catalog(250)
tools[249] = { ...tools[249], ...invalid }
const parsed = contract.parseCodexCompletionRequestV1({ ...BASE, tools })
@@@ -437,6 -446,969 +504,977 @@@ test('opaque canonical names remain bou
})
})
+ // --- V2 (codex-completion-request.v2) -------------------------------------
+
+ const V2_REQUEST_KEYS = { schemaVersion: contract.SCHEMA_VERSION_V2 }
+ const IMAGE_DATA = {
+ png: VISUAL_FIXTURE.png.messages[0].contentParts.find(part => part.type === 'image').data,
+ jpeg: VISUAL_FIXTURE.jpeg.messages[0].contentParts.find(part => part.type === 'image').data,
+ }
+ const MAX_ENCODED_IMAGE_CHARS = 4 * Math.ceil(contract.VISUAL_LIMITS.maxImageBytes / 3)
+
+ /**
+ * Fixture image parts carry `dataRef` (resolved from visual-requests.json) so
+ * the frozen hash corpus stays readable, and `mutate` for documented
+ * truncations. Resolution returns a deep copy: a loaded fixture is never
+ * mutated in place.
+ */
+ function resolveFixtureImages(value) {
+ if (Array.isArray(value)) return value.map(resolveFixtureImages)
+ if (value && typeof value === 'object') {
+ if (typeof value.dataRef === 'string') {
+ const source = IMAGE_DATA[value.dataRef]
+ assert.ok(source, `unknown image ref ${value.dataRef}`)
+ const bytes = Buffer.from(source, 'base64')
+ let data = source
+ if (value.mutate === 'strip-eoi')
+ data = bytes.subarray(0, bytes.length - 2).toString('base64')
+ else if (value.mutate === 'truncate-after-ihdr')
+ data = bytes.subarray(0, 33).toString('base64')
+ else assert.equal(value.mutate, undefined, `unknown mutate ${value.mutate}`)
+ const clone = { ...value, data }
+ delete clone.dataRef
+ delete clone.mutate
+ return clone
+ }
+ const out = {}
+ for (const [key, inner] of Object.entries(value)) out[key] = resolveFixtureImages(inner)
+ return out
+ }
+ return value
+ }
+
+ function pngChunks(bytes) {
+ const chunks = []
+ let pos = 8
+ while (pos < bytes.length) {
+ const length = bytes.readUInt32BE(pos)
+ chunks.push({
+ type: bytes.toString('latin1', pos + 4, pos + 8),
+ data: bytes.subarray(pos + 8, pos + 8 + length),
+ crc: bytes.readUInt32BE(pos + 8 + length),
+ crcInput: bytes.subarray(pos + 4, pos + 8 + length),
+ })
+ pos += 12 + length
+ }
+ return chunks
+ }
+
+ const MIB = 1024 * 1024
+ // The per-image ceiling this suite replaced. Kept as a literal so the tests
+ // prove the raise rather than restating the current constant.
+ const FORMER_IMAGE_CEILING = 524288
+
+ function imagePart(data, mimeType = 'image/png') {
+ return {
+ type: 'image',
+ mimeType,
+ data,
+ source: { kind: 'tool', attachmentId: 'att_1700000000001_ff00aa11', toolCallId: 'call_abc123' },
+ }
+ }
+
+ function v2WithMessages(messages) {
+ return { ...BASE, ...V2_REQUEST_KEYS, messages }
+ }
+
+ function v2WithParts(parts, content = '') {
+ return v2WithMessages([{ role: 'user', content, contentParts: parts }])
+ }
+
+ function v2TextRequest(content) {
+ return v2WithMessages([{ role: 'user', content }])
+ }
+
+ test('v2 fixture corpus: valid cases match frozen digests and distinct payloads differ', () => {
+ for (const fixture of FIXTURE_V2.cases) {
+ const request = resolveFixtureImages(fixture.request)
+ const parsed = contract.parseCodexCompletionRequest(request)
+ assert.equal(parsed.ok, true, fixture.name)
+ const direct = contract.parseCodexCompletionRequestV2(request)
+ assert.equal(direct.ok, true, fixture.name)
+ assert.deepEqual(parsed, direct, `${fixture.name} dispatcher parity`)
+ const digest = contract.hashCodexCompletionRequest(parsed.value)
+ assert.equal(digest, fixture.sha256, fixture.name)
+ assert.equal(
+ contract.hashCodexCompletionRequest(direct.value),
+ digest,
+ `${fixture.name} hash parity`
+ )
+ if (fixture.distinctRequest) {
+ const other = contract.parseCodexCompletionRequest(
+ resolveFixtureImages(fixture.distinctRequest)
+ )
+ assert.equal(other.ok, true, `${fixture.name} distinct`)
+ assert.notEqual(contract.hashCodexCompletionRequest(other.value), digest, fixture.name)
+ }
+ }
+ })
+
+ test('v2 fixture corpus: rejected payloads fail closed with the frozen code and message', () => {
+ for (const fixture of FIXTURE_V2.rejects) {
+ const parsed = contract.parseCodexCompletionRequest(resolveFixtureImages(fixture.request))
+ assert.equal(parsed.ok, false, fixture.name)
+ assert.equal(parsed.code, fixture.reason, fixture.name)
+ assert.equal(parsed.message, fixture.message, fixture.name)
+ }
+ })
+
+ test('v2 visual fixtures: inline png/jpeg requests parse and pin the exact octets', () => {
+ for (const key of ['png', 'jpeg', 'pngImageOnly']) {
+ const request = VISUAL_FIXTURE[key]
+ assert.equal(request.schemaVersion, contract.SCHEMA_VERSION_V2, key)
+ const imageParts = request.messages[0].contentParts.filter(part => part.type === 'image')
+ assert.equal(imageParts.length, 1, key)
+ const bytes = Buffer.from(imageParts[0].data, 'base64')
+ const pinned = VISUAL_FIXTURE.imageSha256[imageParts[0].mimeType.replace('image/', '')]
+ assert.equal(crypto.createHash('sha256').update(bytes).digest('hex'), pinned, key)
+ const parsed = contract.parseCodexCompletionRequest(request)
+ assert.equal(parsed.ok, true, `${key}: ${parsed.message}`)
+ assert.deepEqual(
+ parsed.value.messages[0].contentParts,
+ request.messages[0].contentParts,
+ `${key} projection`
+ )
+ }
+
+ const png = Buffer.from(IMAGE_DATA.png, 'base64')
+ assert.deepEqual(
+ [png.readUInt32BE(16), png.readUInt32BE(20)],
+ [VISUAL_FIXTURE.expectedDimensions.png.width, VISUAL_FIXTURE.expectedDimensions.png.height]
+ )
+ const jpeg = Buffer.from(IMAGE_DATA.jpeg, 'base64')
+ assert.deepEqual([jpeg[0], jpeg[1]], [0xff, 0xd8])
+ assert.deepEqual([jpeg[jpeg.length - 2], jpeg[jpeg.length - 1]], [0xff, 0xd9])
+ assert.ok(jpeg.includes(Buffer.from([0xff, 0xda])), 'jpeg carries a start-of-scan segment')
+ })
+
+ test('v2 fixture png is a real image: real CRCs and an inflatable scanline stream', () => {
+ const bytes = Buffer.from(IMAGE_DATA.png, 'base64')
+ const chunks = pngChunks(bytes)
+ assert.deepEqual(
+ chunks.map(chunk => chunk.type),
+ ['IHDR', 'IDAT', 'IEND']
+ )
+ for (const chunk of chunks) {
+ assert.equal(chunk.crc, zlib.crc32(chunk.crcInput) >>> 0, chunk.type)
+ }
+ const { width, height } = VISUAL_FIXTURE.expectedDimensions.png
+ const raw = zlib.inflateSync(chunks[1].data)
+ assert.equal(raw.length, height * (1 + width * 3))
+ for (let row = 0; row < height; row++) {
+ assert.equal(raw[row * (1 + width * 3)], 0, `scanline ${row} filter byte`)
+ }
+ })
+
+ test('dispatcher: v1 rejects contentParts, unknown versions fail closed, one hash serves both', () => {
+ const v1WithParts = { ...VISUAL_FIXTURE.png, schemaVersion: contract.SCHEMA_VERSION }
+ const rejected = contract.parseCodexCompletionRequestV1(v1WithParts)
+ assert.equal(rejected.ok, false)
+ assert.equal(rejected.code, 'unknown-field')
+ assert.match(rejected.message, /contentParts/)
+ assert.equal(contract.parseCodexCompletionRequest(v1WithParts).ok, false)
+
+ for (const schemaVersion of ['codex-completion-request.v3', undefined, null, 2]) {
+ const parsed = contract.parseCodexCompletionRequest({ ...BASE, schemaVersion })
+ assert.equal(parsed.ok, false, String(schemaVersion))
+ assert.equal(parsed.code, 'invalid', String(schemaVersion))
+ }
+ assert.equal(contract.parseCodexCompletionRequest('not an object').ok, false)
+
+ const v1 = contract.parseCodexCompletionRequest(BASE)
+ const v2 = contract.parseCodexCompletionRequest(v2TextRequest('hello'))
+ assert.equal(v1.ok, true)
+ assert.equal(v2.ok, true)
+ assert.equal(
+ contract.hashCodexCompletionRequest(v1.value),
+ contract.hashCodexCompletionRequestV1(v1.value)
+ )
+ const withoutVersion = ({ schemaVersion, ...rest }) => rest
+ assert.deepEqual(
+ withoutVersion(v2.value),
+ withoutVersion(v1.value),
+ 'text-only v2 keeps v1 semantics'
+ )
+ assert.notEqual(
+ contract.hashCodexCompletionRequest(v2.value),
+ contract.hashCodexCompletionRequest(v1.value)
+ )
+ })
+
+ test('dispatcher: v2 keeps every v1 root check instead of bypassing it', () => {
+ for (const fixture of FIXTURE.rejects) {
+ const asV1 = contract.parseCodexCompletionRequest(fixture.request)
+ const asV2 = contract.parseCodexCompletionRequest({
+ ...fixture.request,
+ schemaVersion: contract.SCHEMA_VERSION_V2,
+ })
+ assert.equal(asV1.ok, false, fixture.name)
+ assert.equal(asV2.ok, false, `${fixture.name} v2`)
+ assert.equal(asV2.code, asV1.code, `${fixture.name} code`)
+ }
+
+ const roots = [
+ { name: 'requestId', patch: { requestId: 'bad id' } },
+ { name: 'idempotencyKey', patch: { idempotencyKey: 'é' } },
+ { name: 'provider', patch: { provider: 'openai-api' } },
+ { name: 'model', patch: { model: 'bad model' } },
+ { name: 'deadline-low', patch: { deadlineMs: 0 }, code: 'limit' },
+ {
+ name: 'deadline-high',
+ patch: { deadlineMs: contract.LIMITS.maxDeadlineMs + 1 },
+ code: 'limit',
+ },
+ { name: 'deadline-fraction', patch: { deadlineMs: 1.5 }, code: 'non-finite' },
+ {
+ name: 'deadline-nonfinite',
+ patch: { deadlineMs: Number.POSITIVE_INFINITY },
+ code: 'non-finite',
+ },
+ { name: 'generation-unknown', patch: { generation: { topK: 5 } } },
+ { name: 'generation-temperature', patch: { generation: { temperature: 3 } } },
+ { name: 'transport-hints-unknown', patch: { transportHints: { cacheKey: 'x' } } },
+ { name: 'messages-empty', patch: { messages: [] } },
+ { name: 'message-role', patch: { messages: [{ role: 'human', content: 'x' }] } },
+ { name: 'message-content-type', patch: { messages: [{ role: 'user', content: 5 }] } },
+ {
+ name: 'message-tool-calls-on-user',
+ patch: {
+ messages: [
+ { role: 'user', content: 'x', toolCalls: [{ id: 'a', name: 'b', arguments: {} }] },
+ ],
+ },
+ },
+ { name: 'tool-description', patch: { tools: [{ name: 'a', description: 1, parameters: {} }] } },
+ {
+ name: 'tool-name-control',
+ patch: { tools: [{ name: 'a\u0000b', description: 'x', parameters: {} }] },
+ },
+ {
+ name: 'text-part-text-type',
+ patch: {
+ messages: [{ role: 'user', content: 'x', contentParts: [{ type: 'text', text: 5 }] }],
+ },
+ },
+ ]
+ for (const entry of roots) {
+ const parsed = contract.parseCodexCompletionRequest({
+ ...BASE,
+ ...V2_REQUEST_KEYS,
+ ...entry.patch,
+ })
+ assert.equal(parsed.ok, false, entry.name)
+ if (entry.code) assert.equal(parsed.code, entry.code, entry.name)
+ }
+ })
+
+ test('v2 projection preserves part order, source identity and the text projection verbatim', () => {
+ const multi = resolveFixtureImages(
+ FIXTURE_V2.cases.find(item => item.name === 'multi-image-order-significant').request
+ )
+ const parsed = contract.parseCodexCompletionRequest(multi)
+ assert.equal(parsed.ok, true)
+ assert.equal(Object.isFrozen(parsed.value), true)
+ assert.deepEqual(parsed.value.messages[0].contentParts, multi.messages[0].contentParts)
+ assert.deepEqual(
+ parsed.value.messages[0].contentParts.map(part => part.type),
+ ['text', 'image', 'image']
+ )
+
+ const compacted = resolveFixtureImages(
+ FIXTURE_V2.cases.find(item => item.name === 'text-only-parts-after-compaction').request
+ )
+ const parsedCompacted = contract.parseCodexCompletionRequest(compacted)
+ assert.equal(parsedCompacted.ok, true)
+ const parts = parsedCompacted.value.messages[0].contentParts
+ assert.ok(
+ parts.every(part => part.type === 'text'),
+ 'text-only parts survive without an image'
+ )
+ assert.equal(parsedCompacted.value.messages[0].content, parts.map(part => part.text).join('\n'))
+
+ const imageOnly = contract.parseCodexCompletionRequest(VISUAL_FIXTURE.pngImageOnly)
+ assert.equal(imageOnly.ok, true)
+ assert.equal(imageOnly.value.messages[0].content, '', 'an image-only message has empty text')
+ })
+
+ test('v2 limits: image count, encoder bound, per-image bytes, total bytes, dimensions and pixels', () => {
+ const png = IMAGE_DATA.png
+ const twenty = Array.from({ length: contract.VISUAL_LIMITS.maxImages }, () => imagePart(png))
+ assert.equal(
+ contract.parseCodexCompletionRequest(v2WithParts(twenty)).ok,
+ true,
+ 'twenty images fit'
+ )
+ const twentyOne = contract.parseCodexCompletionRequest(v2WithParts([...twenty, imagePart(png)]))
+ assert.equal(twentyOne.ok, false)
+ assert.equal(twentyOne.code, 'limit')
+ assert.match(twentyOne.message, /20 images/)
+
+ const encoded = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart('A'.repeat(MAX_ENCODED_IMAGE_CHARS + 4))])
+ )
+ assert.equal(encoded.code, 'limit', 'encoded length is bounded before decoding')
+ const decoded = contract.parseCodexCompletionRequest(
+ v2WithParts([
+ imagePart(Buffer.alloc(contract.VISUAL_LIMITS.maxImageBytes + 1).toString('base64')),
+ ])
+ )
+ assert.equal(decoded.code, 'limit')
+
+ // Above the ceiling this suite replaced, in both accepted containers.
+ const pngOverFormerCeiling = declaredHeaderPngOfSize(FORMER_IMAGE_CEILING + 1)
+ assert.equal(pngOverFormerCeiling.length, FORMER_IMAGE_CEILING + 1)
+ const acceptedPng = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(pngOverFormerCeiling.toString('base64'))])
+ )
+ assert.equal(acceptedPng.ok, true, acceptedPng.message)
+ const acceptedJpeg = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(jpegOfSize(FORMER_IMAGE_CEILING + 1).toString('base64'), 'image/jpeg')])
+ )
+ assert.equal(acceptedJpeg.ok, true, acceptedJpeg.message)
+ const acceptedFiveMiBJpeg = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(jpegOfSize(5 * MIB).toString('base64'), 'image/jpeg')])
+ )
+ assert.equal(acceptedFiveMiBJpeg.ok, true, acceptedFiveMiBJpeg.message)
+
+ // 3 MiB, and exactly the per-image ceiling, are inside the budget.
+ const acceptedThreeMiB = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(declaredHeaderPngOfSize(3 * MIB).toString('base64'))])
+ )
+ assert.equal(acceptedThreeMiB.ok, true, acceptedThreeMiB.message)
+ const acceptedCeiling = contract.parseCodexCompletionRequest(
+ v2WithParts([
+ imagePart(declaredHeaderPngOfSize(contract.VISUAL_LIMITS.maxImageBytes).toString('base64')),
+ ])
+ )
+ assert.equal(acceptedCeiling.ok, true, acceptedCeiling.message)
+
+ // One byte over the per-image ceiling, as a container that is otherwise valid.
+ const overCeiling = contract.parseCodexCompletionRequest(
+ v2WithParts([
+ imagePart(
+ declaredHeaderPngOfSize(contract.VISUAL_LIMITS.maxImageBytes + 1).toString('base64')
+ ),
+ ])
+ )
+ assert.equal(overCeiling.ok, false)
+ assert.equal(overCeiling.code, 'limit')
+ assert.match(overCeiling.message, /image exceeds/)
+ assert.match(overCeiling.message, new RegExp(String(contract.VISUAL_LIMITS.maxImageBytes)))
+
+ // Exceptional >10 MiB is allowed; the hard per-image ceiling is 16 MiB.
+ const twelveMiB = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(declaredHeaderPngOfSize(12 * MIB).toString('base64'))])
+ )
+ assert.equal(twelveMiB.ok, true, twelveMiB.message)
+
+ // A larger individual image does not increase the aggregate resource budget.
+ const tenMiB = declaredHeaderPngOfSize(10 * MIB).toString('base64')
+ const fiveMiB = declaredHeaderPngOfSize(5 * MIB).toString('base64')
+ const combined = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(tenMiB), imagePart(fiveMiB)])
+ )
+ assert.equal(combined.ok, true, combined.message)
+ const combinedWithJpeg = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(tenMiB), imagePart(jpegOfSize(5 * MIB).toString('base64'), 'image/jpeg')])
+ )
+ assert.equal(combinedWithJpeg.ok, true, combinedWithJpeg.message)
+ const atAggregate = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(tenMiB), imagePart(declaredHeaderPngOfSize(6 * MIB).toString('base64'))])
+ )
+ assert.equal(atAggregate.ok, true, atAggregate.message)
+ const overAggregate = contract.parseCodexCompletionRequest(
+ v2WithParts([
+ imagePart(tenMiB),
+ imagePart(declaredHeaderPngOfSize(6 * MIB + 1).toString('base64')),
+ ])
+ )
+ assert.equal(overAggregate.ok, false)
+ assert.equal(overAggregate.code, 'limit')
+ assert.match(overAggregate.message, /total image bytes/)
+
+ const atDimension = contract.parseCodexCompletionRequest(
+ v2WithParts([
+ imagePart(realPng(contract.VISUAL_LIMITS.maxImageDimension, 1, 9).toString('base64')),
+ ])
+ )
+ assert.equal(atDimension.ok, true, atDimension.message)
+ const overDimension = contract.parseCodexCompletionRequest(
+ v2WithParts([
+ imagePart(realPng(contract.VISUAL_LIMITS.maxImageDimension + 1, 1, 11).toString('base64')),
+ ])
+ )
+ assert.equal(overDimension.code, 'limit')
+ assert.equal(overDimension.kind, 'size')
+ assert.match(overDimension.message, /dimension/)
+
+ // Phone-sized frames are a Codex pixel problem, not a byte problem.
+ const phoneShape = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(declaredHeaderPng(8064, 6048).toString('base64'))])
+ )
+ assert.equal(phoneShape.ok, false)
+ assert.equal(phoneShape.code, 'limit')
+ assert.equal(phoneShape.kind, 'size')
+ assert.match(phoneShape.message, /dimension/)
+
+ // 2048×2048 is both the dimension and the pixel ceiling.
+ assert.equal(
+ contract.VISUAL_LIMITS.maxImageDimension * contract.VISUAL_LIMITS.maxImageDimension,
+ contract.VISUAL_LIMITS.maxImagePixels
+ )
+ const atPixels = contract.parseCodexCompletionRequest(
+ v2WithParts([
+ imagePart(
+ declaredHeaderPng(
+ contract.VISUAL_LIMITS.maxImageDimension,
+ contract.VISUAL_LIMITS.maxImageDimension
+ ).toString('base64')
+ ),
+ ])
+ )
+ assert.equal(atPixels.ok, true, atPixels.message)
+
+ const wrongMime = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(png, 'image/jpeg')])
+ )
+ assert.equal(wrongMime.ok, false, 'mime and container signature must agree')
+ const jpegAsPng = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(IMAGE_DATA.jpeg, 'image/png')])
+ )
+ assert.equal(jpegAsPng.ok, false)
+ })
+
+ test('v2 visual budgets are request-scoped across messages: twenty small images fit, twenty-one do not', () => {
+ const png = IMAGE_DATA.png
+ const userWithImages = count => ({
+ role: 'user',
+ content: '',
+ contentParts: Array.from({ length: count }, () => imagePart(png)),
+ })
+
+ // 11 + 10 images: every message is inside maxImages on its own, the request is not.
+ const splitOverCap = contract.parseCodexCompletionRequest(
+ v2WithMessages([userWithImages(11), userWithImages(10)])
+ )
+ assert.equal(splitOverCap.ok, false)
+ assert.equal(splitOverCap.code, 'limit')
+ assert.match(splitOverCap.message, /20 images/)
+
+ // Boundary: exactly maxImages spread over twenty messages is accepted.
+ const oneEach = contract.parseCodexCompletionRequest(
+ v2WithMessages(Array.from({ length: contract.VISUAL_LIMITS.maxImages }, () => userWithImages(1)))
+ )
+ assert.equal(oneEach.ok, true, oneEach.message)
+
+ // Three 5 MiB images across messages fill the unchanged aggregate budget.
+ const atCeiling = declaredHeaderPngOfSize(5 * MIB).toString('base64')
+ const messageWith = encoded => ({
+ role: 'user',
+ content: '',
+ contentParts: [imagePart(encoded)],
+ })
+ const oneEachAtCeiling = contract.parseCodexCompletionRequest(
+ v2WithMessages([messageWith(atCeiling), messageWith(atCeiling), messageWith(atCeiling)])
+ )
+ assert.equal(oneEachAtCeiling.ok, true, oneEachAtCeiling.message)
+ // Three ceiling images are the exact aggregate boundary, and the encoded body
+ // is larger than the V1 ceiling — this is the request that needs the V2 budget.
+ const ceilingBody = Buffer.byteLength(
+ JSON.stringify(
+ v2WithMessages([messageWith(atCeiling), messageWith(atCeiling), messageWith(atCeiling)])
+ ),
+ 'utf8'
+ )
+ assert.ok(ceilingBody > contract.LIMITS.maxRequestBodyBytes)
+ assert.ok(ceilingBody <= contract.LIMITS.maxVisualRequestBodyBytes)
+
+ // A fourth ceiling image is refused before the count gate is reached: four
+ // 5 MiB payloads encode to more than the 24 MiB body ceiling. The count rule
+ // is exercised with small images above; this asserts which gate fires first
+ // for maximum-size payloads.
+ const fourMessages = contract.parseCodexCompletionRequest(
+ v2WithMessages([
+ messageWith(atCeiling),
+ messageWith(atCeiling),
+ messageWith(atCeiling),
+ messageWith(atCeiling),
+ ])
+ )
+ assert.equal(fourMessages.ok, false)
+ assert.equal(fourMessages.code, 'limit')
+ assert.equal(fourMessages.message, 'request exceeds maxVisualRequestBodyBytes')
+ })
+
+ /**
+ * The request with every image payload replaced by an empty string — the
+ * non-image share the V2 budget is defined on. Used to find an exact boundary;
+ * the assertions below always check the contract's verdict, not this helper.
+ */
+ function nonImageBytes(request) {
+ return Buffer.byteLength(
+ JSON.stringify({
+ ...request,
+ messages: request.messages.map(message =>
+ Array.isArray(message.contentParts)
+ ? {
+ ...message,
+ contentParts: message.contentParts.map(part =>
+ part.type === 'image' ? { ...part, data: '' } : part
+ ),
+ }
+ : message
+ ),
+ }),
+ 'utf8'
+ )
+ }
+
-test('requestBodyLimitBytes: V2 declares 24 MiB; every other body keeps the 1 MiB ceiling', () => {
- assert.equal(contract.LIMITS.maxRequestBodyBytes, 1048576)
++test('requestBodyLimitBytes: V2 declares 24 MiB; every other body keeps the 8 MiB ceiling', () => {
++ assert.equal(contract.LIMITS.maxRequestBodyBytes, 8388608)
+ assert.equal(contract.LIMITS.maxVisualRequestBodyBytes, 25165824)
+ assert.equal(contract.VISUAL_LIMITS.maxImages, 20)
+ assert.equal(contract.VISUAL_LIMITS.typicalImageBytes, 5 * MIB)
+ assert.equal(contract.VISUAL_LIMITS.typicalTotalImageBytes, 9 * MIB)
+ assert.equal(contract.VISUAL_LIMITS.typicalEnvelopeBytes, 14 * MIB)
+ assert.equal(contract.VISUAL_LIMITS.maxImageBytes, 16 * MIB)
+ assert.equal(contract.VISUAL_LIMITS.maxTotalImageBytes, 16 * MIB)
+ assert.equal(contract.VISUAL_LIMITS.maxImageDimension, 2048)
+ assert.equal(contract.VISUAL_LIMITS.maxImagePixels, 2048 * 2048)
+
+ for (const v2 of [VISUAL_FIXTURE.png, VISUAL_FIXTURE.jpeg, VISUAL_FIXTURE.pngImageOnly]) {
+ assert.equal(v2.schemaVersion, contract.SCHEMA_VERSION_V2)
+ assert.equal(contract.requestBodyLimitBytes(v2), 25165824)
+ }
+ // A declaration is not a payload: unknown, missing and non-object bodies keep
+ // the smaller ceiling so a caller cannot ask for the larger budget it has not
+ // satisfied.
+ for (const other of [
+ BASE,
+ { ...BASE, schemaVersion: 'codex-completion-request.v3' },
+ { ...BASE, schemaVersion: undefined },
+ {},
+ null,
+ undefined,
+ 'x',
+ 7,
+ [],
+ ]) {
- assert.equal(contract.requestBodyLimitBytes(other), 1048576, String(other))
++ assert.equal(contract.requestBodyLimitBytes(other), contract.LIMITS.maxRequestBodyBytes, String(other))
+ }
+ })
+
-test('v2 preserves the non-image budget: text and tools stay on the 1 MiB ceiling', () => {
++test('v2 preserves the non-image budget: text and tools stay on the maxRequestBodyBytes ceiling', () => {
+ const { maxRequestBodyBytes, maxVisualRequestBodyBytes } = contract.LIMITS
+ const image = imagePart(IMAGE_DATA.png)
+ const overflow = 'request exceeds maxRequestBodyBytes outside image data'
- const longText = 'x'.repeat(2 * MIB)
++ const longText = 'x'.repeat(maxRequestBodyBytes + MIB)
+
- // Images do not buy text: 2 MiB of content-class payload is refused far below
- // the 24 MiB ceiling the same body is allowed to use for image data.
++ // Images do not buy text: content-class payload over the non-image cap is
++ // refused below the 24 MiB ceiling the same body may use for image data.
+ const textHeavy = contract.parseCodexCompletionRequest(
+ v2WithParts([image, { type: 'text', text: longText }], longText)
+ )
+ assert.equal(textHeavy.ok, false)
+ assert.equal(textHeavy.code, 'limit')
+ assert.equal(textHeavy.message, overflow)
+
+ // A text-only V2 body is not a 24 MiB allowance either.
+ assert.deepEqual(contract.parseCodexCompletionRequest(v2TextRequest(longText)), {
+ ok: false,
+ code: 'limit',
+ kind: 'size',
+ message: overflow,
+ })
+
+ // Tool definitions are on the same caller-controlled budget.
+ const toolHeavy = contract.parseCodexCompletionRequest({
+ ...v2WithParts([image]),
- tools: [{ name: 'read', description: 'y'.repeat(2 * MIB), parameters: {} }],
++ tools: [{ name: 'read', description: 'y'.repeat(maxRequestBodyBytes + MIB), parameters: {} }],
+ })
+ assert.equal(toolHeavy.ok, false)
+ assert.equal(toolHeavy.code, 'limit')
+ assert.equal(toolHeavy.message, overflow)
+
+ // Exact boundary. The image is blanked out of the measurement, so the largest
+ // accepted text still leaves the body far under the V2 ceiling, and one byte
+ // more is refused by the non-image rule.
+ const withImageAndText = length =>
+ v2WithParts([image, { type: 'text', text: 'z'.repeat(length) }], 'z'.repeat(length))
+ const base = nonImageBytes(withImageAndText(0))
+ const growth = (nonImageBytes(withImageAndText(10)) - base) / 10
+ assert.equal(growth, 2, 'content and its text part both carry the payload')
+ const exactLength = Math.floor((maxRequestBodyBytes - base) / growth)
+ const boundary = nonImageBytes(withImageAndText(exactLength))
+ assert.ok(
+ boundary <= maxRequestBodyBytes && boundary > maxRequestBodyBytes - growth,
+ `non-image boundary landed at ${boundary}`
+ )
+ const bodyAtBoundary = Buffer.byteLength(JSON.stringify(withImageAndText(exactLength)), 'utf8')
+ assert.ok(
+ bodyAtBoundary < maxVisualRequestBodyBytes,
+ 'the non-image boundary is decided well below the V2 ceiling'
+ )
+ const atLimit = contract.parseCodexCompletionRequest(withImageAndText(exactLength))
+ assert.equal(atLimit.ok, true, atLimit.message)
+ const overLimit = contract.parseCodexCompletionRequest(withImageAndText(exactLength + 1))
+ assert.equal(overLimit.ok, false)
+ assert.equal(overLimit.code, 'limit')
+ assert.equal(overLimit.message, overflow)
+ assert.ok(
+ nonImageBytes(withImageAndText(exactLength + 1)) > maxRequestBodyBytes,
+ 'the rejection is the non-image budget, not another gate'
+ )
+ })
+
+ test('v2 total budget: the raw body is capped at 24 MiB and the three budgets stay consistent', () => {
+ const { maxVisualRequestBodyBytes, maxRequestBodyBytes } = contract.LIMITS
- // The V2 ceiling must cover the largest legal image set (3 x 5 MiB decoded, so
- // ~21 MiB of canonical base64) plus the whole non-image share. Asserted so a
- // future change to any of the three image numbers is caught here.
++ // The V2 ceiling covers the whole non-image share plus its envelope, and the
++ // largest legal image set (16 MiB decoded, ~21.3 MiB of canonical base64)
++ // plus a documented non-image floor. It does not cover both maxima at once
++ // (#731 raised the non-image share to 8 MiB); a request carrying both is
++ // refused by the whole-body gate. Asserted so a change to any of the image
++ // numbers or to either ceiling is caught here.
+ const aggregateEncoded = 4 * Math.ceil(contract.VISUAL_LIMITS.maxTotalImageBytes / 3) + 8
- assert.ok(aggregateEncoded + maxRequestBodyBytes < maxVisualRequestBodyBytes)
++ const nonImageFloorBesideMaxImages = 2.5 * 1024 * 1024
++ assert.ok(maxRequestBodyBytes + 16 * 1024 < maxVisualRequestBodyBytes)
++ assert.ok(maxVisualRequestBodyBytes - aggregateEncoded >= nonImageFloorBesideMaxImages)
+
+ // Over the ceiling is refused by the size gate, before any payload work.
+ const oversized = v2WithParts([imagePart('A'.repeat(maxVisualRequestBodyBytes))])
+ assert.ok(Buffer.byteLength(JSON.stringify(oversized), 'utf8') > maxVisualRequestBodyBytes)
+ const refused = contract.parseCodexCompletionRequest(oversized)
+ assert.equal(refused.ok, false)
+ assert.equal(refused.code, 'limit')
+ assert.equal(refused.message, 'request exceeds maxVisualRequestBodyBytes')
+
+ // The same shape parsed as V1 keeps the V1 ceiling and its V1 message: the
+ // larger budget is a property of the version, not of the payload.
+ const asV1 = contract.parseCodexCompletionRequestV1({
+ ...oversized,
+ schemaVersion: contract.SCHEMA_VERSION,
+ })
+ assert.equal(asV1.ok, false)
+ assert.equal(asV1.code, 'limit')
+ assert.equal(asV1.message, 'request exceeds maxRequestBodyBytes')
+ })
+
+ test('large real PNG: CRCs and inflatable scanlines at 3 MiB and at 10 MiB', () => {
+ const cases = [
+ ['3 MiB', 3 * MIB, 512, 512, 21],
+ ['10 MiB', 10 * MIB, 1150, 1150, 31],
+ ]
+ for (const [label, target, width, height, seed] of cases) {
+ const png = realPngOfSize(target, width, height, seed)
+ assert.equal(png.length, target, label)
+ const chunks = pngChunks(png)
+ assert.deepEqual(
+ chunks.map(chunk => chunk.type),
+ ['IHDR', 'IDAT', 'tEXt', 'IEND'],
+ label
+ )
+ for (const chunk of chunks) {
+ assert.equal(chunk.crc, zlib.crc32(chunk.crcInput) >>> 0, `${label} ${chunk.type} crc`)
+ }
+ const raw = zlib.inflateSync(chunks[1].data)
+ assert.equal(raw.length, height * (1 + width * 3), label)
+ const parsed = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(png.toString('base64'))])
+ )
+ assert.equal(parsed.ok, true, `${label}: ${parsed.message}`)
+ }
+ })
+
+ test('shared pads keep a real fixture JPEG/PNG contract-valid at 5 MiB', () => {
+ const jpeg = padJpegToSize(Buffer.from(IMAGE_DATA.jpeg, 'base64'), 5 * MIB)
+ const png = padPngToSize(Buffer.from(IMAGE_DATA.png, 'base64'), 5 * MIB)
+ assert.equal(jpeg.length, 5 * MIB)
+ assert.equal(png.length, 5 * MIB)
+ const jpegParsed = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(jpeg.toString('base64'), 'image/jpeg')])
+ )
+ const pngParsed = contract.parseCodexCompletionRequest(
+ v2WithParts([imagePart(png.toString('base64'))])
+ )
+ assert.equal(jpegParsed.ok, true, jpegParsed.message)
+ assert.equal(pngParsed.ok, true, pngParsed.message)
+ })
+
+ test('buildCodexProxyEnvelope: exact shape, no outer deadline, exact size boundary', () => {
+ const ticket = 'header.payload.signature'.repeat(3)
+ const parsed = contract.parseCodexCompletionRequest({
+ ...BASE,
+ ...V2_REQUEST_KEYS,
+ deadlineMs: 15000,
+ })
+ assert.equal(parsed.ok, true)
+ const requestHash = contract.hashCodexCompletionRequest(parsed.value)
+ const envelope = contract.buildCodexProxyEnvelope({
+ executionTicket: ticket,
+ requestHash,
+ request: parsed.value,
+ })
+ assert.equal(envelope.ok, true, envelope.message)
+ assert.deepEqual(Object.keys(envelope.value), ['executionTicket', 'requestHash', 'request'])
+ assert.equal('deadlineMs' in envelope.value, false, 'outer deadline is never emitted')
+ assert.equal(
+ envelope.value.request.deadlineMs,
+ 15000,
+ 'deadline travels inside the hashed request'
+ )
+ assert.equal(Object.isFrozen(envelope.value), true)
+ assert.equal(
+ Buffer.byteLength(JSON.stringify(envelope.value), 'utf8') <=
+ contract.requestBodyLimitBytes(envelope.value.request),
+ true
+ )
+
+ const shifted = contract.parseCodexCompletionRequest({
+ ...BASE,
+ ...V2_REQUEST_KEYS,
+ deadlineMs: 15001,
+ })
+ assert.notEqual(
+ contract.hashCodexCompletionRequest(shifted.value),
+ requestHash,
+ 'the deadline is bound by the request hash'
+ )
+
+ // V2 exact boundary. The request's own share is bounded (images at ~21 MiB
+ // encoded, everything else at 1 MiB), so padding its text can no longer reach
+ // the envelope ceiling — the ticket is the field that moves it, and the ticket
+ // is what the authorizer really adds.
+ const envelopeForTicket = ticketBytes => {
+ const request = contract.parseCodexCompletionRequest(VISUAL_FIXTURE.png)
+ assert.equal(request.ok, true, request.message)
+ const hash = contract.hashCodexCompletionRequest(request.value)
+ const executionTicket = 't'.repeat(ticketBytes)
+ return {
+ executionTicket,
+ hash,
+ request,
+ size: Buffer.byteLength(
+ JSON.stringify({ executionTicket, requestHash: hash, request: request.value }),
+ 'utf8'
+ ),
+ }
+ }
+ const limit = contract.requestBodyLimitBytes(parsed.value)
+ assert.equal(limit, contract.LIMITS.maxVisualRequestBodyBytes)
+ const probe = envelopeForTicket(8)
+ const exactTicket = 8 + (limit - probe.size)
+ const exact = envelopeForTicket(exactTicket)
+ assert.equal(exact.size, limit)
+ const atLimit = contract.buildCodexProxyEnvelope({
+ executionTicket: exact.executionTicket,
+ requestHash: exact.hash,
+ request: exact.request.value,
+ })
+ assert.equal(atLimit.ok, true, atLimit.message)
+ assert.equal(Buffer.byteLength(JSON.stringify(atLimit.value), 'utf8'), limit)
+
+ const over = envelopeForTicket(exactTicket + 1)
+ assert.equal(over.size, limit + 1)
+ const refused = contract.buildCodexProxyEnvelope({
+ executionTicket: over.executionTicket,
+ requestHash: over.hash,
+ request: over.request.value,
+ })
+ assert.equal(refused.ok, false)
+ assert.equal(refused.code, 'limit')
+ assert.equal(refused.message, 'proxy envelope exceeds maxVisualRequestBodyBytes')
+
+ // V1 keeps the 1 MiB envelope ceiling: same construction, exact boundary, and
+ // the V1 failure message.
+ const v1Request = contract.parseCodexCompletionRequest({ ...BASE, deadlineMs: 5000 })
+ assert.equal(v1Request.ok, true)
+ const v1Hash = contract.hashCodexCompletionRequest(v1Request.value)
+ const v1Size = ticketBytes =>
+ Buffer.byteLength(
+ JSON.stringify({
+ executionTicket: 't'.repeat(ticketBytes),
+ requestHash: v1Hash,
+ request: v1Request.value,
+ }),
+ 'utf8'
+ )
+ const v1Ticket = 8 + (contract.LIMITS.maxRequestBodyBytes - v1Size(8))
+ const v1Exact = contract.buildCodexProxyEnvelope({
+ executionTicket: 't'.repeat(v1Ticket),
+ requestHash: v1Hash,
+ request: v1Request.value,
+ })
+ assert.equal(v1Exact.ok, true, v1Exact.message)
+ assert.equal(Buffer.byteLength(JSON.stringify(v1Exact.value), 'utf8'), v1Size(v1Ticket))
+ assert.equal(
+ Buffer.byteLength(JSON.stringify(v1Exact.value), 'utf8'),
+ contract.LIMITS.maxRequestBodyBytes
+ )
+ const v1Over = contract.buildCodexProxyEnvelope({
+ executionTicket: 't'.repeat(v1Ticket + 1),
+ requestHash: v1Hash,
+ request: v1Request.value,
+ })
+ assert.equal(v1Over.ok, false)
+ assert.equal(v1Over.code, 'limit')
+ assert.equal(v1Over.message, 'proxy envelope exceeds maxRequestBodyBytes')
+ })
+
+ test('buildCodexProxyEnvelope: fails closed on hash mismatch, bad input and invalid requests', () => {
+ const ticket = 'header.payload.signature'
+ const parsed = contract.parseCodexCompletionRequest(VISUAL_FIXTURE.png)
+ assert.equal(parsed.ok, true)
+ const requestHash = contract.hashCodexCompletionRequest(parsed.value)
+ const cases = [
+ {
+ name: 'hash-mismatch',
+ input: { executionTicket: ticket, requestHash: 'a'.repeat(64), request: parsed.value },
+ code: 'request_hash_mismatch',
+ },
+ {
+ name: 'hash-shape',
+ input: { executionTicket: ticket, requestHash: 'not-a-digest', request: parsed.value },
+ code: 'invalid',
+ },
+ {
+ name: 'unknown-envelope-field',
+ input: { executionTicket: ticket, requestHash, request: parsed.value, deadlineMs: 1000 },
+ code: 'unknown-field',
+ },
+ {
+ name: 'short-ticket',
+ input: { executionTicket: 'short', requestHash, request: parsed.value },
+ code: 'invalid',
+ },
+ {
+ name: 'ticket-control-character',
+ input: { executionTicket: 'ticket\u0000value', requestHash, request: parsed.value },
+ code: 'invalid',
+ },
+ {
+ name: 'request-unknown-root-field',
+ input: {
+ executionTicket: ticket,
+ requestHash,
+ request: { ...VISUAL_FIXTURE.png, headers: { Authorization: 'Bearer x' } },
+ },
+ code: 'unknown-field',
+ },
+ {
+ name: 'request-contradictory-parts',
+ input: {
+ executionTicket: ticket,
+ requestHash,
+ request: v2WithParts([{ type: 'text', text: 'actual' }], 'different'),
+ },
+ code: 'invalid',
+ },
+ ]
+ for (const entry of cases) {
+ const built = contract.buildCodexProxyEnvelope(entry.input)
+ assert.equal(built.ok, false, entry.name)
+ assert.equal(built.code, entry.code, entry.name)
+ }
+ assert.equal(contract.buildCodexProxyEnvelope(null).code, 'invalid')
+
+ const v1 = contract.parseCodexCompletionRequest({ ...BASE, deadlineMs: 5000 })
+ assert.equal(v1.ok, true)
+ const v1Envelope = contract.buildCodexProxyEnvelope({
+ executionTicket: ticket,
+ requestHash: contract.hashCodexCompletionRequest(v1.value),
+ request: v1.value,
+ })
+ assert.equal(v1Envelope.ok, true, v1Envelope.message)
+ assert.deepEqual(Object.keys(v1Envelope.value), ['executionTicket', 'requestHash', 'request'])
+ assert.equal('deadlineMs' in v1Envelope.value, false)
+ })
+
+ test('isBoundedId rejects empty, oversized, and non-id characters', () => {
+ assert.equal(contract.isBoundedId('invocation-1'), true)
+ assert.equal(contract.isBoundedId('ns/name:slot'), true)
+ assert.equal(contract.isBoundedId(''), false)
+ assert.equal(contract.isBoundedId('x'.repeat(129)), false)
+ assert.equal(contract.isBoundedId('has space'), false)
+ assert.equal(contract.isBoundedId(1), false)
+ })
+
-test('measureNonImageAuthorizeBytes keeps wrapper fields on the 1 MiB budget', () => {
++test('measureNonImageAuthorizeBytes keeps wrapper fields on the maxRequestBodyBytes budget', () => {
+ const image = imagePart(IMAGE_DATA.png)
+ const request = {
+ ...BASE,
+ schemaVersion: contract.SCHEMA_VERSION_V2,
+ messages: [
+ {
+ role: 'user',
+ content: 'look',
+ contentParts: [{ type: 'text', text: 'look' }, image],
+ },
+ ],
+ }
+ const wrapper = {
+ request,
+ invocationId: 'invocation-1',
+ attemptGeneration: 1,
+ targetRef: 'codex-primary',
+ }
+ const whole = Buffer.byteLength(JSON.stringify(wrapper), 'utf8')
+ const nonImage = contract.measureNonImageAuthorizeBytes(wrapper)
+ assert.ok(whole > nonImage)
+ assert.ok(nonImage < contract.LIMITS.maxRequestBodyBytes)
+ assert.equal(contract.requestBodyLimitBytes(wrapper.request), 25165824)
+
- const stuffed = { ...wrapper, invocationId: 'x'.repeat(2 * 1024 * 1024) }
++ const stuffed = {
++ ...wrapper,
++ invocationId: 'x'.repeat(contract.LIMITS.maxRequestBodyBytes + 1024 * 1024),
++ }
+ assert.ok(contract.measureNonImageAuthorizeBytes(stuffed) > contract.LIMITS.maxRequestBodyBytes)
+ assert.equal(contract.requestBodyLimitBytes(stuffed.request), 25165824)
+ })
+
+ test('measureNonImageCompletionBytes omits the execution ticket', () => {
+ const request = {
+ ...BASE,
+ schemaVersion: contract.SCHEMA_VERSION_V2,
+ messages: [
+ {
+ role: 'user',
+ content: 'look',
+ contentParts: [{ type: 'text', text: 'look' }, imagePart(IMAGE_DATA.png)],
+ },
+ ],
+ }
+ const authorize = {
+ request,
+ invocationId: 'invocation-1',
+ attemptGeneration: 1,
+ targetRef: 'codex-primary',
+ }
+ const room = 500
+ const pad =
+ contract.LIMITS.maxRequestBodyBytes - contract.measureNonImageAuthorizeBytes(authorize) - room
+ assert.ok(pad > 64)
+ const tightAuthorize = {
+ ...authorize,
+ invocationId: `${authorize.invocationId}${'x'.repeat(pad)}`,
+ }
+ assert.ok(contract.measureNonImageAuthorizeBytes(tightAuthorize) < contract.LIMITS.maxRequestBodyBytes)
+
+ const completion = {
+ ...tightAuthorize,
+ requestHash: 'a'.repeat(64),
+ executionTicket: `header.${'a'.repeat(2048)}.sig`,
+ }
+ assert.ok(contract.measureNonImageAuthorizeBytes(completion) > contract.LIMITS.maxRequestBodyBytes)
+ assert.ok(contract.measureNonImageCompletionBytes(completion) <= contract.LIMITS.maxRequestBodyBytes)
+ assert.equal(
+ contract.measureNonImageCompletionBytes(completion),
+ contract.measureNonImageAuthorizeBytes({
+ ...tightAuthorize,
+ requestHash: completion.requestHash,
+ })
+ )
+ })
+
// ---------------------------------------------------------------------------
// Canonical hashing shared by mcp-host (client) and control-api/codex-llm-proxy
// (server), plus the structural depth cap.
diff --cc packages/llm-provider-attempt-contract/visualPayload.cjs
index 000000000,1e906aac5..63894fe1a
mode 000000,100644..100644
--- a/packages/llm-provider-attempt-contract/visualPayload.cjs
+++ b/packages/llm-provider-attempt-contract/visualPayload.cjs
@@@ -1,0 -1,225 +1,226 @@@
+ 'use strict'
+
+ /**
+ * Bounded visual-payload validation for codex-completion-request.v2.
+ *
+ * Guarantee, stated narrowly on purpose: this module proves base64
+ * canonicality, byte budgets, JPEG/PNG container framing, required header and
+ * terminator blocks, and the dimensions declared by those headers. It does not
+ * decode pixels, verify PNG CRCs, validate entropy-coded JPEG data, or prove
+ * that the image renders. "Valid" here means "syntactically well-formed
+ * container inside the local budget", never "decoded and visually correct".
+ *
+ * The budget below is a conservative local safety/product decision. It is not
+ * an upstream capability fact; the frozen ChatGPT endpoint is not certified by
+ * these numbers. Codex charges patches, not file bytes: the official client
+ * resizes to 2048 px and sends `detail: high`. A poorly compressed 2048 PNG
+ * can exceed 10 MiB and must still be authorized; an 8192 px / 48 MP image
+ * will 400 upstream even when it is only 2 MiB.
+ *
+ * Two layers share this object:
+ * - typical* is the usual 2048 JPEG/PNG product target (5 / 9 / 14 MiB).
+ * It is documentation and UX guidance, not a reject.
+ * - max* is the hard ceiling: one exceptional 2048 image may be larger
- * than 10 MiB. The V2 HTTP envelope stays 24 MiB so 16 MiB decoded
- * (~21.3 MiB base64) plus the 1 MiB non-image share still fits.
++ * than 10 MiB. The V2 HTTP envelope stays 24 MiB, so 16 MiB decoded
++ * (~21.3 MiB base64) leaves about 2.7 MiB for non-image data; the
++ * 8 MiB non-image cap (#731) applies only when the images are smaller.
+ * Model capability lists (which models accept images) belong to issue #654 /
+ * PR #669 (models.dev). This package only bounds Codex transport.
+ */
+
+ const VISUAL_LIMITS = Object.freeze({
+ maxImages: 20,
+ typicalImageBytes: 5242880,
+ typicalTotalImageBytes: 9437184,
+ typicalEnvelopeBytes: 14680064,
+ maxImageBytes: 16777216,
+ maxTotalImageBytes: 16777216,
+ maxImageDimension: 2048,
+ maxImagePixels: 4194304,
+ })
+
+ // Exact encoded length of a canonical base64 string that decodes to
+ // maxImageBytes octets. Compared before any decoding work happens.
+ const MAX_ENCODED_IMAGE_BYTES = 4 * Math.ceil(VISUAL_LIMITS.maxImageBytes / 3)
+
+ const BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/
+ const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+ const PNG_IHDR = 'IHDR'
+ const PNG_IDAT = 'IDAT'
+ const PNG_IEND = 'IEND'
+
+ // SOF0..SOF15 except DHT (0xC4), JPG (0xC8) and DAC (0xCC), which reuse the
+ // same marker range without carrying frame dimensions.
+ const JPEG_SOF_MARKERS = new Set([
+ 0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+ ])
+ const JPEG_SOI = 0xd8
+ const JPEG_EOI = 0xd9
+ const JPEG_SOS = 0xda
+ const JPEG_TEM = 0x01
+
+ function fail(code, message, kind) {
+ return kind ? { ok: false, code, message, kind } : { ok: false, code, message }
+ }
+
+ function ok(value) {
+ return { ok: true, value }
+ }
+
+ /**
+ * Strict canonical base64. Length is bounded before `Buffer.from`, invalid
+ * alphabets and padding placement are rejected, and a decode/encode round trip
+ * rejects non-canonical trailing bits that a lenient decoder would accept.
+ */
+ function decodeStrictBase64(data, maxDecodedBytes) {
+ if (typeof data !== 'string') return fail('invalid', 'image data must be a base64 string')
+ if (data.length === 0) return fail('invalid', 'image data must not be empty')
+ if (data.length > MAX_ENCODED_IMAGE_BYTES) {
+ return fail('limit', `image exceeds ${maxDecodedBytes} decoded bytes`, 'size')
+ }
+ if (data.length % 4 !== 0) return fail('invalid', 'image data must be canonical base64')
+ if (!BASE64_PATTERN.test(data)) return fail('invalid', 'image data must be canonical base64')
+ const bytes = Buffer.from(data, 'base64')
+ if (bytes.length === 0) return fail('invalid', 'image data must not be empty')
+ if (bytes.length > maxDecodedBytes) {
+ return fail('limit', `image exceeds ${maxDecodedBytes} decoded bytes`, 'size')
+ }
+ if (bytes.toString('base64') !== data) {
+ return fail('invalid', 'image data must be canonical base64')
+ }
+ return ok(bytes)
+ }
+
+ function readPngDimensions(buffer) {
+ const length = buffer.length
+ if (length < 8 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+ return fail('invalid', 'PNG signature is missing')
+ }
+ let pos = 8
+ let header = null
+ let sawImageData = false
+ let sawEnd = false
+ while (pos < length) {
+ if (pos + 8 > length) return fail('invalid', 'PNG chunk header is truncated')
+ const chunkLength = buffer.readUInt32BE(pos)
+ const type = buffer.toString('latin1', pos + 4, pos + 8)
+ if (pos + 12 + chunkLength > length) return fail('invalid', 'PNG chunk is truncated')
+ if (header === null) {
+ if (type !== PNG_IHDR || chunkLength !== 13) {
+ return fail('invalid', 'PNG first chunk must be a 13-byte IHDR')
+ }
+ const width = buffer.readUInt32BE(pos + 8)
+ const height = buffer.readUInt32BE(pos + 12)
+ if (width < 1 || height < 1) return fail('invalid', 'PNG dimensions must be positive')
+ header = { width, height }
+ } else if (type === PNG_IHDR) {
+ return fail('invalid', 'PNG repeats IHDR')
+ }
+ if (type === PNG_IDAT) sawImageData = true
+ if (type === PNG_IEND) {
+ if (chunkLength !== 0) return fail('invalid', 'PNG IEND must be empty')
+ if (pos + 12 !== length) return fail('invalid', 'PNG IEND must be the last chunk')
+ sawEnd = true
+ break
+ }
+ pos += 12 + chunkLength
+ }
+ // IHDR alone (or signature-only) is header-only pretending: the container
+ // must also carry image data and terminate.
+ if (header === null) return fail('invalid', 'PNG has no IHDR')
+ if (!sawImageData) return fail('invalid', 'PNG has no IDAT image data')
+ if (!sawEnd) return fail('invalid', 'PNG has no IEND terminator')
+ return ok(header)
+ }
+
+ function readJpegDimensions(buffer) {
+ const length = buffer.length
+ if (length < 4 || buffer[0] !== 0xff || buffer[1] !== JPEG_SOI) {
+ return fail('invalid', 'JPEG SOI marker is missing')
+ }
+ if (buffer[length - 2] !== 0xff || buffer[length - 1] !== JPEG_EOI) {
+ return fail('invalid', 'JPEG EOI marker is missing')
+ }
+ let pos = 2
+ let frame = null
+ let scanEnd = -1
+ while (pos < length) {
+ if (buffer[pos] !== 0xff) return fail('invalid', 'JPEG marker framing is malformed')
+ while (pos < length && buffer[pos] === 0xff) pos += 1
+ if (pos >= length) return fail('invalid', 'JPEG marker is truncated')
+ const marker = buffer[pos]
+ pos += 1
+ if (marker === 0x00) return fail('invalid', 'JPEG marker framing is malformed')
+ if (marker === JPEG_EOI) break
+ if (marker === JPEG_SOI) return fail('invalid', 'JPEG repeats SOI')
+ if (marker === JPEG_TEM || (marker >= 0xd0 && marker <= 0xd7)) continue
+ if (pos + 2 > length) return fail('invalid', 'JPEG segment length is truncated')
+ const segmentLength = buffer.readUInt16BE(pos)
+ if (segmentLength < 2 || pos + segmentLength > length) {
+ return fail('invalid', 'JPEG segment is truncated')
+ }
+ if (JPEG_SOF_MARKERS.has(marker)) {
+ if (segmentLength < 8) return fail('invalid', 'JPEG frame header is truncated')
+ const height = buffer.readUInt16BE(pos + 3)
+ const width = buffer.readUInt16BE(pos + 5)
+ if (width < 1 || height < 1) return fail('invalid', 'JPEG dimensions must be positive')
+ frame = { width, height }
+ }
+ if (marker === JPEG_SOS) {
+ scanEnd = pos + segmentLength
+ break
+ }
+ pos += segmentLength
+ }
+ // Frame header plus scan header plus at least one entropy-coded byte: a
+ // header-only file must not pass as an image.
+ if (frame === null) return fail('invalid', 'JPEG has no frame header')
+ if (scanEnd < 0) return fail('invalid', 'JPEG has no start-of-scan segment')
+ if (scanEnd >= length - 2) return fail('invalid', 'JPEG has no entropy-coded image data')
+ return ok(frame)
+ }
+
+ function assertWithinDimensionBudget(dimensions) {
+ if (
+ dimensions.width > VISUAL_LIMITS.maxImageDimension ||
+ dimensions.height > VISUAL_LIMITS.maxImageDimension
+ ) {
+ return fail('limit', `image dimension exceeds ${VISUAL_LIMITS.maxImageDimension}`, 'size')
+ }
+ if (dimensions.width * dimensions.height > VISUAL_LIMITS.maxImagePixels) {
+ return fail('limit', `image pixel count exceeds ${VISUAL_LIMITS.maxImagePixels}`, 'size')
+ }
+ return null
+ }
+
+ /**
+ * Per-image gate: MIME, strict base64, octet budget, container framing and
+ * dimension/pixel budget. Aggregate image count and total bytes stay with the
+ * caller because they span the complete request, including history messages.
+ */
+ function inspectVisualImage(input) {
+ if (input.mimeType !== 'image/jpeg' && input.mimeType !== 'image/png') {
+ return fail('invalid', 'image mimeType is not allowed')
+ }
+ const decoded = decodeStrictBase64(input.data, VISUAL_LIMITS.maxImageBytes)
+ if (!decoded.ok) return decoded
+ const dimensions =
+ input.mimeType === 'image/png'
+ ? readPngDimensions(decoded.value)
+ : readJpegDimensions(decoded.value)
+ if (!dimensions.ok) return dimensions
+ const budget = assertWithinDimensionBudget(dimensions.value)
+ if (budget) return budget
+ return ok({
+ bytes: decoded.value.length,
+ width: dimensions.value.width,
+ height: dimensions.value.height,
+ })
+ }
+
+ module.exports = {
+ VISUAL_LIMITS,
+ MAX_ENCODED_IMAGE_BYTES,
+ decodeStrictBase64,
+ inspectVisualImage,
+ }
diff --cc tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json
index f4b8ced51,03c3997e4..f12aa32ed
--- a/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json
+++ b/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json
@@@ -40,7 -40,8 +40,8 @@@
},
"oauthScopes": ["openid", "profile", "email", "offline_access"],
"limits": {
- "maxRequestBodyBytes": 1048576,
+ "maxRequestBodyBytes": 8388608,
+ "maxVisualRequestBodyBytes": 25165824,
"maxMessages": 1024,
"maxToolCalls": 256,
"maxOutputTokens": 16384,
@@@ -61,9 -62,9 +62,11 @@@
"ticket_invalid",
"ticket_replayed",
"request_hash_mismatch",
+ "image_source_invalid",
+ "payload_too_large",
- "tool_call_limit_exceeded"
+ "tool_call_limit_exceeded",
+ "context_length_exceeded",
+ "invalid_tool_arguments"
],
"termsAndTestAccount": {
"automationAuthorized": true,
diff --cc tests/e2e/fixtures/package-lock.json
index 87f7ab185,3a9bac504..78c5189ed
--- a/tests/e2e/fixtures/package-lock.json
+++ b/tests/e2e/fixtures/package-lock.json
@@@ -1,12 -1,12 +1,12 @@@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.91",
- "version": "1.0.90",
++ "version": "1.0.92",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.91",
- "version": "1.0.90",
++ "version": "1.0.92",
"dependencies": {
"@kubernetes/client-node": "^1.0.0"
},
diff --cc tests/e2e/fixtures/package.json
index db0b424af,91a0be7f9..aa7639ef1
--- a/tests/e2e/fixtures/package.json
+++ b/tests/e2e/fixtures/package.json
@@@ -1,6 -1,6 +1,6 @@@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.91",
- "version": "1.0.90",
++ "version": "1.0.92",
"description": "E2E test fixtures and utilities for Clerum testing",
"type": "module",
"main": "index.ts",
diff --cc tests/e2e/integration/codex-subscription-contract-freeze.test.ts
index da779300e,c975fb76b..f02bdd14d
--- a/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
+++ b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
@@@ -85,6 -103,41 +103,45 @@@ function collectSensitiveLeaves(value:
}
describe('codex-subscription contract freeze', () => {
+ it('freezes V2 local budgets without asserting upstream image support', () => {
+ const fixture = JSON.parse(readFileSync(fixturePath, 'utf8'))
+ const localContract = createRequire(import.meta.url)(
+ join(repoRoot, 'packages/llm-provider-attempt-contract/index.cjs')
+ )
+ expect(fixture.protocolVersion).toBe('codex-subscription-transport.v1')
+ expect(fixture.requestSchemas).toEqual([
+ localContract.SCHEMA_VERSION,
+ localContract.SCHEMA_VERSION_V2,
+ ])
+ expect(fixture.visualInput.limits).toEqual(localContract.VISUAL_LIMITS)
+ expect(fixture.visualInput.enabledByDefault).toBe(true)
+ expect(fixture.visualInput.upstreamVerified).toBe(false)
+ expect(fixture.visualInput.activation).toBe('default')
+ const architecture = readFileSync(architectureDocPath, 'utf8')
+ expect(architecture).toContain('codex-completion-request.v2')
+ expect(architecture).not.toContain('CODEX_IMAGE_INPUT_MODELS')
+ const proxyDeploy = readFileSync(
+ join(repoRoot, 'deploy/base/control-plane/codex-llm-proxy.yaml'),
+ 'utf8'
+ )
- expect(proxyDeploy).toContain(
- `CODEX_LLM_PROXY_MAX_BODY_BYTES: "${localContract.LIMITS.maxRequestBodyBytes}"`
++ // #731: the ordinary body limit is left unset in the manifest so the proxy
++ // derives it from the contract cap plus its envelope allowance.
++ expect(proxyDeploy).not.toMatch(/^\s*CODEX_LLM_PROXY_MAX_BODY_BYTES:/m)
++ const proxyLimits = readFileSync(join(repoRoot, 'codex-llm-proxy/src/requestLimits.ts'), 'utf8')
++ expect(proxyLimits).toMatch(
++ /DEFAULT_MAX_BODY_BYTES = CONTRACT_LIMITS\.maxRequestBodyBytes \+ ENVELOPE_ALLOWANCE_BYTES/
+ )
+ expect(proxyDeploy).toContain(
+ `CODEX_LLM_PROXY_MAX_VISUAL_BODY_BYTES: "${localContract.LIMITS.maxVisualRequestBodyBytes}"`
+ )
+ expect(proxyDeploy).not.toMatch(/CODEX_IMAGE_INPUT_MODELS/)
+ const hostConfig = readFileSync(join(repoRoot, 'mcp-host/src/config.ts'), 'utf8')
+ const proxyConfig = readFileSync(join(repoRoot, 'codex-llm-proxy/src/config.ts'), 'utf8')
+ expect(hostConfig).not.toMatch(/CODEX_IMAGE_INPUT_MODELS/)
+ expect(proxyConfig).not.toMatch(/CODEX_IMAGE_INPUT_MODELS/)
+ expect(architecture).toContain('on by default for every `codex-subscription` model')
+ })
+
it('requires the sanitized fixture and both freeze documents', () => {
expect(existsSync(fixturePath), `missing fixture: ${fixturePath}`).toBe(true)
expect(
@@@ -156,7 -209,8 +213,8 @@@
expect(limits).not.toHaveProperty('maxTools')
expect(limits?.maxToolCalls).toBe(256)
expect(limits?.maxMessages).toBe(1024)
- expect(limits?.maxRequestBodyBytes).toBe(1048576)
+ expect(limits?.maxRequestBodyBytes).toBe(8388608)
+ expect(limits?.maxVisualRequestBodyBytes).toBe(25165824)
const errors = contract.errorTaxonomy
expect(Array.isArray(errors) && (errors as unknown[]).length > 0).toBe(true)