Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { describe, expect, it, vi } from 'vitest'
import {
LIMITS,
VISUAL_LIMITS,
buildCodexProxyEnvelope,
hashCodexCompletionRequest,
parseCodexCompletionRequest,
} from '@clerum/llm-provider-attempt-contract'
import { LlmErrorCode } from '../../core/errors'
import {
CodexLlmProxyClient,
CodexProxyError,
codexProxyErrorMessage,
resolveCodexProxyRuntimeUrl,
} from '../codexLlmProxyClient'
import { CodexSubscriptionProvider } from '../codexSubscription'
import { classifyFailoverClass } from '../failover/classify'
import { CodexAuthorizeError } from '../providerAttemptAuthorizer'
import { PNG_2X2_BASE64 } from './codexImageFixtures'
import { closedPortUrl, fetchFailure, silentServer } from './connectFailureFixtures'
function sse(frames: unknown[]): ReadableStream<Uint8Array> {
const encoder = new TextEncoder()
const payload = frames.map(frame => `data: ${JSON.stringify(frame)}\n\n`).join('')
return new ReadableStream({
start(controller) {
controller.enqueue(encoder.encode(payload))
controller.close()
},
})
}
// A well-formed V2 request with one image, authorized under its own hash.
function codexVisualInput() {
const parsed = parseCodexCompletionRequest({
schemaVersion: 'codex-completion-request.v2',
requestId: 'req-visual',
idempotencyKey: 'idem-visual',
provider: 'codex-subscription',
model: 'gpt-5.1',
deadlineMs: 1000,
messages: [
{
role: 'user',
content: 'Describe the attached image',
contentParts: [
{ type: 'text', text: 'Describe the attached image' },
{
type: 'image',
mimeType: 'image/png',
data: PNG_2X2_BASE64,
source: { kind: 'attachment', attachmentId: 'att-1', messageId: 'msg-1' },
},
],
},
],
})
if (!parsed.ok) throw new Error(parsed.message)
return {
request: parsed.value,
requestHash: hashCodexCompletionRequest(parsed.value),
executionTicket: 'fixture-ticket',
}
}
type CodexVisualInput = ReturnType<typeof codexVisualInput>
/** The fixture's single user message, with its parts. */
function codexVisualMessage(input: CodexVisualInput) {
const [message] = input.request.messages
if (!message || !('contentParts' in message) || !message.contentParts) {
throw new Error('fixture message has no contentParts')
}
return { ...message, contentParts: message.contentParts }
}
describe('CodexLlmProxyClient', () => {
it('sends the exact measured V2 envelope and refuses an independent deadline or hash', async () => {
const parsed = parseCodexCompletionRequest({
schemaVersion: 'codex-completion-request.v2',
requestId: 'req-visual',
idempotencyKey: 'idem-visual',
provider: 'codex-subscription',
model: 'gpt-5.1',
deadlineMs: 1000,
messages: [
{
role: 'user',
content: 'image redacted',
contentParts: [{ type: 'text', text: 'image redacted' }],
},
],
})
if (!parsed.ok) throw new Error(parsed.message)
const input = {
request: parsed.value,
requestHash: hashCodexCompletionRequest(parsed.value),
executionTicket: 'fixture-ticket',
}
const measured = buildCodexProxyEnvelope(input)
if (!measured.ok) throw new Error(measured.message)
const fetchFn = vi.fn<typeof fetch>(
async () => new Response(sse([{ type: 'done', outcome: 'success' }]))
)
const client = new CodexLlmProxyClient({
runtimeUrl: 'http://proxy/completions',
readPlatformJwt: () => 'fixture-only',
fetchFn,
})
await client.stream({ ...input, deadlineMs: 1000 })
expect(JSON.parse(String(fetchFn.mock.calls[0]?.[1]?.body))).toEqual(measured.value)
expect(measured.value).not.toHaveProperty('deadlineMs')
await expect(client.stream({ ...input, deadlineMs: 2000 })).rejects.toMatchObject({
code: 'invalid_request',
dispatched: false,
})
await expect(client.stream({ ...input, requestHash: 'a'.repeat(64) })).rejects.toMatchObject({
code: 'request_hash_mismatch',
dispatched: false,
})
expect(fetchFn).toHaveBeenCalledOnce()
})
// Review R4-L6: the pre-dispatch refusals use the providers' canonical
// mapping, so a conversation over the non-image budget is a context-length
// refusal and an image count is not a size refusal.
it.each([
[
'text over the non-image budget',
(input: CodexVisualInput) => {
const message = codexVisualMessage(input)
const text = 'x'.repeat(LIMITS.maxRequestBodyBytes)
const parts = message.contentParts.map(part =>
part.type === 'text' ? { ...part, text } : part
)
return {
...input,
request: {
...input.request,
messages: [{ ...message, content: text, contentParts: parts }],
},
}
},
{
code: 'request_limit_exceeded',
message: 'request exceeds maxRequestBodyBytes outside image data',
},
],
[
'more images than the contract allows',
(input: CodexVisualInput) => {
const message = codexVisualMessage(input)
const image = message.contentParts.find(part => part.type === 'image')
if (!image) throw new Error('fixture has no image part')
const images = Array.from({ length: VISUAL_LIMITS.maxImages + 1 }, (_, i) => ({
...image,
source: { kind: 'attachment' as const, attachmentId: `att-${i}`, messageId: 'msg-1' },
}))
const contentParts = [{ type: 'text' as const, text: message.content }, ...images]
return {
...input,
request: { ...input.request, messages: [{ ...message, contentParts }] },
}
},
{ code: 'invalid_request', message: `request exceeds ${VISUAL_LIMITS.maxImages} images` },
],
[
'an envelope over the visual ceiling',
(input: CodexVisualInput) => ({
...input,
executionTicket: 't'.repeat(LIMITS.maxVisualRequestBodyBytes),
}),
{ code: 'payload_too_large', message: 'proxy envelope exceeds maxVisualRequestBodyBytes' },
],
])('R4-L6 refuses %s before the proxy hop', async (_label, mutate, expected) => {
const fetchFn = vi.fn<typeof fetch>(
async () => new Response(sse([{ type: 'done', outcome: 'success' }]))
)
const client = new CodexLlmProxyClient({
runtimeUrl: 'http://proxy/completions',
readPlatformJwt: () => 'fixture-only',
fetchFn,
})
const input = codexVisualInput()
await expect(client.stream(mutate(input))).rejects.toMatchObject({
...expected,
dispatched: false,
})
expect(fetchFn).not.toHaveBeenCalled()
// Witness: the unmodified request reaches the proxy.
await client.stream(input)
expect(fetchFn).toHaveBeenCalledOnce()
})
it.each(['html', 'json'])(
'keeps a %s 413 terminal rather than treating it as unavailable',
async format => {
const fetchFn = vi.fn(
async () =>
new Response(
format === 'html'
? '<h1>Too large</h1>'
: JSON.stringify({ error: 'payload_too_large' }),
{ status: 413 }
)
)
const client = new CodexLlmProxyClient({
runtimeUrl: 'http://proxy/internal/runtime/v1/codex/completions',
readPlatformJwt: () => 'test-jwt',
fetchFn,
})
await expect(
client.stream({ executionTicket: 'test-ticket', requestHash: 'a'.repeat(64), request: {} })
).rejects.toMatchObject({ code: 'payload_too_large', dispatched: true })
expect(fetchFn).toHaveBeenCalledOnce()
}
)
it('streams to the frozen runtime Service URL and never accepts a caller URL', async () => {
const fetchFn = vi.fn().mockResolvedValue({
ok: true,
body: sse([
{ type: 'text', text: 'hello' },
{ type: 'tool_call', id: 'c1', name: 'echo', arguments: { x: 1 } },
{ type: 'done', outcome: 'success' },
]),
})
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 result = await client.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: { model: 'gpt-5.3-codex' },
// Not part of the input type: a caller must not be able to redirect the hop.
url: 'https://attacker.example/backend-api/codex/responses',
runtimeUrl: 'https://attacker.example/internal/runtime/v1/codex/completions',
} as never)
expect(fetchFn).toHaveBeenCalledTimes(1)
expect(fetchFn.mock.calls[0][0]).toBe(
'http://codex-llm-proxy.control-plane.svc.cluster.local:8080/internal/runtime/v1/codex/completions'
)
const sent = JSON.parse(fetchFn.mock.calls[0][1].body)
expect(Object.keys(sent).sort()).toEqual(['executionTicket', 'request', 'requestHash'])
expect(JSON.stringify(sent)).not.toContain('attacker.example')
expect(result.text).toBe('hello')
expect(result.toolCalls).toEqual([
{ type: 'tool_call', id: 'c1', name: 'echo', arguments: { x: 1 } },
])
})
// The proxy reports the tool-call limit on two wire paths: a 422 JSON body
// before any stream frame, or an SSE error frame after one. Both must reach
// the provider classifier with the proxy's code intact.
it.each([
{
path: '422 JSON body before streaming',
response: {
ok: false,
status: 422,
json: async () => ({ error: 'tool_call_limit_exceeded' }),
},
message: 'proxy stream failed with 422 (tool_call_limit_exceeded)',
},
{
path: 'SSE error frame after a text frame',
response: {
ok: true,
body: sse([
{ type: 'text', text: 'partial' },
{ type: 'error', code: 'tool_call_limit_exceeded' },
]),
},
message: 'proxy stream failed with tool_call_limit_exceeded',
},
])('surfaces tool_call_limit_exceeded from the $path', 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: 'tool_call_limit_exceeded', message })
const classified = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never).classifyError(
err
)
expect(classified.code).toBe(LlmErrorCode.ToolCallLimitExceeded)
expect(classified.retryable).toBe(false)
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: '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()
}
)
// T-MB-5 — the proxy answers `408 { error: 'request_timeout' }` when the
// body upload overruns its read deadline. The body never reached the
// upstream, so this is not an outage: it must not enter failover cooldown.
it('T-MB-5a classifies the proxy 408 request_timeout as a non-retryable ApiCallFailed', async () => {
const fetchFn = vi.fn(async () => Response.json({ error: 'request_timeout' }, { status: 408 }))
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: 'request_timeout',
message: 'proxy stream failed with 408 (request_timeout)',
})
const classified = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never).classifyError(
err
)
expect(classified).toMatchObject({
code: LlmErrorCode.ApiCallFailed,
retryable: false,
providerCode: 'request_timeout',
})
expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
})
it.each(['visual_host_share', 'visual_gate', 'proxy_capacity_exceeded'] as const)(
'decodes the local %s admission code without failover and keeps the client usable',
async code => {
const input = {
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
}
const fetchFn = vi
.fn()
.mockResolvedValueOnce(
Response.json({ error: code, reason: 'untrusted upstream prose' }, { status: 503 })
)
.mockResolvedValueOnce(new Response(sse([{ type: 'done', outcome: 'success' }])))
const client = new CodexLlmProxyClient({
runtimeUrl: 'http://proxy/internal/runtime/v1/codex/completions',
readPlatformJwt: () => 'platform-jwt',
fetchFn,
})
const err = await client.stream(input).then(
() => undefined,
(e: unknown) => e
)
expect(fetchFn).toHaveBeenCalledTimes(1)
expect(err).toBeInstanceOf(CodexProxyError)
if (!(err instanceof CodexProxyError)) throw new Error('expected CodexProxyError')
expect(err).toMatchObject({
code,
message: codexProxyErrorMessage(code, 503),
dispatched: true,
})
expect(err.message).not.toContain('untrusted upstream prose')
const provider = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never)
const classified = provider.classifyError(err)
expect(classified.code).toBe(LlmErrorCode.ApiCallFailed)
expect(classified.retryable).toBe(false)
expect(classified.providerCode).toBe(code)
expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
const next = await client.stream(input)
expect(next.outcome).toBe('success')
expect(fetchFn).toHaveBeenCalledTimes(2)
const outage = provider.classifyError(
new CodexProxyError('provider_unavailable', 'real upstream outage')
)
expect(outage.code).toBe(LlmErrorCode.ModelOverloaded)
expect(outage.retryable).toBe(true)
expect(classifyFailoverClass(outage.code, outage.retryable)).toBe('provider_unavailable')
}
)
it.each([
[
'unknown_machine_code',
JSON.stringify({ error: 'future_proxy_error' }),
LlmErrorCode.ApiCallFailed,
false,
'future_proxy_error',
],
[
'reason_only',
JSON.stringify({ reason: 'visual_gate' }),
LlmErrorCode.ModelOverloaded,
true,
'provider_unavailable',
],
['malformed_json', '{', LlmErrorCode.ModelOverloaded, true, 'provider_unavailable'],
] as const)(
'keeps wire %s separate from trusted local refusal provenance',
async (_label, body, code, retryable, providerCode) => {
const fetchFn = vi
.fn()
.mockResolvedValue(
new Response(body, { status: 503, headers: { 'content-type': 'application/json' } })
)
const proxy = new CodexLlmProxyClient({
runtimeUrl: 'http://proxy/internal/runtime/v1/codex/completions',
readPlatformJwt: () => 'platform-jwt',
fetchFn,
})
const error = await proxy
.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
})
.then(
() => undefined,
(caught: unknown) => caught
)
expect(error).toBeInstanceOf(CodexProxyError)
expect(fetchFn).toHaveBeenCalledTimes(1)
const provider = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never)
const classified = provider.classifyError(error)
expect(classified).toMatchObject({ code, retryable, providerCode })
expect(classifyFailoverClass(classified.code, classified.retryable)).toBe(
retryable ? 'provider_unavailable' : null
)
}
)
// T-TE-1 (D4) — the proxy passes control-api's redeem refusal through as
// `403 { error: 'ticket_expired' }` when the ticket died while the request
// was queued. Nothing reached the provider, so a re-authorized retry is the
// remedy. `ticket_replayed` / `ticket_invalid` are defects and stay terminal.
it.each([
{ error: 'ticket_expired', status: 403, retryable: true, failover: 'provider_unavailable' },
{ error: 'ticket_replayed', status: 409, retryable: false, failover: null },
{ error: 'ticket_invalid', status: 403, retryable: false, failover: null },
] as const)(
'T-TE-1a classifies the proxy $status $error as ApiCallFailed with retryable=$retryable',
async ({ error, status, retryable, failover }) => {
const fetchFn = vi.fn(async () => Response.json({ error }, { status }))
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: error,
message: `proxy stream failed with ${status} (${error})`,
dispatched: true,
})
const classified = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never).classifyError(
err
)
expect(classified).toMatchObject({
code: LlmErrorCode.ApiCallFailed,
retryable,
providerCode: error,
})
expect(classifyFailoverClass(classified.code, classified.retryable)).toBe(failover)
}
)
// The proxy's total stream cap arrives as 504 before any frame, or as an SSE
// error frame after one. The attempt spent its whole budget, so the same
// request would spend it again elsewhere: no retry, no failover.
it.each([
{
path: '504 JSON body before streaming',
response: {
ok: false,
status: 504,
json: async () => ({ error: 'stream_duration_exceeded' }),
},
message: 'proxy stream failed with 504 (stream_duration_exceeded)',
},
{
path: 'SSE error frame after a text frame',
response: {
ok: true,
body: sse([
{ type: 'text', text: 'partial' },
{ type: 'error', code: 'stream_duration_exceeded' },
]),
},
message: 'proxy stream failed with stream_duration_exceeded',
},
])('surfaces stream_duration_exceeded from the $path', 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: 'stream_duration_exceeded', message })
const provider = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never)
const classified = provider.classifyError(err)
expect(classified.code).toBe(LlmErrorCode.StreamDurationExceeded)
expect(classified.retryable).toBe(false)
expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
// Witness: the idle cut is an outage on the same classifier and does fail over.
const idle = provider.classifyError(
new CodexProxyError(
'provider_unavailable',
'proxy stream failed with 503 (provider_unavailable)'
)
)
expect(classifyFailoverClass(idle.code, idle.retryable)).toBe('provider_unavailable')
})
// The proxy writes `: keepalive` SSE comments while the upstream is silent,
// before and between data frames, and a comment can straddle two reads.
it('ignores proxy keepalive comments around and between data frames', async () => {
const encoder = new TextEncoder()
const chunks = [
': keepalive\n\n: keep',
'alive\n\n',
'data: {"type":"text","text":"hel"}\n\n: keepalive\n\n',
'data: {"type":"text","text":"lo"}\n\n',
': keepalive\n\ndata: {"type":"done","outcome":"success"}\n\n',
]
const fetchFn = vi.fn().mockResolvedValue({
ok: true,
body: new ReadableStream<Uint8Array>({
start(controller) {
for (const chunk of chunks) controller.enqueue(encoder.encode(chunk))
controller.close()
},
}),
})
const client = new CodexLlmProxyClient({
runtimeUrl: resolveCodexProxyRuntimeUrl('http://codex-llm-proxy:8080'),
readPlatformJwt: () => 'platform-jwt',
fetchFn: fetchFn as unknown as typeof fetch,
})
const result = await client.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: { model: 'gpt-5.3-codex' },
})
expect(result.text).toBe('hello')
expect(result.toolCalls).toEqual([])
expect(result.outcome).toBe('success')
})
it('refuses a runtime URL that is not absolute', () => {
expect(
() =>
new CodexLlmProxyClient({
runtimeUrl: '/internal/runtime/v1/codex/completions',
readPlatformJwt: () => 'platform-jwt',
})
).toThrow(/absolute server-owned URL/)
})
it('fails closed when aborted before the proxy hop', async () => {
const client = new CodexLlmProxyClient({
runtimeUrl:
'http://codex-llm-proxy.control-plane.svc.cluster.local:8080/internal/runtime/v1/codex/completions',
readPlatformJwt: () => 'platform-jwt',
fetchFn: vi.fn() as unknown as typeof fetch,
})
const signal = AbortSignal.abort()
await expect(
client.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
signal,
})
).rejects.toMatchObject({ code: 'canceled' })
expect(client['options'].fetchFn).not.toHaveBeenCalled()
})
it('surfaces the proxy error code with the HTTP status', async () => {
const client = new CodexLlmProxyClient({
runtimeUrl: resolveCodexProxyRuntimeUrl(
'http://codex-llm-proxy.control-plane.svc.cluster.local:8080'
),
readPlatformJwt: () => 'platform-jwt',
fetchFn: vi.fn().mockResolvedValue({
ok: false,
status: 403,
json: async () => ({ error: 'origin_denied' }),
}) as unknown as typeof fetch,
})
await expect(
client.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
})
).rejects.toMatchObject({
code: 'origin_denied',
message: 'proxy stream failed with 403 (origin_denied)',
})
})
it('refreshes the platform JWT once and retries the proxy hop after HTTP 401', async () => {
let jwt = 'stale-jwt'
const refreshOnUnauthorized = vi.fn(async () => {
jwt = 'fresh-jwt'
})
const fetchFn = vi
.fn()
.mockResolvedValueOnce({
ok: false,
status: 401,
json: async () => ({ error: 'Unauthorized' }),
})
.mockResolvedValueOnce({
ok: true,
body: sse([
{ type: 'text', text: 'ok' },
{ type: 'done', outcome: 'success' },
]),
})
const client = new CodexLlmProxyClient({
runtimeUrl: resolveCodexProxyRuntimeUrl(
'http://codex-llm-proxy.control-plane.svc.cluster.local:8080'
),
readPlatformJwt: () => jwt,
refreshOnUnauthorized,
fetchFn: fetchFn as unknown as typeof fetch,
})
const result = await client.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
})
expect(refreshOnUnauthorized).toHaveBeenCalledTimes(1)
expect(fetchFn).toHaveBeenCalledTimes(2)
expect(fetchFn.mock.calls[0][1].headers.authorization).toBe('Bearer stale-jwt')
expect(fetchFn.mock.calls[1][1].headers.authorization).toBe('Bearer fresh-jwt')
expect(result.text).toBe('ok')
})
it('fails closed when the proxy emits an SSE error frame after headers', async () => {
const client = new CodexLlmProxyClient({
runtimeUrl: resolveCodexProxyRuntimeUrl(
'http://codex-llm-proxy.control-plane.svc.cluster.local:8080'
),
readPlatformJwt: () => 'platform-jwt',
fetchFn: vi.fn().mockResolvedValue({
ok: true,
body: sse([{ type: 'error', code: 'origin_denied' }]),
}) as unknown as typeof fetch,
})
await expect(
client.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
})
).rejects.toMatchObject({ code: 'origin_denied' })
})
it('marks only the pre-stream abort as never dispatched', async () => {
const runtimeUrl = resolveCodexProxyRuntimeUrl(
'http://codex-llm-proxy.control-plane.svc.cluster.local:8080'
)
const abortedClient = new CodexLlmProxyClient({
runtimeUrl,
readPlatformJwt: () => 'platform-jwt',
fetchFn: vi.fn() as unknown as typeof fetch,
})
await expect(
abortedClient.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
signal: AbortSignal.abort(),
})
).rejects.toMatchObject({ code: 'canceled', dispatched: false })
// The request left the process before control-api answered, so a denial is
// not proof that nothing was billed.
const deniedClient = new CodexLlmProxyClient({
runtimeUrl,
readPlatformJwt: () => 'platform-jwt',
fetchFn: vi.fn().mockResolvedValue({
ok: false,
status: 403,
json: async () => ({ error: 'origin_denied' }),
}) as unknown as typeof fetch,
})
await expect(
deniedClient.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
})
).rejects.toMatchObject({ code: 'origin_denied', dispatched: true })
// An error frame arrives mid-stream: the upstream call is already running.
const framedClient = new CodexLlmProxyClient({
runtimeUrl,
readPlatformJwt: () => 'platform-jwt',
fetchFn: vi.fn().mockResolvedValue({
ok: true,
body: sse([{ type: 'error', code: 'rate_limited' }]),
}) as unknown as typeof fetch,
})
await expect(
framedClient.stream({
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
})
).rejects.toMatchObject({ code: 'rate_limited', dispatched: true })
})
})
// G1-6 (#720): a 429 is a rate limit, whether or not its body carries JSON,
// and its `Retry-After` (delta-seconds 1..3600) travels on the error.
describe('CodexLlmProxyClient rate limits', () => {
const INPUT = {
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
}
async function failure(response: Response) {
const fetchFn = vi.fn<typeof fetch>(async () => response)
const client = new CodexLlmProxyClient({
runtimeUrl: 'http://proxy/completions',
readPlatformJwt: () => 'platform-jwt',
fetchFn,
})
const err = await client.stream(INPUT).then(
() => undefined,
(e: unknown) => e
)
return { err, fetchFn }
}
it('G1-6a reads a 429 with no JSON code as rate_limited with its Retry-After', async () => {
const { err, fetchFn } = await failure(
new Response('<html><body>Too Many Requests</body></html>', {
status: 429,
headers: { 'content-type': 'text/html', 'retry-after': '7' },
})
)
// Liveness witness: the proxy hop ran and got the 429.
expect(fetchFn).toHaveBeenCalledTimes(1)
expect(err).toBeInstanceOf(CodexProxyError)
expect(err).toMatchObject({ code: 'rate_limited', retryAfterMs: 7000 })
})
it('G1-6b carries the Retry-After of a JSON rate_limited reply', async () => {
const { err, fetchFn } = await failure(
Response.json({ error: 'rate_limited' }, { status: 429, headers: { 'retry-after': '2' } })
)
expect(fetchFn).toHaveBeenCalledTimes(1)
expect(err).toMatchObject({ code: 'rate_limited', retryAfterMs: 2000 })
})
it.each(['0', '3601', 'soon', '1.5', 'Wed, 21 Oct 2026 07:28:00 GMT', ''])(
'G1-6c drops the Retry-After value %j instead of guessing',
async value => {
const { err, fetchFn } = await failure(
Response.json({ error: 'rate_limited' }, { status: 429, headers: { 'retry-after': value } })
)
expect(fetchFn).toHaveBeenCalledTimes(1)
expect(err).toMatchObject({ code: 'rate_limited' })
expect((err as CodexProxyError).retryAfterMs).toBeUndefined()
}
)
it('G1-6c keeps the JSON code a 429 carries', async () => {
const { err } = await failure(Response.json({ error: 'budget_denied' }, { status: 429 }))
expect(err).toMatchObject({ code: 'budget_denied' })
})
// G1-11 (#720, review R1-B1): a limiter in the control-api shape answers a
// reason phrase, not a code. On a 429 only a machine code wins.
it('G1-11c reads a 429 whose JSON error is a reason phrase as rate_limited', async () => {
const { err, fetchFn } = await failure(
Response.json(
{ error: 'Too Many Requests', retryAfterSeconds: 4 },
{ status: 429, headers: { 'retry-after': '4' } }
)
)
expect(fetchFn).toHaveBeenCalledTimes(1)
expect(err).toMatchObject({ code: 'rate_limited', retryAfterMs: 4000 })
})
// Review round 2 M7: this pins only that the 429 rule does not fire. Which
// code a non-429 JSON error should get is a separate question.
it('G1-11c does not apply the 429 rule to a non-429 JSON error', async () => {
const { err, fetchFn } = await failure(
Response.json(
{ error: 'Service Unavailable' },
{ status: 503, headers: { 'retry-after': '4' } }
)
)
expect(fetchFn).toHaveBeenCalledTimes(1)
// Witness: the non-ok branch ran and threw the proxy error.
expect(err).toBeInstanceOf(CodexProxyError)
expect((err as CodexProxyError).code).not.toBe('rate_limited')
expect((err as CodexProxyError).retryAfterMs).toBeUndefined()
})
it.each([
['1', 1000],
['3600', 3_600_000],
])('G1-6c carries a Retry-After of exactly %s (review round 2 L7)', async (value, ms) => {
const { err, fetchFn } = await failure(
Response.json({ error: 'rate_limited' }, { status: 429, headers: { 'retry-after': value } })
)
expect(fetchFn).toHaveBeenCalledTimes(1)
expect(err).toMatchObject({ code: 'rate_limited', retryAfterMs: ms })
})
it('G1-6c keeps an HTML 502 as provider_unavailable with no Retry-After', async () => {
const { err, fetchFn } = await failure(
new Response('<html><body>502 Bad Gateway</body></html>', {
status: 502,
headers: { 'content-type': 'text/html', 'retry-after': '5' },
})
)
expect(fetchFn).toHaveBeenCalledTimes(1)
expect(err).toMatchObject({ code: 'provider_unavailable' })
expect((err as CodexProxyError).retryAfterMs).toBeUndefined()
})
})
// G1-7 (#720): a proxy that no live process answered is control_plane_unavailable;
// a failure that may have reached one keeps its current shape.
describe('CodexLlmProxyClient control-plane reachability', () => {
const INPUT = {
executionTicket: 'ticket-123456',
requestHash: 'a'.repeat(64),
request: {},
}
function clientAt(runtimeUrl: string, fetchFn?: typeof fetch): CodexLlmProxyClient {
return new CodexLlmProxyClient({
runtimeUrl: resolveCodexProxyRuntimeUrl(runtimeUrl),
readPlatformJwt: () => 'platform-jwt',
...(fetchFn ? { fetchFn } : {}),
})
}
it('G1-7a reads a refused connection as control_plane_unavailable', async () => {
const url = await closedPortUrl()
// Witness: the platform fetch fails this way against the closed port.
const raw = await fetch(`${url}/probe`).catch((caught: unknown) => caught)
expect(raw).toBeInstanceOf(TypeError)
expect((raw as { cause?: { code?: unknown } }).cause?.code).toBe('ECONNREFUSED')
const err = await clientAt(url)
.stream(INPUT)
.catch((caught: unknown) => caught)
expect(err).toBeInstanceOf(CodexProxyError)
expect(err).toMatchObject({ code: 'control_plane_unavailable' })
expect((err as Error).message).toContain('ECONNREFUSED')
})
it.each(['ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'UND_ERR_CONNECT_TIMEOUT'])(
'G1-7b reads a %s fetch failure as control_plane_unavailable',
async code => {
const fetchFn = vi.fn<typeof fetch>(async () => {
throw fetchFailure(code)
})
await expect(clientAt('http://proxy.invalid', fetchFn).stream(INPUT)).rejects.toMatchObject({
name: 'CodexProxyError',
code: 'control_plane_unavailable',
})
expect(fetchFn).toHaveBeenCalledTimes(1)
}
)
it('G1-7c rethrows a reset connection unchanged', async () => {
const failure = fetchFailure('ECONNRESET')
const fetchFn = vi.fn<typeof fetch>(async () => {
throw failure
})
await expect(clientAt('http://proxy.invalid', fetchFn).stream(INPUT)).rejects.toBe(failure)
expect(fetchFn).toHaveBeenCalledTimes(1)
})
it('G1-7d rejects with the abort reason when the caller aborts a request in flight', async () => {
const server = await silentServer()
try {
const controller = new AbortController()
const reason = new Error('caller gave up')
const pending = clientAt(server.url)
.stream({ ...INPUT, signal: controller.signal })
.catch((caught: unknown) => caught)
// Witness: the request reached a live process before the abort.
await server.received
controller.abort(reason)
expect(await pending).toBe(reason)
} finally {
await server.close()
}
})
it('G1-7d rethrows a connect-phase code unchanged once the caller aborted', async () => {
const controller = new AbortController()
const failure = fetchFailure('ECONNREFUSED')
const fetchFn = vi.fn<typeof fetch>(async () => {
controller.abort(new Error('caller gave up'))
throw failure
})
await expect(
clientAt('http://proxy.invalid', fetchFn).stream({ ...INPUT, signal: controller.signal })
).rejects.toBe(failure)
expect(fetchFn).toHaveBeenCalledTimes(1)
})
it('G1-7e leaves an error raised after the response started unchanged', async () => {
const failure = fetchFailure('ECONNREFUSED')
const fetchFn = vi.fn<typeof fetch>(
async () =>
new Response(
new ReadableStream<Uint8Array>({
start(controller) {
controller.error(failure)
},
}),
{ status: 200, headers: { 'content-type': 'text/event-stream' } }
)
)
await expect(clientAt('http://proxy.invalid', fetchFn).stream(INPUT)).rejects.toBe(failure)
expect(fetchFn).toHaveBeenCalledTimes(1)
})
})
// G1-8 (#720): the classifier's answer for the two codes G1 adds on the wire.
describe('CodexSubscriptionProvider G1 classification', () => {
const provider = new CodexSubscriptionProvider('gpt-5.3-codex', {} as never)
async function proxyReply(response: Response): Promise<unknown> {
const fetchFn = vi.fn<typeof fetch>(async () => response)
const err = await new CodexLlmProxyClient({
runtimeUrl: 'http://proxy/completions',
readPlatformJwt: () => 'platform-jwt',
fetchFn,
})
.stream({ executionTicket: 'ticket-123456', requestHash: 'a'.repeat(64), request: {} })
.catch((caught: unknown) => caught)
// Liveness witness: the proxy hop ran.
expect(fetchFn).toHaveBeenCalledTimes(1)
return err
}
it('G1-8a keeps an upstream 4xx terminal with no failover', async () => {
const err = await proxyReply(
Response.json({ error: 'upstream_rejected', upstreamStatus: 404 }, { status: 422 })
)
const classified = provider.classifyError(err)
expect(classified).toMatchObject({
// Review round 2 L12: its own code, not the "Connection Error" of
// LLM_API_CALL_FAILED. The literal pins the value the Desktop keys on.
code: 'LLM_UPSTREAM_REJECTED',
retryable: false,
providerCode: 'upstream_rejected',
providerDispatched: true,
// Review R1-H2: a 402 and a 404 no longer read the same downstream.
httpStatus: 404,
})
expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
})
it('G1-8c reads the upstream status from an SSE error frame', async () => {
const err = await proxyReply(
new Response(sse([{ type: 'error', code: 'upstream_rejected', upstreamStatus: 402 }]), {
status: 200,
headers: { 'content-type': 'text/event-stream' },
})
)
expect(err).toMatchObject({ code: 'upstream_rejected', upstreamStatus: 402 })
expect(provider.classifyError(err)).toMatchObject({
code: 'LLM_UPSTREAM_REJECTED',
httpStatus: 402,
})
})
// Review round 2 L11: both ends of 400..499 are accepted.
it.each([400, 499])('G1-8d reads an upstreamStatus of exactly %j', async upstreamStatus => {
const err = await proxyReply(
Response.json({ error: 'upstream_rejected', upstreamStatus }, { status: 422 })
)
expect(err).toMatchObject({ code: 'upstream_rejected', upstreamStatus })
expect(provider.classifyError(err).httpStatus).toBe(upstreamStatus)
})
it.each([200, 399, 404.5, '404', 500, 600])(
'G1-8d ignores an upstreamStatus of %j that is not an integer 4xx',
async upstreamStatus => {
const err = await proxyReply(
Response.json({ error: 'upstream_rejected', upstreamStatus }, { status: 422 })
)
// Witness: the code still arrived; only the status was refused.
expect(err).toMatchObject({ code: 'upstream_rejected' })
expect((err as { upstreamStatus?: number }).upstreamStatus).toBeUndefined()
expect(provider.classifyError(err).httpStatus).toBeUndefined()
}
)
it('G1-8e reads upstreamStatus only for upstream_rejected', async () => {
const err = await proxyReply(
Response.json({ error: 'provider_unavailable', upstreamStatus: 404 }, { status: 503 })
)
expect(err).toMatchObject({ code: 'provider_unavailable' })
expect((err as { upstreamStatus?: number }).upstreamStatus).toBeUndefined()
})
it('G1-8b labels a gateway control_plane_unavailable reply as a control-plane outage', async () => {
const err = await proxyReply(
Response.json({ error: 'control_plane_unavailable' }, { status: 503 })
)
const classified = provider.classifyError(err)
expect(LlmErrorCode.ControlPlaneUnavailable).toBe('LLM_CONTROL_PLANE_UNAVAILABLE')
expect(classified).toMatchObject({
code: LlmErrorCode.ControlPlaneUnavailable,
retryable: true,
providerCode: 'control_plane_unavailable',
providerDispatched: true,
})
// Same failover class as the outage label it replaces.
expect(classifyFailoverClass(classified.code, classified.retryable)).toBe(
'provider_unavailable'
)
})
it('G1-8b labels a refused proxy connection as a control-plane outage', async () => {
const url = await closedPortUrl()
const err = await new CodexLlmProxyClient({
runtimeUrl: resolveCodexProxyRuntimeUrl(url),
readPlatformJwt: () => 'platform-jwt',
})
.stream({ executionTicket: 'ticket-123456', requestHash: 'a'.repeat(64), request: {} })
.catch((caught: unknown) => caught)
expect(err).toMatchObject({ code: 'control_plane_unavailable' })
expect(provider.classifyError(err)).toMatchObject({
code: LlmErrorCode.ControlPlaneUnavailable,
retryable: true,
providerCode: 'control_plane_unavailable',
// Review round 2 L10: the request never left the Host, but the proxy
// client does not claim so. `true` is the conservative reading
// (llm/types.ts): it keeps the idempotency key from being revived after
// an authorize that already reserved the attempt. Same as dev.
providerDispatched: true,
})
})
it('G1-8b labels an authorize that reached no gateway as a control-plane outage, not dispatched', () => {
const classified = provider.classifyError(
new CodexAuthorizeError(
'control_plane_unavailable',
'authorize could not reach the control plane (ECONNREFUSED)'
)
)
expect(classified).toMatchObject({
code: LlmErrorCode.ControlPlaneUnavailable,
retryable: true,
providerCode: 'control_plane_unavailable',
providerDispatched: false,
})
expect(classifyFailoverClass(classified.code, classified.retryable)).toBe(
'provider_unavailable'
)
})
it('G1-8c still labels provider_unavailable as an overload', async () => {
const err = await proxyReply(Response.json({ error: 'provider_unavailable' }, { status: 503 }))
expect(provider.classifyError(err)).toMatchObject({
code: LlmErrorCode.ModelOverloaded,
retryable: true,
})
})
})