Skip to content

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

TypeScript

fix: harden Grok and Codex LLM proxies

Jose Gabriel Ramirez Encinasbf5b2936e6a3
diff --git a/codex-llm-proxy/package.json b/codex-llm-proxy/package.json
index 03eaa4074..7db200526 100644
--- a/codex-llm-proxy/package.json
+++ b/codex-llm-proxy/package.json
@@ -8,9 +8,10 @@
},
"scripts": {
"build": "tsc -p tsconfig.build.json",
- "typecheck": "tsc --noEmit",
+ "typecheck": "tsc --noEmit && npm run typecheck:test",
+ "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
"start": "node dist/main.js",
- "test": "vitest run",
+ "test": "npm run typecheck:test && vitest run",
"test:watch": "vitest"
},
"license": "SEE LICENSE IN LICENSE",
diff --git a/codex-llm-proxy/src/codexTransport.ts b/codex-llm-proxy/src/codexTransport.ts
index af7b60c5f..5fca274bb 100644
--- a/codex-llm-proxy/src/codexTransport.ts
+++ b/codex-llm-proxy/src/codexTransport.ts
@@ -23,6 +23,13 @@ export type StreamFrame =
| { type: 'text'; text: string }
| { type: 'tool_call'; id: string; name: string; arguments: Record<string, unknown> }
+/**
+ * Receives mapped frames. Returning a promise signals client backpressure: the
+ * SSE reader stops pulling upstream bytes until it settles (or the stream
+ * aborts), so a slow consumer cannot make the proxy buffer an unbounded stream.
+ */
+export type FrameSink = (frame: StreamFrame) => void | Promise<void>
+
export type TransportTicket = {
jti: string
hostRef: string
@@ -68,7 +75,7 @@ export type StreamCodexCompletionInput = {
}) => Promise<FinalizeAttemptSuccess>
fetchFn: typeof fetch
lookup?: OriginPolicyOptions['lookup']
- onFrame?: (frame: StreamFrame) => void
+ onFrame?: FrameSink
}
export type StreamCodexCompletionResult = {
@@ -91,6 +98,11 @@ export async function streamCodexCompletion(
if (request.model !== input.ticket.model) {
throw new CodexTransportError('model_not_allowed', 'request model does not match the ticket')
}
+ // A client that disconnected before dispatch must not consume the ticket:
+ // nothing was redeemed, so there is no attempt receipt to finalize.
+ if (input.signal?.aborted) {
+ return { outcome: 'canceled' }
+ }
const redeemed = await input.redeem({
executionTicket: input.executionTicket,
requestHash: input.requestHash,
@@ -189,7 +201,7 @@ async function readUpstreamStream(input: {
signal?: AbortSignal
fetchFn: typeof fetch
lookup?: OriginPolicyOptions['lookup']
- onFrame?: (frame: StreamFrame) => void
+ onFrame?: FrameSink
}): Promise<StreamCodexCompletionResult> {
const url = assertAllowedUpstreamUrl(CODEX_COMPLETIONS_ORIGIN, 'completions')
const timeout = AbortSignal.timeout(input.deadlineMs)
@@ -318,7 +330,7 @@ function toUpstreamPayload(
async function consumeSse(
body: ReadableStream<Uint8Array>,
- onFrame: ((frame: StreamFrame) => void) | undefined,
+ onFrame: FrameSink | undefined,
signal: AbortSignal,
names: ToolNameMap
): Promise<StreamCodexCompletionResult> {
@@ -328,7 +340,7 @@ async function consumeSse(
// Text stays streaming. Calls become executable only once the entire
// response succeeds and its independent call budget has been validated.
const toolFrames: Array<Extract<StreamFrame, { type: 'tool_call' }>> = []
- const acceptFrame = (frame?: StreamFrame) => {
+ const acceptFrame = async (frame?: StreamFrame): Promise<void> => {
if (pending.size > LIMITS.maxToolCalls) {
throw new CodexTransportError(
'provider_unavailable',
@@ -350,7 +362,7 @@ async function consumeSse(
)
}
toolFrames.push({ ...frame, name: canonicalName })
- } else if (frame) onFrame?.(frame)
+ } else if (frame) await deliverFrame(onFrame, frame, signal)
}
let buffer = ''
let completed = false
@@ -369,7 +381,7 @@ async function consumeSse(
buffer = parts.pop() ?? ''
for (const part of parts) {
const mapped = ingestSseBlock(part, pending)
- acceptFrame(mapped.frame)
+ await acceptFrame(mapped.frame)
if (mapped.usage) usage = mapped.usage
if (mapped.completed) completed = true
if (mapped.failed) failed = true
@@ -379,7 +391,7 @@ async function consumeSse(
buffer += decoder.decode().replace(/\r\n/g, '\n').replace(/\r/g, '\n')
if (buffer.trim()) {
const mapped = ingestSseBlock(buffer, pending)
- acceptFrame(mapped.frame)
+ await acceptFrame(mapped.frame)
if (mapped.usage) usage = mapped.usage
if (mapped.completed) completed = true
if (mapped.failed) failed = true
@@ -393,7 +405,7 @@ async function consumeSse(
for (const call of pending.values()) {
if (call.emitted) continue
const args = parseToolArguments(call.arguments)
- acceptFrame({ type: 'tool_call', id: call.id, name: call.name, arguments: args })
+ await acceptFrame({ type: 'tool_call', id: call.id, name: call.name, arguments: args })
call.emitted = true
}
if (signal.aborted) return { outcome: 'canceled', usage }
@@ -401,12 +413,36 @@ async function consumeSse(
throw new CodexTransportError('provider_unavailable', 'upstream response failed')
}
if (completed) {
- for (const frame of toolFrames) onFrame?.(frame)
+ for (const frame of toolFrames) await deliverFrame(onFrame, frame, signal)
return { outcome: 'success', usage }
}
return { outcome: 'unknown', usage }
}
+async function deliverFrame(
+ onFrame: FrameSink | undefined,
+ frame: StreamFrame,
+ signal: AbortSignal
+): Promise<void> {
+ const pending: unknown = onFrame?.(frame)
+ // Only a thenable signals backpressure; a `void` callback may return anything.
+ if (!(pending instanceof Promise) || signal.aborted) return
+ await new Promise<void>((resolve, reject) => {
+ const onAbort = () => resolve()
+ signal.addEventListener('abort', onAbort, { once: true })
+ pending.then(
+ () => {
+ signal.removeEventListener('abort', onAbort)
+ resolve()
+ },
+ err => {
+ signal.removeEventListener('abort', onAbort)
+ reject(err)
+ }
+ )
+ })
+}
+
function ingestSseBlock(
part: string,
pending: Map<string, PendingToolCall>
@@ -549,25 +585,49 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && Array.isArray(value) === false
}
+/**
+ * Bounds for the admin catalog/test upstream call: a hard deadline covering
+ * headers and body, a streamed body cap, and normalized-model caps aligned
+ * with control-api's catalog sync limits.
+ */
+export const CATALOG_LIMITS = {
+ timeoutMs: 15_000,
+ // Live ChatGPT catalog rows can carry per-model instruction payloads and the
+ // production size is unmeasured; keep generous headroom over the Grok cap.
+ maxBodyBytes: 8 * 1_048_576,
+ maxModels: 256,
+ maxModelIdLength: 128,
+} as const
+
export async function listCodexModels(input: {
accessToken: string
fetchFn: typeof fetch
lookup?: OriginPolicyOptions['lookup']
+ /** Test seam; production uses CATALOG_LIMITS.timeoutMs. */
+ timeoutMs?: number
}): Promise<{
outcome: 'ready' | 'auth-rejected' | 'unavailable'
models: Array<{ model: string; displayName?: string }>
}> {
const url = assertAllowedUpstreamUrl(CODEX_CATALOG_ORIGIN, 'catalog')
const headers = chatgptUpstreamHeaders(input.accessToken, { accept: 'application/json' })
- const response = await fetchFrozenOrigin({
- url,
- fetchFn: input.fetchFn,
- lookup: input.lookup,
- init: {
- method: 'GET',
- headers,
- },
- })
+ const signal = AbortSignal.timeout(input.timeoutMs ?? CATALOG_LIMITS.timeoutMs)
+ let response: Response
+ try {
+ response = await fetchFrozenOrigin({
+ url,
+ fetchFn: input.fetchFn,
+ lookup: input.lookup,
+ init: {
+ method: 'GET',
+ headers,
+ signal,
+ },
+ })
+ } catch (err) {
+ if (signal.aborted) throw catalogTimeoutError()
+ throw err
+ }
if (response.status === 401 || response.status === 403)
return { outcome: 'auth-rejected', models: [] }
if (!response.ok) {
@@ -581,7 +641,8 @@ export async function listCodexModels(input: {
)
return { outcome: 'unavailable', models: [] }
}
- const body = (await response.json()) as unknown
+ const raw = await readBoundedCatalogBody(response, signal)
+ const body = JSON.parse(raw) as unknown
return { outcome: 'ready', models: normalizeModels(body) }
}
@@ -589,6 +650,7 @@ export async function testCodexConnection(input: {
accessToken: string
fetchFn: typeof fetch
lookup?: OriginPolicyOptions['lookup']
+ timeoutMs?: number
}): Promise<{ outcome: 'ready' | 'auth-rejected' | 'unavailable' }> {
const listed = await listCodexModels(input)
return { outcome: listed.outcome }
@@ -603,10 +665,20 @@ function normalizeModels(body: unknown): Array<{ model: string; displayName?: st
? body.data
: []
const models: Array<{ model: string; displayName?: string }> = []
+ let droppedOverlongIds = 0
+ let droppedOverLimit = 0
for (const row of rows) {
if (!isPlainObject(row)) continue
const model = String(row.model || row.slug || row.id || '').trim()
if (!model) continue
+ if (model.length > CATALOG_LIMITS.maxModelIdLength) {
+ droppedOverlongIds += 1
+ continue
+ }
+ if (models.length >= CATALOG_LIMITS.maxModels) {
+ droppedOverLimit += 1
+ continue
+ }
const displayName =
typeof row.displayName === 'string'
? row.displayName
@@ -615,5 +687,60 @@ function normalizeModels(body: unknown): Array<{ model: string; displayName?: st
: undefined
models.push(displayName ? { model, displayName } : { model })
}
+ if (droppedOverlongIds > 0 || droppedOverLimit > 0) {
+ logger.warn(
+ {
+ event: 'codex_catalog_bounded',
+ received: rows.length,
+ accepted: models.length,
+ droppedOverlongIds,
+ droppedOverLimit,
+ },
+ 'Codex catalog response exceeded proxy bounds'
+ )
+ }
return models
}
+
+function catalogTimeoutError(): CodexTransportError {
+ return new CodexTransportError('provider_unavailable', 'catalog upstream deadline exceeded')
+}
+
+/** Read the catalog body under the deadline, cancelling past the byte cap. */
+async function readBoundedCatalogBody(response: Response, signal: AbortSignal): Promise<string> {
+ if (!response.body) return ''
+ const reader = response.body.getReader()
+ let onAbort: (() => void) | undefined
+ const aborted = new Promise<never>((_, reject) => {
+ onAbort = () => reject(catalogTimeoutError())
+ if (signal.aborted) onAbort()
+ else signal.addEventListener('abort', onAbort, { once: true })
+ })
+ aborted.catch(() => undefined)
+ const chunks: Uint8Array[] = []
+ let total = 0
+ try {
+ for (;;) {
+ const { done, value } = await Promise.race([reader.read(), aborted])
+ if (done) break
+ total += value.byteLength
+ if (total > CATALOG_LIMITS.maxBodyBytes) {
+ throw new CodexTransportError('provider_unavailable', 'catalog upstream body exceeds limit')
+ }
+ chunks.push(value)
+ }
+ } catch (err) {
+ await reader.cancel().catch(() => undefined)
+ if (err instanceof CodexTransportError) throw err
+ if (signal.aborted) throw catalogTimeoutError()
+ throw err
+ } finally {
+ if (onAbort) signal.removeEventListener('abort', onAbort)
+ try {
+ reader.releaseLock()
+ } catch {
+ // A pending read may still hold the lock after cancel; nothing to release.
+ }
+ }
+ return Buffer.concat(chunks).toString('utf8')
+}
diff --git a/codex-llm-proxy/src/config.ts b/codex-llm-proxy/src/config.ts
index dee88f64e..2baa3094d 100644
--- a/codex-llm-proxy/src/config.ts
+++ b/codex-llm-proxy/src/config.ts
@@ -32,6 +32,29 @@ function requiredPem(name: string, raw: string | undefined): string {
return value
}
+// Fail at startup instead of at the first redeem. Messages name the variable
+// only; the raw value (URL or service token) is never echoed.
+function requiredHttpUrl(name: string, raw: string | undefined): string {
+ const value = raw?.trim() ?? ''
+ if (!value) throw new Error(`${name} must be set`)
+ let parsed: URL
+ try {
+ parsed = new URL(value)
+ } catch {
+ throw new Error(`${name} must be an absolute http(s) URL`)
+ }
+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+ throw new Error(`${name} must be an absolute http(s) URL`)
+ }
+ return value
+}
+
+function requiredNonEmpty(name: string, raw: string | undefined): string {
+ const value = raw?.trim() ?? ''
+ if (!value) throw new Error(`${name} must be set`)
+ return value
+}
+
export function loadConfig(env: NodeJS.ProcessEnv = process.env): CodexLlmProxyConfig {
return {
runtimePort: requiredPositiveInt('CODEX_LLM_PROXY_RUNTIME_PORT', env.CODEX_LLM_PROXY_RUNTIME_PORT, 8080),
@@ -55,8 +78,8 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): CodexLlmProxyC
jwtIssuer: env.CODEX_LLM_PROXY_JWT_ISSUER?.trim() || 'control-api',
jwtPublicKey: requiredPem('CODEX_LLM_PROXY_JWT_PUBLIC_KEY', env.CODEX_LLM_PROXY_JWT_PUBLIC_KEY),
executionEnabled: env.CODEX_LLM_PROXY_EXECUTION_ENABLED === 'true',
- controlApiBaseUrl: env.CODEX_LLM_PROXY_CONTROL_API_URL?.trim() || '',
+ controlApiBaseUrl: requiredHttpUrl('CODEX_LLM_PROXY_CONTROL_API_URL', env.CODEX_LLM_PROXY_CONTROL_API_URL),
controlApiServiceName: env.CODEX_LLM_PROXY_CONTROL_API_SERVICE?.trim() || 'codex-llm-proxy',
- controlApiServiceToken: env.CODEX_LLM_PROXY_CONTROL_API_TOKEN?.trim() || '',
+ controlApiServiceToken: requiredNonEmpty('CODEX_LLM_PROXY_CONTROL_API_TOKEN', env.CODEX_LLM_PROXY_CONTROL_API_TOKEN),
}
}
diff --git a/codex-llm-proxy/src/controlApiClient.ts b/codex-llm-proxy/src/controlApiClient.ts
index a362c7235..148e445fa 100644
--- a/codex-llm-proxy/src/controlApiClient.ts
+++ b/codex-llm-proxy/src/controlApiClient.ts
@@ -84,10 +84,7 @@ export class ControlApiClient {
}
return {
providerAttemptId: String(body.providerAttemptId ?? input.receipt.providerAttemptId),
- outcome:
- body.outcome === 'canceled' || body.outcome === 'error' || body.outcome === 'unknown'
- ? body.outcome
- : 'success',
+ outcome: parseFinalizeOutcome(body.outcome),
duplicate: body.duplicate === true,
}
}
@@ -129,6 +126,18 @@ function parseRedeem(body: unknown): RedeemAttemptSuccess {
throw new ControlApiClientError('provider_unavailable', 'redeem response is invalid')
}
const transport = body.transport
+ // Absent keeps the historical 300s default. A present value must be a
+ // finite positive number: zero/negative would reach AbortSignal.timeout as a
+ // RangeError, and a non-number is a control-api contract violation.
+ const maxStreamDurationMs =
+ transport.maxStreamDurationMs === undefined ? 300_000 : transport.maxStreamDurationMs
+ if (
+ typeof maxStreamDurationMs !== 'number' ||
+ !Number.isFinite(maxStreamDurationMs) ||
+ maxStreamDurationMs <= 0
+ ) {
+ throw new ControlApiClientError('provider_unavailable', 'redeem maxStreamDurationMs is invalid')
+ }
if (
transport.protocolVersion !== CODEX_TRANSPORT_PROTOCOL ||
transport.completionsOrigin !== CODEX_COMPLETIONS_ORIGIN ||
@@ -154,16 +163,20 @@ function parseRedeem(body: unknown): RedeemAttemptSuccess {
? transport.operation
: 'completion_stream',
servedModel: transport.servedModel,
- maxStreamDurationMs:
- typeof transport.maxStreamDurationMs === 'number' && Number.isFinite(transport.maxStreamDurationMs)
- ? transport.maxStreamDurationMs
- : 300_000,
+ maxStreamDurationMs,
},
expiryClass: body.expiryClass === 'upstream_managed' ? 'upstream_managed' : 'short_lived',
attemptReceipt: body.attemptReceipt,
}
}
+/** Unrecognized finalize outcomes are ambiguous; never report them as success. */
+function parseFinalizeOutcome(raw: unknown): FinalizeAttemptSuccess['outcome'] {
+ return raw === 'success' || raw === 'canceled' || raw === 'error' || raw === 'unknown'
+ ? raw
+ : 'unknown'
+}
+
function isPlainObject(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
diff --git a/codex-llm-proxy/src/requestLimits.ts b/codex-llm-proxy/src/requestLimits.ts
index 1d092b926..550e48cde 100644
--- a/codex-llm-proxy/src/requestLimits.ts
+++ b/codex-llm-proxy/src/requestLimits.ts
@@ -27,23 +27,36 @@ export class StreamGate {
private queued = 0
constructor(
- private readonly maxConcurrent = STREAM_LIMITS.maxConcurrentStreams,
- private readonly maxQueued = STREAM_LIMITS.maxQueuedRequests
+ private readonly maxConcurrent: number = STREAM_LIMITS.maxConcurrentStreams,
+ private readonly maxQueued: number = STREAM_LIMITS.maxQueuedRequests
) {}
- async acquire(): Promise<() => void> {
+ /**
+ * Take a stream slot. When `signal` aborts (client disconnected) while the
+ * caller is still queued, the waiter is rejected and its queue slot freed, so
+ * a dropped client never proceeds to redeem an attempt.
+ */
+ async acquire(signal?: AbortSignal): Promise<() => void> {
+ if (signal?.aborted) throw new RequestLimitError('stream request was aborted')
if (this.running >= this.maxConcurrent) {
if (this.queued >= this.maxQueued) throw new RequestLimitError('stream queue is full')
this.queued += 1
try {
- await new Promise<void>(resolve => {
+ await new Promise<void>((resolve, reject) => {
+ let timer: ReturnType<typeof setTimeout> | undefined
+ const onAbort = () => {
+ if (timer !== undefined) clearTimeout(timer)
+ reject(new RequestLimitError('stream request was aborted'))
+ }
const wait = () => {
if (this.running < this.maxConcurrent) {
+ signal?.removeEventListener('abort', onAbort)
resolve()
return
}
- setTimeout(wait, 10)
+ timer = setTimeout(wait, 10)
}
+ signal?.addEventListener('abort', onAbort, { once: true })
wait()
})
} finally {
diff --git a/codex-llm-proxy/src/server.ts b/codex-llm-proxy/src/server.ts
index 219a780d6..6d6448cfe 100644
--- a/codex-llm-proxy/src/server.ts
+++ b/codex-llm-proxy/src/server.ts
@@ -162,7 +162,7 @@ export function createProxyApps(config: CodexLlmProxyConfig, deps: ProxyRuntimeD
// Abort only when the client drops the response before we finish writing.
abortWhenClientDisconnects(req, res, abort)
try {
- release = await streamGate.acquire()
+ release = await streamGate.acquire(abort.signal)
res.status(200)
res.setHeader('content-type', 'text/event-stream')
res.setHeader('cache-control', 'no-cache')
@@ -185,9 +185,7 @@ export function createProxyApps(config: CodexLlmProxyConfig, deps: ProxyRuntimeD
finalize: input => client.finalize(input),
fetchFn,
lookup,
- onFrame: frame => {
- res.write(`data: ${JSON.stringify(frame)}\n\n`)
- },
+ onFrame: frame => writeSseChunk(res, `data: ${JSON.stringify(frame)}\n\n`, abort.signal),
})
res.write(
`data: ${JSON.stringify({ type: 'done', outcome: result.outcome, ...(result.usage ? { usage: result.usage } : {}) })}\n\n`
@@ -337,6 +335,32 @@ function mapError(err: unknown): { status: number; code: string } {
return { status: 503, code: 'provider_unavailable' }
}
+/**
+ * Write one SSE chunk and honor socket backpressure. Returns undefined when
+ * the chunk was accepted (hot path stays synchronous); otherwise a promise that
+ * settles on 'drain', or when the client closes / the stream aborts so a
+ * departed consumer never pins the stream slot.
+ */
+export function writeSseChunk(
+ res: Response,
+ chunk: string,
+ signal: AbortSignal
+): Promise<void> | undefined {
+ if (res.write(chunk)) return undefined
+ return new Promise<void>(resolve => {
+ const done = () => {
+ res.off('drain', done)
+ res.off('close', done)
+ signal.removeEventListener('abort', done)
+ resolve()
+ }
+ res.on('drain', done)
+ res.on('close', done)
+ signal.addEventListener('abort', done, { once: true })
+ if (signal.aborted || res.destroyed) done()
+ })
+}
+
export function abortWhenClientDisconnects(
req: Request,
res: Response,
diff --git a/codex-llm-proxy/test/catalogBounds.test.ts b/codex-llm-proxy/test/catalogBounds.test.ts
new file mode 100644
index 000000000..475f434c7
--- /dev/null
+++ b/codex-llm-proxy/test/catalogBounds.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest'
+import { CATALOG_LIMITS, listCodexModels, testCodexConnection } from '../src/codexTransport.js'
+
+const lookup = async () => [{ address: '1.2.3.4', family: 4 }]
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+}
+
+/** Rejects when the request has no deadline signal; otherwise hangs until it aborts. */
+const stalledFetch = (async (_url: unknown, init?: RequestInit) =>
+ new Promise<Response>((_, reject) => {
+ const signal = init?.signal
+ if (!signal) {
+ reject(new Error('catalog fetch carries no deadline signal'))
+ return
+ }
+ signal.addEventListener('abort', () => reject(signal.reason), { once: true })
+ })) as typeof fetch
+
+describe('Codex catalog upstream bounds', () => {
+ it('uses a 15s deadline, an 8 MiB body cap, and the control-api model caps', () => {
+ expect(CATALOG_LIMITS).toEqual({
+ timeoutMs: 15_000,
+ maxBodyBytes: 8 * 1_048_576,
+ maxModels: 256,
+ maxModelIdLength: 128,
+ })
+ })
+
+ it('lists a normal catalog', async () => {
+ const listed = await listCodexModels({
+ accessToken: 'tok',
+ fetchFn: (async () =>
+ jsonResponse({ data: [{ id: 'gpt-5.1', title: 'GPT 5.1' }] })) as typeof fetch,
+ lookup,
+ })
+ expect(listed).toEqual({
+ outcome: 'ready',
+ models: [{ model: 'gpt-5.1', displayName: 'GPT 5.1' }],
+ })
+ })
+
+ it('fails a stalled catalog request at the deadline instead of hanging', async () => {
+ await expect(
+ listCodexModels({ accessToken: 'tok', fetchFn: stalledFetch, lookup, timeoutMs: 50 })
+ ).rejects.toMatchObject({ code: 'provider_unavailable' })
+ await expect(
+ testCodexConnection({ accessToken: 'tok', fetchFn: stalledFetch, lookup, timeoutMs: 50 })
+ ).rejects.toMatchObject({ code: 'provider_unavailable' })
+ })
+
+ it('fails a catalog body that stalls after headers at the deadline', async () => {
+ const fetchFn = (async () =>
+ new Response(new ReadableStream<Uint8Array>({ pull: () => new Promise(() => {}) }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })) as typeof fetch
+ const started = Date.now()
+ await expect(
+ listCodexModels({ accessToken: 'tok', fetchFn, lookup, timeoutMs: 50 })
+ ).rejects.toMatchObject({ code: 'provider_unavailable' })
+ expect(Date.now() - started).toBeLessThan(2_000)
+ })
+
+ it('stops reading and fails a catalog body larger than the cap', async () => {
+ const chunk = new TextEncoder().encode(' '.repeat(64 * 1024))
+ let pulledBytes = 0
+ const fetchFn = (async () =>
+ new Response(
+ new ReadableStream<Uint8Array>(
+ {
+ pull(controller) {
+ // Finite (3x the cap) so a missing cap fails on the assertion, not OOM.
+ if (pulledBytes >= 3 * CATALOG_LIMITS.maxBodyBytes) {
+ controller.close()
+ return
+ }
+ pulledBytes += chunk.byteLength
+ controller.enqueue(chunk)
+ },
+ },
+ { highWaterMark: 0 }
+ ),
+ { status: 200, headers: { 'content-type': 'application/json' } }
+ )) as typeof fetch
+ await expect(listCodexModels({ accessToken: 'tok', fetchFn, lookup })).rejects.toMatchObject({
+ code: 'provider_unavailable',
+ })
+ expect(pulledBytes).toBeLessThanOrEqual(CATALOG_LIMITS.maxBodyBytes + 2 * chunk.byteLength)
+ })
+
+ it('caps the normalized catalog at 256 models and drops ids longer than 128 chars', async () => {
+ const overlong = 'm'.repeat(129)
+ const rows = [
+ { id: overlong },
+ { id: 'm'.repeat(128) },
+ ...Array.from({ length: 300 }, (_, index) => ({ id: `model-${index}` })),
+ ]
+ const listed = await listCodexModels({
+ accessToken: 'tok',
+ fetchFn: (async () => jsonResponse({ data: rows })) as typeof fetch,
+ lookup,
+ })
+ expect(listed.outcome).toBe('ready')
+ expect(listed.models).toHaveLength(256)
+ expect(listed.models.some(row => row.model === overlong)).toBe(false)
+ expect(listed.models[0]).toEqual({ model: 'm'.repeat(128) })
+ expect(listed.models.every(row => row.model.length <= 128)).toBe(true)
+ })
+})
diff --git a/codex-llm-proxy/test/codexTransport.conformance.test.ts b/codex-llm-proxy/test/codexTransport.conformance.test.ts
index 2d9f1d9ab..7a02f7ca4 100644
--- a/codex-llm-proxy/test/codexTransport.conformance.test.ts
+++ b/codex-llm-proxy/test/codexTransport.conformance.test.ts
@@ -3,7 +3,11 @@ import {
hashCodexCompletionRequestV1,
parseCodexCompletionRequestV1,
} from '@clerum/llm-provider-attempt-contract'
-import { CodexTransportError, streamCodexCompletion } from '../src/codexTransport.js'
+import {
+ CodexTransportError,
+ type StreamCodexCompletionInput,
+ streamCodexCompletion,
+} from '../src/codexTransport.js'
import type { RedeemAttemptSuccess } from '../src/controlApiClient.js'
import { CODEX_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
import { ToolNameMap } from '../src/toolNameMap.js'
@@ -18,6 +22,12 @@ const REQUEST = {
messages: [{ role: 'user' as const, content: 'hello' }],
}
+type FetchInput = string | URL | Request
+
+function headerOf(init: RequestInit | undefined, name: string): string | undefined {
+ return (init?.headers as Record<string, string> | undefined)?.[name]
+}
+
const REQUEST_HASH = hashCodexCompletionRequestV1(REQUEST)
function accessTokenFor(label: string): string {
@@ -59,6 +69,105 @@ function sseResponse(
}
describe('streamCodexCompletion', () => {
+ it('does not read further upstream bytes while the frame consumer is back-pressured', async () => {
+ const encoder = new TextEncoder()
+ const events = [
+ 'data: {"type":"response.output_text.delta","delta":"one"}\n\n',
+ 'data: {"type":"response.output_text.delta","delta":"two"}\n\n',
+ 'data: {"type":"response.completed","response":{"usage":{}}}\n\n',
+ ]
+ let pulls = 0
+ const fetchFn = vi.fn(async () => {
+ const body = new ReadableStream<Uint8Array>(
+ {
+ pull(controller) {
+ const next = events[pulls]
+ pulls += 1
+ if (next === undefined) controller.close()
+ else controller.enqueue(encoder.encode(next))
+ },
+ },
+ { highWaterMark: 0 }
+ )
+ return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } })
+ })
+ let releaseDrain: (() => void) | undefined
+ const drained = new Promise<void>(resolve => {
+ releaseDrain = resolve
+ })
+ const frames: unknown[] = []
+ const pending = streamCodexCompletion({
+ executionTicket: 'ticket-drain',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-drain',
+ hostRef: 'research-host',
+ model: REQUEST.model,
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-drain',
+ },
+ redeem: async () => redeemSuccess(),
+ finalize: vi.fn(async () => ({
+ providerAttemptId: 'att-drain',
+ outcome: 'success' as const,
+ duplicate: false,
+ })),
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ onFrame: frame => {
+ frames.push(frame)
+ // First frame fills the client buffer; later frames are accepted.
+ return frames.length === 1 ? drained : undefined
+ },
+ })
+ await new Promise(resolve => setTimeout(resolve, 50))
+ expect(frames).toEqual([{ type: 'text', text: 'one' }])
+ expect(pulls).toBe(1)
+ releaseDrain?.()
+ const result = await pending
+ expect(result.outcome).toBe('success')
+ expect(frames).toEqual([
+ { type: 'text', text: 'one' },
+ { type: 'text', text: 'two' },
+ ])
+ })
+
+ it('does not redeem when the client aborted before the attempt was dispatched', async () => {
+ const redeem = vi.fn(async () => redeemSuccess())
+ const finalize = vi.fn(async () => ({
+ providerAttemptId: 'att-pre-abort',
+ outcome: 'canceled' as const,
+ duplicate: false,
+ }))
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
+ sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
+ )
+ const abort = new AbortController()
+ abort.abort()
+ const result = await streamCodexCompletion({
+ executionTicket: 'ticket-pre-abort',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-pre-abort',
+ hostRef: 'research-host',
+ model: REQUEST.model,
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-pre-abort',
+ },
+ signal: abort.signal,
+ redeem,
+ finalize,
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ })
+ expect(result.outcome).toBe('canceled')
+ expect(redeem).not.toHaveBeenCalled()
+ expect(fetchFn).not.toHaveBeenCalled()
+ expect(finalize).not.toHaveBeenCalled()
+ })
+
it('preserves real MCP optional schemas with explicit non-strict upstream tools', async () => {
const request = {
...REQUEST,
@@ -70,7 +179,9 @@ describe('streamCodexCompletion', () => {
}
const original = structuredClone(request)
const requestHash = hashCodexCompletionRequestV1(request)
- const fetchFn = vi.fn(async () => sseResponse(['data: {"type":"response.completed"}\n\n']))
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
+ sseResponse(['data: {"type":"response.completed"}\n\n'])
+ )
await streamCodexCompletion({
executionTicket: 'ticket-optionality',
requestHash,
@@ -85,7 +196,7 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-optionality',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -169,17 +280,19 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-arguments',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
- fetchFn: vi.fn(async () =>
+ fetchFn: vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse([
`data: ${JSON.stringify({ type: 'response.output_item.done', item: { type: 'function_call', call_id: 'call-optional', name: names.toWire(canonical), arguments: JSON.stringify(args) } })}\n\n`,
'data: {"type":"response.completed"}\n\n',
])
),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => frames.push(frame),
+ onFrame: frame => {
+ frames.push(frame)
+ },
})
expect(frames).toEqual([
{ type: 'tool_call', id: 'call-optional', name: canonical, arguments: args },
@@ -212,9 +325,11 @@ describe('streamCodexCompletion', () => {
outcome: 'success' as const,
duplicate: false,
})),
- fetchFn: vi.fn(async () => sseResponse(frames)),
+ fetchFn: vi.fn(async (_url: FetchInput, _init?: RequestInit) => sseResponse(frames)),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => emitted.push(frame),
+ onFrame: frame => {
+ emitted.push(frame)
+ },
})
if (terminal === 'unterminated') expect((await pending).outcome).toBe('unknown')
else await expect(pending).rejects.toThrow(/upstream response failed/)
@@ -252,9 +367,11 @@ describe('streamCodexCompletion', () => {
},
redeem: vi.fn(async () => redeemSuccess()),
finalize,
- fetchFn: vi.fn(async () => sseResponse(frames)),
+ fetchFn: vi.fn(async (_url: FetchInput, _init?: RequestInit) => sseResponse(frames)),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => emitted.push(frame),
+ onFrame: frame => {
+ emitted.push(frame)
+ },
})
if (count === 32) {
expect((await pending).outcome).toBe('success')
@@ -276,7 +393,7 @@ describe('streamCodexCompletion', () => {
duplicate: false,
}))
const frames: unknown[] = []
- const fetchFn = vi.fn(async (url: string) => {
+ const fetchFn = vi.fn(async (url: FetchInput, _init?: RequestInit) => {
expect(url).toBe(CODEX_COMPLETIONS_ORIGIN)
return sseResponse([
'data: {"type":"response.output_text.delta","delta":"hi"}\n\n',
@@ -300,7 +417,9 @@ describe('streamCodexCompletion', () => {
finalize,
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => frames.push(frame),
+ onFrame: frame => {
+ frames.push(frame)
+ },
})
expect(redeem).toHaveBeenCalledOnce()
@@ -319,18 +438,18 @@ describe('streamCodexCompletion', () => {
receipt: expect.objectContaining({ outcome: 'success', requestHash: REQUEST_HASH }),
})
)
- expect(String(fetchFn.mock.calls[0]?.[1]?.headers?.['authorization'])).toContain(
+ expect(String(headerOf(fetchFn.mock.calls[0]?.[1], 'authorization'))).toContain(
accessTokenFor('live')
)
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['originator']).toBe('evenfire')
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['openai-beta']).toBe('responses=v1')
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['session_id']).toBe('req-001')
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['chatgpt-account-id']).toBe('acct_live_1')
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'originator')).toBe('evenfire')
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'openai-beta')).toBe('responses=v1')
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'session_id')).toBe('req-001')
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'chatgpt-account-id')).toBe('acct_live_1')
expect(String(fetchFn.mock.calls[0]?.[1]?.body)).toContain('"store":false')
})
it('flushes a completed event that arrives without a trailing blank line', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse([
'data: {"type":"response.completed","response":{"usage":{"input_tokens":1,"output_tokens":1}}}',
])
@@ -360,7 +479,7 @@ describe('streamCodexCompletion', () => {
})
it('parses CRLF-delimited SSE frames', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse([
'data: {"type":"response.completed","response":{"usage":{"input_tokens":4,"output_tokens":5}}}\r\n\r\n',
])
@@ -390,7 +509,7 @@ describe('streamCodexCompletion', () => {
})
it('uses the redeemed ChatGPT account id when the access token is opaque', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
await streamCodexCompletion({
@@ -408,17 +527,17 @@ describe('streamCodexCompletion', () => {
redeemSuccess({ accessToken: 'opaque-token', chatgptAccountId: 'acct_from_id_token' }),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
})
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['chatgpt-account-id']).toBe('acct_from_id_token')
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'chatgpt-account-id')).toBe('acct_from_id_token')
})
it('keeps the redeemed ChatGPT account id when the access token JWT names another account', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
await streamCodexCompletion({
@@ -439,13 +558,13 @@ describe('streamCodexCompletion', () => {
}),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
})
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['chatgpt-account-id']).toBe('acct_stored')
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'chatgpt-account-id')).toBe('acct_stored')
})
it('refuses to fetch completions when the access token has no ChatGPT account id', async () => {
@@ -465,7 +584,7 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess({ accessToken: 'opaque-token' }),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'error',
+ outcome: 'error' as const,
duplicate: false,
})),
fetchFn,
@@ -516,7 +635,7 @@ describe('streamCodexCompletion', () => {
redeemSuccess({ transport: { ...redeemSuccess().transport, servedModel: 'other' } }),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'error',
+ outcome: 'error' as const,
duplicate: false,
})),
fetchFn: vi.fn(),
@@ -545,7 +664,7 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'error',
+ outcome: 'error' as const,
duplicate: false,
})),
fetchFn,
@@ -578,7 +697,7 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -604,10 +723,12 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'error',
+ outcome: 'error' as const,
duplicate: false,
})),
- fetchFn: vi.fn(async () => new Response('denied', { status: 401 })),
+ fetchFn: vi.fn(
+ async (_url: FetchInput, _init?: RequestInit) => new Response('denied', { status: 401 })
+ ),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
})
).rejects.toMatchObject({ code: 'connection_unavailable' })
@@ -665,7 +786,7 @@ describe('streamCodexCompletion', () => {
tokens.push(input.executionTicket)
return redeemSuccess({ accessToken: accessTokenFor(input.executionTicket) })
})
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
const ticket = {
@@ -683,7 +804,7 @@ describe('streamCodexCompletion', () => {
redeem,
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -697,23 +818,23 @@ describe('streamCodexCompletion', () => {
redeem,
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
})
expect(tokens).toEqual(['t-a', 't-b'])
- expect(String(fetchFn.mock.calls[0]?.[1]?.headers?.['authorization'])).toContain(
+ expect(String(headerOf(fetchFn.mock.calls[0]?.[1], 'authorization'))).toContain(
accessTokenFor('t-a')
)
- expect(String(fetchFn.mock.calls[1]?.[1]?.headers?.['authorization'])).toContain(
+ expect(String(headerOf(fetchFn.mock.calls[1]?.[1], 'authorization'))).toContain(
accessTokenFor('t-b')
)
})
it('does not retry after an ambiguous upstream response', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.output_text.delta","delta":"partial"}\n\n'])
)
const result = await streamCodexCompletion({
@@ -730,7 +851,7 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'unknown',
+ outcome: 'unknown' as const,
duplicate: false,
})),
fetchFn,
@@ -766,7 +887,7 @@ describe('streamCodexCompletion', () => {
transportHints: { promptCacheKey: 'sess-1' },
}
const requestHash = hashCodexCompletionRequestV1(request)
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
await streamCodexCompletion({
@@ -783,7 +904,7 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -885,7 +1006,9 @@ describe('streamCodexCompletion', () => {
}),
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => emitted.push(frame),
+ onFrame: frame => {
+ emitted.push(frame)
+ },
})
expect(result.outcome).toBe('success')
expect(emitted).toContainEqual({ type: 'tool_call', id: 'new-call', name, arguments: {} })
@@ -934,7 +1057,9 @@ describe('streamCodexCompletion', () => {
finalize,
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => emitted.push(frame),
+ onFrame: frame => {
+ emitted.push(frame)
+ },
})
).rejects.toMatchObject({
code: 'provider_unavailable',
@@ -950,7 +1075,7 @@ describe('streamCodexCompletion', () => {
})
it('omits Notify-like generation fields on the Responses wire', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
await streamCodexCompletion({
@@ -967,7 +1092,7 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -991,7 +1116,7 @@ describe('streamCodexCompletion', () => {
generation: { maxOutputTokens: 4096, temperature: 0.2 },
}
const requestHash = hashCodexCompletionRequestV1(request)
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
await streamCodexCompletion({
@@ -1008,7 +1133,7 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -1022,11 +1147,13 @@ describe('streamCodexCompletion', () => {
})
it('maps upstream 400 to invalid_request and finalizes error without usage', async () => {
- const finalize = vi.fn(async () => ({
- providerAttemptId: 'att-1',
- outcome: 'error' as const,
- duplicate: false,
- }))
+ const finalize = vi.fn(
+ async (_input: Parameters<StreamCodexCompletionInput['finalize']>[0]) => ({
+ providerAttemptId: 'att-1',
+ outcome: 'error' as const,
+ duplicate: false,
+ })
+ )
await expect(
streamCodexCompletion({
executionTicket: 'ticket-1',
@@ -1041,7 +1168,10 @@ describe('streamCodexCompletion', () => {
},
redeem: async () => redeemSuccess(),
finalize,
- fetchFn: vi.fn(async () => new Response('bad request', { status: 400 })),
+ fetchFn: vi.fn(
+ async (_url: FetchInput, _init?: RequestInit) =>
+ new Response('bad request', { status: 400 })
+ ),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
})
).rejects.toMatchObject({ code: 'invalid_request' })
@@ -1055,7 +1185,7 @@ describe('streamCodexCompletion', () => {
it('emits a tool call only after argument deltas complete', async () => {
const frames: unknown[] = []
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse([
'data: {"type":"response.output_item.added","item":{"type":"function_call","id":"item-1","call_id":"call-9","name":"lookup","arguments":""}}\n\n',
'data: {"type":"response.function_call_arguments.delta","item_id":"item-1","delta":"{\\"q\\":"}}\n\n',
@@ -1078,12 +1208,14 @@ describe('streamCodexCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => frames.push(frame),
+ onFrame: frame => {
+ frames.push(frame)
+ },
})
expect(frames).toEqual([
{ type: 'tool_call', id: 'call-9', name: 'lookup', arguments: { q: 'x' } },
diff --git a/codex-llm-proxy/test/controlApiClient.test.ts b/codex-llm-proxy/test/controlApiClient.test.ts
index bd6a0f57c..9f47ad989 100644
--- a/codex-llm-proxy/test/controlApiClient.test.ts
+++ b/codex-llm-proxy/test/controlApiClient.test.ts
@@ -1,6 +1,7 @@
import { createServer, type IncomingMessage, type Server } from 'node:http'
import { describe, expect, it } from 'vitest'
import { ControlApiClient, ControlApiClientError } from '../src/controlApiClient.js'
+import { CODEX_CATALOG_ORIGIN, CODEX_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
const LOOPBACK_V4 = ['127', '0', '0', '1'].join('.')
@@ -62,6 +63,17 @@ describe('ControlApiClient', () => {
if (String(req.url).endsWith('/redeem')) {
seenTokens.push(String((body as { executionTicket: string }).executionTicket))
}
+ if (String(req.url).endsWith('/finalize')) {
+ // control-api echoes the persisted terminal outcome on finalize.
+ const raw = res as unknown as {
+ statusCode: number
+ setHeader: (name: string, value: string) => void
+ end: (chunk: string) => void
+ }
+ raw.statusCode = 200
+ raw.setHeader('content-type', 'application/json')
+ raw.end(JSON.stringify({ providerAttemptId: 'att-1', outcome: 'success', duplicate: false }))
+ }
})
try {
const client = new ControlApiClient({
@@ -127,3 +139,118 @@ describe('ControlApiClient', () => {
}
})
})
+
+describe('ControlApiClient response hardening', () => {
+ function jsonServer(body: unknown) {
+ return listen((_req, _body, res) => {
+ const raw = res as unknown as {
+ statusCode: number
+ setHeader: (name: string, value: string) => void
+ end: (chunk: string) => void
+ }
+ raw.statusCode = 200
+ raw.setHeader('content-type', 'application/json')
+ raw.end(JSON.stringify(body))
+ })
+ }
+
+ function client(url: string): ControlApiClient {
+ return new ControlApiClient({
+ baseUrl: `${url}/api/v1`,
+ serviceName: 'codex-llm-proxy',
+ serviceToken: 'dev-codex-llm-proxy-token',
+ })
+ }
+
+ const receipt = {
+ schemaVersion: 'codex-attempt-receipt.v1' as const,
+ providerAttemptId: 'att-1',
+ requestHash: 'b'.repeat(64),
+ outcome: 'success' as const,
+ }
+
+ it.each([['bogus'], [42], [null]])(
+ 'maps an unrecognized finalize outcome %j to unknown, never success',
+ async outcome => {
+ const server = await jsonServer({ providerAttemptId: 'att-1', outcome, duplicate: false })
+ try {
+ const finalized = await client(server.url).finalize({
+ attemptReceipt: 'a'.repeat(64),
+ receipt,
+ })
+ expect(finalized.outcome).toBe('unknown')
+ } finally {
+ await server.close()
+ }
+ }
+ )
+
+ it.each(['success', 'canceled', 'error', 'unknown'] as const)(
+ 'passes through the recognized finalize outcome %s',
+ async outcome => {
+ const server = await jsonServer({ providerAttemptId: 'att-1', outcome, duplicate: true })
+ try {
+ const finalized = await client(server.url).finalize({
+ attemptReceipt: 'a'.repeat(64),
+ receipt,
+ })
+ expect(finalized).toEqual({ providerAttemptId: 'att-1', outcome, duplicate: true })
+ } finally {
+ await server.close()
+ }
+ }
+ )
+
+ function redeemBody(maxStreamDurationMs: unknown): Record<string, unknown> {
+ return {
+ accessToken: 'tok-live',
+ transport: {
+ protocolVersion: 'codex-subscription-transport.v1',
+ completionsOrigin: CODEX_COMPLETIONS_ORIGIN,
+ catalogOrigin: CODEX_CATALOG_ORIGIN,
+ operation: 'completion_stream',
+ servedModel: 'gpt-5.1',
+ ...(maxStreamDurationMs === undefined ? {} : { maxStreamDurationMs }),
+ },
+ expiryClass: 'short_lived',
+ attemptReceipt: 'a'.repeat(64),
+ }
+ }
+
+ it.each([[0], [-1], [-300_000], [null], ['300000']])(
+ 'rejects a redeem transport maxStreamDurationMs of %j as provider_unavailable',
+ async value => {
+ const server = await jsonServer(redeemBody(value))
+ try {
+ await expect(
+ client(server.url).redeem({
+ executionTicket: 'ticket-1',
+ requestHash: 'b'.repeat(64),
+ operation: 'completion_stream',
+ })
+ ).rejects.toMatchObject({ code: 'provider_unavailable' })
+ } finally {
+ await server.close()
+ }
+ }
+ )
+
+ it('keeps a positive maxStreamDurationMs and defaults an absent one to 300000', async () => {
+ const positive = await jsonServer(redeemBody(120_000))
+ const absent = await jsonServer(redeemBody(undefined))
+ try {
+ const input = {
+ executionTicket: 'ticket-1',
+ requestHash: 'b'.repeat(64),
+ operation: 'completion_stream' as const,
+ }
+ expect((await client(positive.url).redeem(input)).transport.maxStreamDurationMs).toBe(
+ 120_000
+ )
+ expect((await client(absent.url).redeem(input)).transport.maxStreamDurationMs).toBe(300_000)
+ } finally {
+ await positive.close()
+ await absent.close()
+ }
+ })
+})
diff --git a/codex-llm-proxy/test/requestLimits.test.ts b/codex-llm-proxy/test/requestLimits.test.ts
new file mode 100644
index 000000000..ed7ec59fa
--- /dev/null
+++ b/codex-llm-proxy/test/requestLimits.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { RequestLimitError, StreamGate } from '../src/requestLimits.js'
+
+describe('StreamGate', () => {
+ it('admits a queued waiter once a running stream releases', async () => {
+ const gate = new StreamGate(1, 1)
+ const release = await gate.acquire()
+ let admitted = false
+ const queued = gate.acquire().then(next => {
+ admitted = true
+ return next
+ })
+ await new Promise(resolve => setTimeout(resolve, 30))
+ expect(admitted).toBe(false)
+ release()
+ const releaseQueued = await queued
+ expect(admitted).toBe(true)
+ releaseQueued()
+ })
+
+ it('rejects immediately without taking a slot when the signal is already aborted', async () => {
+ const gate = new StreamGate(1, 1)
+ const abort = new AbortController()
+ abort.abort()
+ await expect(gate.acquire(abort.signal)).rejects.toBeInstanceOf(RequestLimitError)
+ // The running slot was not consumed: a fresh caller is admitted at once.
+ const release = await Promise.race([
+ gate.acquire(),
+ new Promise<never>((_, reject) =>
+ setTimeout(() => reject(new Error('slot leaked by aborted caller')), 100)
+ ),
+ ])
+ release()
+ })
+
+ it('rejects a queued waiter when its client aborts and frees the queue slot', async () => {
+ const gate = new StreamGate(1, 1)
+ const release = await gate.acquire()
+ const abort = new AbortController()
+ const queued = gate.acquire(abort.signal)
+ abort.abort()
+ await expect(
+ Promise.race([
+ queued,
+ new Promise<never>((_, reject) =>
+ setTimeout(() => reject(new Error('queued waiter ignored abort')), 200)
+ ),
+ ])
+ ).rejects.toBeInstanceOf(RequestLimitError)
+ // The queue slot is free again, so a new waiter queues instead of "queue is full".
+ const next = gate.acquire()
+ release()
+ const releaseNext = await next
+ releaseNext()
+ })
+})
diff --git a/codex-llm-proxy/test/server.security.test.ts b/codex-llm-proxy/test/server.security.test.ts
index 40156c8d5..f052b12c3 100644
--- a/codex-llm-proxy/test/server.security.test.ts
+++ b/codex-llm-proxy/test/server.security.test.ts
@@ -1,10 +1,15 @@
import { generateKeyPairSync } from 'node:crypto'
import jwt from 'jsonwebtoken'
import request from 'supertest'
+import {
+ hashCodexCompletionRequestV1,
+ parseCodexCompletionRequestV1,
+} from '@clerum/llm-provider-attempt-contract'
import { describe, expect, it } from 'vitest'
import { verifyAdminPermit } from '../src/auth/adminPermitVerifier.js'
import { verifyExecutionTicket } from '../src/auth/executionTicketVerifier.js'
import { loadConfig, type CodexLlmProxyConfig } from '../src/config.js'
+import { ControlApiClient, ControlApiClientError } from '../src/controlApiClient.js'
import { createProxyApps } from '../src/server.js'
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
@@ -282,3 +287,162 @@ describe('codex-llm-proxy security surface', () => {
).toThrow(/bounded positive integer/)
})
})
+
+describe('codex-llm-proxy execution kill switch', () => {
+ const lookup = async () => [{ address: '1.2.3.4', family: 4 }]
+
+ function validCompletionBody(): Record<string, unknown> {
+ const raw = {
+ schemaVersion: 'codex-completion-request.v1',
+ requestId: 'req-kill-switch',
+ idempotencyKey: 'idem-kill-switch',
+ provider: 'codex-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'hello' }],
+ }
+ const parsed = parseCodexCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashCodexCompletionRequestV1(parsed.value)
+ const executionTicket = sign(
+ {
+ jti: '33333333-3333-4333-8333-333333333333',
+ typ: 'codex-execution-ticket',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId: 'att-kill-switch',
+ },
+ 'codex-llm-proxy'
+ )
+ return { executionTicket, requestHash, request: raw }
+ }
+
+ function recordingClient(): { client: ControlApiClient; redeems: unknown[] } {
+ const redeems: unknown[] = []
+ const client = {
+ async redeem(input: unknown) {
+ redeems.push(input)
+ throw new ControlApiClientError('no_grant', 'no grant in kill-switch test')
+ },
+ async finalize() {
+ throw new Error('finalize must not run in kill-switch test')
+ },
+ } as unknown as ControlApiClient
+ return { client, redeems }
+ }
+
+ it('returns 404 disabled for a fully valid runtime JWT + ticket when execution is disabled', async () => {
+ const body = validCompletionBody()
+
+ // Liveness witness: the identical request reaches redeem when enabled.
+ const enabled = recordingClient()
+ const live = createProxyApps(config({ executionEnabled: true, maxBodyBytes: 65_536 }), {
+ controlApiClient: enabled.client,
+ lookup,
+ })
+ const reached = await request(live.runtimeApp)
+ .post('/internal/runtime/v1/codex/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send(body)
+ expect(reached.status).toBe(403)
+ expect(JSON.parse(reached.text)).toEqual({ error: 'no_grant' })
+ expect(enabled.redeems).toHaveLength(1)
+
+ const disabled = recordingClient()
+ const off = createProxyApps(config({ executionEnabled: false, maxBodyBytes: 65_536 }), {
+ controlApiClient: disabled.client,
+ lookup,
+ })
+ const res = await request(off.runtimeApp)
+ .post('/internal/runtime/v1/codex/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send(body)
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'disabled' })
+ expect(disabled.redeems).toHaveLength(0)
+ })
+
+ it('returns 404 disabled for a valid admin permit when execution is disabled', async () => {
+ const upstream = () =>
+ new Response(JSON.stringify({ data: [{ id: 'gpt-5.1' }] }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+
+ // Liveness witness: the identical admin call reaches the catalog upstream when enabled.
+ let enabledCalls = 0
+ const live = createProxyApps(config({ executionEnabled: true, maxBodyBytes: 65_536 }), {
+ fetchFn: (async () => {
+ enabledCalls += 1
+ return upstream()
+ }) as typeof fetch,
+ lookup,
+ })
+ const reached = await request(live.adminApp)
+ .post('/internal/admin/v1/codex/models')
+ .set('Authorization', `Bearer ${adminPermit()}`)
+ .send({ accessToken: 'tok' })
+ expect(reached.status).toBe(200)
+ expect(reached.body.outcome).toBe('ready')
+ expect(enabledCalls).toBe(1)
+
+ let disabledCalls = 0
+ const off = createProxyApps(config({ executionEnabled: false, maxBodyBytes: 65_536 }), {
+ fetchFn: (async () => {
+ disabledCalls += 1
+ return upstream()
+ }) as typeof fetch,
+ lookup,
+ })
+ const res = await request(off.adminApp)
+ .post('/internal/admin/v1/codex/models')
+ .set('Authorization', `Bearer ${adminPermit()}`)
+ .send({ accessToken: 'tok' })
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'disabled' })
+ expect(disabledCalls).toBe(0)
+ })
+})
+
+describe('codex-llm-proxy startup config', () => {
+ const base = {
+ CODEX_LLM_PROXY_JWT_PUBLIC_KEY: publicKey,
+ CODEX_LLM_PROXY_CONTROL_API_URL:
+ 'http://control-api-rpc-gateway.control-plane.svc.cluster.local:8090/api/v1',
+ CODEX_LLM_PROXY_CONTROL_API_TOKEN: 'dev-codex-llm-proxy-token',
+ }
+
+ it('loads a complete environment', () => {
+ const loaded = loadConfig(base)
+ expect(loaded.controlApiBaseUrl).toBe(base.CODEX_LLM_PROXY_CONTROL_API_URL)
+ expect(loaded.controlApiServiceToken).toBe('dev-codex-llm-proxy-token')
+ expect(loaded.controlApiServiceName).toBe('codex-llm-proxy')
+ })
+
+ it.each([undefined, '', ' '])(
+ 'fails at startup when the control-api URL is %j',
+ value => {
+ expect(() => loadConfig({ ...base, CODEX_LLM_PROXY_CONTROL_API_URL: value })).toThrow(
+ /CODEX_LLM_PROXY_CONTROL_API_URL/
+ )
+ }
+ )
+
+ it.each(['not a url', 'ftp://control-api/api/v1', 'file:///etc/passwd'])(
+ 'fails at startup when the control-api URL %j is not http(s)',
+ value => {
+ expect(() => loadConfig({ ...base, CODEX_LLM_PROXY_CONTROL_API_URL: value })).toThrow(
+ /CODEX_LLM_PROXY_CONTROL_API_URL/
+ )
+ }
+ )
+
+ it.each([undefined, '', ' '])(
+ 'fails at startup when the control-api service token is %j',
+ value => {
+ expect(() => loadConfig({ ...base, CODEX_LLM_PROXY_CONTROL_API_TOKEN: value })).toThrow(
+ /CODEX_LLM_PROXY_CONTROL_API_TOKEN/
+ )
+ }
+ )
+})
diff --git a/codex-llm-proxy/test/sseBackpressure.test.ts b/codex-llm-proxy/test/sseBackpressure.test.ts
new file mode 100644
index 000000000..7902b39b5
--- /dev/null
+++ b/codex-llm-proxy/test/sseBackpressure.test.ts
@@ -0,0 +1,274 @@
+import { describe, expect, it } from 'vitest'
+import jwt from 'jsonwebtoken'
+import { generateKeyPairSync } from 'node:crypto'
+import { EventEmitter } from 'node:events'
+import { request as httpRequest } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import {
+ 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 { createProxyApps, writeSseChunk } from '../src/server.js'
+
+function fakeResponse(writeResult: boolean) {
+ const written: string[] = []
+ const res = Object.assign(new EventEmitter(), {
+ destroyed: false,
+ write(chunk: string) {
+ written.push(chunk)
+ return writeResult
+ },
+ })
+ return { res, written }
+}
+
+async function settled(promise: Promise<unknown>, withinMs = 30): Promise<boolean> {
+ let done = false
+ void promise.then(() => {
+ done = true
+ })
+ await new Promise(resolve => setTimeout(resolve, withinMs))
+ return done
+}
+
+describe('writeSseChunk backpressure', () => {
+ it('does not wait when the socket accepted the chunk', async () => {
+ const { res, written } = fakeResponse(true)
+ const pending = writeSseChunk(res as never, 'data: {}\n\n', new AbortController().signal)
+ expect(pending).toBeUndefined()
+ expect(written).toEqual(['data: {}\n\n'])
+ })
+
+ it('waits for drain when res.write reports a full buffer', async () => {
+ const { res } = fakeResponse(false)
+ const pending = writeSseChunk(res as never, 'data: {}\n\n', new AbortController().signal)
+ expect(pending).toBeInstanceOf(Promise)
+ expect(await settled(pending as Promise<void>)).toBe(false)
+ res.emit('drain')
+ expect(await settled(pending as Promise<void>)).toBe(true)
+ })
+
+ it('stops waiting when the client closes or the stream aborts', async () => {
+ const closed = fakeResponse(false)
+ const onClose = writeSseChunk(closed.res as never, 'x', new AbortController().signal)
+ closed.res.emit('close')
+ expect(await settled(onClose as Promise<void>)).toBe(true)
+
+ const aborted = fakeResponse(false)
+ const abort = new AbortController()
+ const onAbort = writeSseChunk(aborted.res as never, 'x', abort.signal)
+ abort.abort()
+ expect(await settled(onAbort as Promise<void>)).toBe(true)
+ })
+})
+
+const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+ modulusLength: 2048,
+ publicKeyEncoding: { type: 'spki', format: 'pem' },
+ privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+})
+
+function sign(payload: Record<string, unknown>, audience: string): string {
+ return jwt.sign(payload, privateKey, {
+ algorithm: 'RS256',
+ issuer: 'control-api',
+ audience,
+ expiresIn: 60,
+ })
+}
+
+function config(): CodexLlmProxyConfig {
+ return {
+ runtimePort: 0,
+ adminPort: 0,
+ probePort: 0,
+ maxBodyBytes: 1_048_576,
+ 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 DELTA_BYTES = 64 * 1024
+const DELTA_COUNT = 1000
+const TOTAL_BYTES = DELTA_BYTES * DELTA_COUNT
+
+describe('slow SSE consumer', () => {
+ it('stops pulling the upstream while the client is not reading, then delivers everything', async () => {
+ const hostRef = 'research-host'
+ const raw = {
+ schemaVersion: 'codex-completion-request.v1',
+ requestId: 'req-backpressure',
+ idempotencyKey: 'idem-backpressure',
+ provider: 'codex-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'stream a lot' }],
+ }
+ const parsed = parseCodexCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashCodexCompletionRequestV1(parsed.value)
+
+ const finalizes: string[] = []
+ const client = {
+ async redeem(): Promise<RedeemAttemptSuccess> {
+ return {
+ accessToken: 'test-access-backpressure',
+ chatgptAccountId: 'acct-backpressure',
+ 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> {
+ finalizes.push(input.receipt.outcome)
+ return {
+ providerAttemptId: input.receipt.providerAttemptId,
+ outcome: input.receipt.outcome,
+ duplicate: false,
+ }
+ },
+ } as unknown as ControlApiClient
+
+ const delta = 'x'.repeat(DELTA_BYTES)
+ const encoder = new TextEncoder()
+ let pulledDeltas = 0
+ const fetchFn = (async () => {
+ let sentCompleted = false
+ const body = new ReadableStream<Uint8Array>(
+ {
+ pull(controller) {
+ if (pulledDeltas < DELTA_COUNT) {
+ pulledDeltas += 1
+ controller.enqueue(
+ encoder.encode(
+ `data: ${JSON.stringify({ type: 'response.output_text.delta', delta })}\n\n`
+ )
+ )
+ return
+ }
+ if (!sentCompleted) {
+ sentCompleted = true
+ controller.enqueue(
+ encoder.encode('data: {"type":"response.completed","response":{"usage":{}}}\n\n')
+ )
+ return
+ }
+ controller.close()
+ },
+ },
+ { highWaterMark: 0 }
+ )
+ return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } })
+ }) as typeof fetch
+
+ const servers = createProxyApps(config(), {
+ 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
+ try {
+ const payload = JSON.stringify({
+ executionTicket: sign(
+ {
+ jti: '44444444-4444-4444-8444-444444444444',
+ typ: 'codex-execution-ticket',
+ hostRef,
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId: 'att-backpressure',
+ },
+ 'codex-llm-proxy'
+ ),
+ requestHash,
+ request: raw,
+ })
+ const platform = sign(
+ {
+ sub: `default/${hostRef}`,
+ hostRefs: [hostRef],
+ workflowControlScopes: ['llm:codex:execute'],
+ scope: 'workflow:approval:request',
+ },
+ 'workflow-approvals'
+ )
+
+ const text = await new Promise<string>((resolve, reject) => {
+ const req = httpRequest(
+ {
+ host: '127.0.0.1',
+ port,
+ method: 'POST',
+ path: '/internal/runtime/v1/codex/completions',
+ headers: {
+ 'content-type': 'application/json',
+ authorization: `Bearer ${platform}`,
+ 'content-length': Buffer.byteLength(payload),
+ },
+ },
+ res => {
+ // Slow consumer: stop reading immediately and wait for the proxy
+ // to settle before asserting how much upstream it consumed.
+ res.pause()
+ void (async () => {
+ let last = -1
+ const deadline = Date.now() + 5_000
+ while (Date.now() < deadline) {
+ await new Promise(r => setTimeout(r, 250))
+ if (pulledDeltas === last) break
+ last = pulledDeltas
+ }
+ try {
+ expect(pulledDeltas * DELTA_BYTES).toBeLessThan(TOTAL_BYTES / 2)
+ } catch (err) {
+ res.destroy()
+ reject(err)
+ return
+ }
+ const chunks: Buffer[] = []
+ res.on('data', chunk => chunks.push(chunk as Buffer))
+ res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+ res.on('error', reject)
+ res.resume()
+ })()
+ }
+ )
+ req.on('error', reject)
+ req.end(payload)
+ })
+
+ expect(pulledDeltas).toBe(DELTA_COUNT)
+ const frames = text
+ .split('\n\n')
+ .filter(part => part.startsWith('data: '))
+ .map(part => JSON.parse(part.slice(6)) as { type: string; outcome?: string })
+ expect(frames.filter(frame => frame.type === 'text')).toHaveLength(DELTA_COUNT)
+ expect(frames.at(-1)).toMatchObject({ type: 'done', outcome: 'success' })
+ expect(finalizes).toEqual(['success'])
+ } finally {
+ await servers.close()
+ }
+ }, 30_000)
+})
diff --git a/codex-llm-proxy/tsconfig.test.json b/codex-llm-proxy/tsconfig.test.json
new file mode 100644
index 000000000..c8c4f5393
--- /dev/null
+++ b/codex-llm-proxy/tsconfig.test.json
@@ -0,0 +1,14 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "noEmit": true,
+ "rootDir": ".",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "lib": ["ES2023"],
+ "declaration": false,
+ "sourceMap": false
+ },
+ "include": ["src/**/*", "test/**/*", "vitest.config.ts"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/grok-llm-proxy/package.json b/grok-llm-proxy/package.json
index c0c9b3d44..21c2fe3e0 100644
--- a/grok-llm-proxy/package.json
+++ b/grok-llm-proxy/package.json
@@ -8,9 +8,10 @@
},
"scripts": {
"build": "tsc -p tsconfig.build.json",
- "typecheck": "tsc --noEmit",
+ "typecheck": "tsc --noEmit && npm run typecheck:test",
+ "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
"start": "node dist/main.js",
- "test": "vitest run",
+ "test": "npm run typecheck:test && vitest run",
"test:watch": "vitest"
},
"license": "SEE LICENSE IN LICENSE",
diff --git a/grok-llm-proxy/src/config.ts b/grok-llm-proxy/src/config.ts
index 804b4d782..92f8d3996 100644
--- a/grok-llm-proxy/src/config.ts
+++ b/grok-llm-proxy/src/config.ts
@@ -32,6 +32,29 @@ function requiredPem(name: string, raw: string | undefined): string {
return value
}
+// Fail at startup instead of at the first redeem. Messages name the variable
+// only; the raw value (URL or service token) is never echoed.
+function requiredHttpUrl(name: string, raw: string | undefined): string {
+ const value = raw?.trim() ?? ''
+ if (!value) throw new Error(`${name} must be set`)
+ let parsed: URL
+ try {
+ parsed = new URL(value)
+ } catch {
+ throw new Error(`${name} must be an absolute http(s) URL`)
+ }
+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+ throw new Error(`${name} must be an absolute http(s) URL`)
+ }
+ return value
+}
+
+function requiredNonEmpty(name: string, raw: string | undefined): string {
+ const value = raw?.trim() ?? ''
+ if (!value) throw new Error(`${name} must be set`)
+ return value
+}
+
export function loadConfig(env: NodeJS.ProcessEnv = process.env): GrokLlmProxyConfig {
return {
runtimePort: requiredPositiveInt(
@@ -67,8 +90,14 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): GrokLlmProxyCo
jwtIssuer: env.GROK_LLM_PROXY_JWT_ISSUER?.trim() || 'control-api',
jwtPublicKey: requiredPem('GROK_LLM_PROXY_JWT_PUBLIC_KEY', env.GROK_LLM_PROXY_JWT_PUBLIC_KEY),
executionEnabled: env.GROK_LLM_PROXY_EXECUTION_ENABLED === 'true',
- controlApiBaseUrl: env.GROK_LLM_PROXY_CONTROL_API_URL?.trim() || '',
+ controlApiBaseUrl: requiredHttpUrl(
+ 'GROK_LLM_PROXY_CONTROL_API_URL',
+ env.GROK_LLM_PROXY_CONTROL_API_URL
+ ),
controlApiServiceName: env.GROK_LLM_PROXY_CONTROL_API_SERVICE?.trim() || 'grok-llm-proxy',
- controlApiServiceToken: env.GROK_LLM_PROXY_CONTROL_API_TOKEN?.trim() || '',
+ controlApiServiceToken: requiredNonEmpty(
+ 'GROK_LLM_PROXY_CONTROL_API_TOKEN',
+ env.GROK_LLM_PROXY_CONTROL_API_TOKEN
+ ),
}
}
diff --git a/grok-llm-proxy/src/controlApiClient.ts b/grok-llm-proxy/src/controlApiClient.ts
index d7646964d..de023cce2 100644
--- a/grok-llm-proxy/src/controlApiClient.ts
+++ b/grok-llm-proxy/src/controlApiClient.ts
@@ -88,10 +88,7 @@ export class ControlApiClient {
}
return {
providerAttemptId: String(body.providerAttemptId ?? input.receipt.providerAttemptId),
- outcome:
- body.outcome === 'canceled' || body.outcome === 'error' || body.outcome === 'unknown'
- ? body.outcome
- : 'success',
+ outcome: parseFinalizeOutcome(body.outcome),
duplicate: body.duplicate === true,
}
}
@@ -142,6 +139,18 @@ function parseRedeem(body: unknown): RedeemAttemptSuccess {
throw new ControlApiClientError('provider_unavailable', 'redeem response is invalid')
}
const transport = body.transport
+ // Absent keeps the historical 300s default. A present value must be a
+ // finite positive number: zero/negative would reach AbortSignal.timeout as a
+ // RangeError, and a non-number is a control-api contract violation.
+ const maxStreamDurationMs =
+ transport.maxStreamDurationMs === undefined ? 300_000 : transport.maxStreamDurationMs
+ if (
+ typeof maxStreamDurationMs !== 'number' ||
+ !Number.isFinite(maxStreamDurationMs) ||
+ maxStreamDurationMs <= 0
+ ) {
+ throw new ControlApiClientError('provider_unavailable', 'redeem maxStreamDurationMs is invalid')
+ }
if (
transport.protocolVersion !== GROK_TRANSPORT_PROTOCOL ||
transport.completionsOrigin !== GROK_COMPLETIONS_ORIGIN ||
@@ -167,17 +176,20 @@ function parseRedeem(body: unknown): RedeemAttemptSuccess {
? transport.operation
: 'completion_stream',
servedModel: transport.servedModel,
- maxStreamDurationMs:
- typeof transport.maxStreamDurationMs === 'number' &&
- Number.isFinite(transport.maxStreamDurationMs)
- ? transport.maxStreamDurationMs
- : 300_000,
+ maxStreamDurationMs,
},
expiryClass: body.expiryClass === 'upstream_managed' ? 'upstream_managed' : 'short_lived',
attemptReceipt: body.attemptReceipt,
}
}
+/** Unrecognized finalize outcomes are ambiguous; never report them as success. */
+function parseFinalizeOutcome(raw: unknown): FinalizeAttemptSuccess['outcome'] {
+ return raw === 'success' || raw === 'canceled' || raw === 'error' || raw === 'unknown'
+ ? raw
+ : 'unknown'
+}
+
function isPlainObject(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
diff --git a/grok-llm-proxy/src/grokTransport.ts b/grok-llm-proxy/src/grokTransport.ts
index f75ec70d3..820a0e107 100644
--- a/grok-llm-proxy/src/grokTransport.ts
+++ b/grok-llm-proxy/src/grokTransport.ts
@@ -23,6 +23,13 @@ export type StreamFrame =
| { type: 'text'; text: string }
| { type: 'tool_call'; id: string; name: string; arguments: Record<string, unknown> }
+/**
+ * Receives mapped frames. Returning a promise signals client backpressure: the
+ * SSE reader stops pulling upstream bytes until it settles (or the stream
+ * aborts), so a slow consumer cannot make the proxy buffer an unbounded stream.
+ */
+export type FrameSink = (frame: StreamFrame) => void | Promise<void>
+
export type TransportTicket = {
jti: string
hostRef: string
@@ -31,6 +38,16 @@ export type TransportTicket = {
providerAttemptId: string
}
+/**
+ * PROBE-GATED (B-M10). The Codex `/responses` wire rejects sampling fields, and
+ * no live SuperGrok probe has yet confirmed that cli-chat-proxy.grok.com
+ * `/v1/responses` accepts `temperature`. Until that probe passes, keep
+ * `generation.temperature` in the authorize hash (request identity) but do
+ * not send it upstream. `max_output_tokens` is bound by the transport contract
+ * and is still sent. Flip to true only with recorded live-probe evidence.
+ */
+export const GROK_UPSTREAM_TEMPERATURE_PROBE_CONFIRMED: boolean = false
+
export class GrokTransportError extends Error {
constructor(
readonly code: string,
@@ -68,7 +85,7 @@ export type StreamGrokCompletionInput = {
}) => Promise<FinalizeAttemptSuccess>
fetchFn: typeof fetch
lookup?: OriginPolicyOptions['lookup']
- onFrame?: (frame: StreamFrame) => void
+ onFrame?: FrameSink
}
export type StreamGrokCompletionResult = {
@@ -91,6 +108,11 @@ export async function streamGrokCompletion(
if (request.model !== input.ticket.model) {
throw new GrokTransportError('model_not_allowed', 'request model does not match the ticket')
}
+ // A client that disconnected before dispatch must not consume the ticket:
+ // nothing was redeemed, so there is no attempt receipt to finalize.
+ if (input.signal?.aborted) {
+ return { outcome: 'canceled' }
+ }
const redeemed = await input.redeem({
executionTicket: input.executionTicket,
requestHash: input.requestHash,
@@ -187,7 +209,7 @@ async function readUpstreamStream(input: {
signal?: AbortSignal
fetchFn: typeof fetch
lookup?: OriginPolicyOptions['lookup']
- onFrame?: (frame: StreamFrame) => void
+ onFrame?: FrameSink
}): Promise<StreamGrokCompletionResult> {
const url = assertAllowedUpstreamUrl(GROK_COMPLETIONS_ORIGIN, 'completions')
const timeout = AbortSignal.timeout(input.deadlineMs)
@@ -299,7 +321,7 @@ function toUpstreamPayload(
if (request.generation?.maxOutputTokens) {
payload.max_output_tokens = request.generation.maxOutputTokens
}
- if (request.generation?.temperature !== undefined) {
+ if (GROK_UPSTREAM_TEMPERATURE_PROBE_CONFIRMED && request.generation?.temperature !== undefined) {
payload.temperature = request.generation.temperature
}
if (request.generation?.toolChoice) {
@@ -313,7 +335,7 @@ function toUpstreamPayload(
async function consumeSse(
body: ReadableStream<Uint8Array>,
- onFrame: ((frame: StreamFrame) => void) | undefined,
+ onFrame: FrameSink | undefined,
signal: AbortSignal,
names: ToolNameMap
): Promise<StreamGrokCompletionResult> {
@@ -323,7 +345,7 @@ async function consumeSse(
// Text stays streaming. Calls become executable only once the entire
// response succeeds and its independent call budget has been validated.
const toolFrames: Array<Extract<StreamFrame, { type: 'tool_call' }>> = []
- const acceptFrame = (frame?: StreamFrame) => {
+ const acceptFrame = async (frame?: StreamFrame): Promise<void> => {
if (pending.size > LIMITS.maxToolCalls) {
throw new GrokTransportError(
'provider_unavailable',
@@ -345,7 +367,7 @@ async function consumeSse(
)
}
toolFrames.push({ ...frame, name: canonicalName })
- } else if (frame) onFrame?.(frame)
+ } else if (frame) await deliverFrame(onFrame, frame, signal)
}
let buffer = ''
let completed = false
@@ -364,7 +386,7 @@ async function consumeSse(
buffer = parts.pop() ?? ''
for (const part of parts) {
const mapped = ingestSseBlock(part, pending)
- acceptFrame(mapped.frame)
+ await acceptFrame(mapped.frame)
if (mapped.usage) usage = mapped.usage
if (mapped.completed) completed = true
if (mapped.failed) failed = true
@@ -374,7 +396,7 @@ async function consumeSse(
buffer += decoder.decode().replace(/\r\n/g, '\n').replace(/\r/g, '\n')
if (buffer.trim()) {
const mapped = ingestSseBlock(buffer, pending)
- acceptFrame(mapped.frame)
+ await acceptFrame(mapped.frame)
if (mapped.usage) usage = mapped.usage
if (mapped.completed) completed = true
if (mapped.failed) failed = true
@@ -388,7 +410,7 @@ async function consumeSse(
for (const call of pending.values()) {
if (call.emitted) continue
const args = parseToolArguments(call.arguments)
- acceptFrame({ type: 'tool_call', id: call.id, name: call.name, arguments: args })
+ await acceptFrame({ type: 'tool_call', id: call.id, name: call.name, arguments: args })
call.emitted = true
}
if (signal.aborted) return { outcome: 'canceled', usage }
@@ -396,12 +418,36 @@ async function consumeSse(
throw new GrokTransportError('provider_unavailable', 'upstream response failed')
}
if (completed) {
- for (const frame of toolFrames) onFrame?.(frame)
+ for (const frame of toolFrames) await deliverFrame(onFrame, frame, signal)
return { outcome: 'success', usage }
}
return { outcome: 'unknown', usage }
}
+async function deliverFrame(
+ onFrame: FrameSink | undefined,
+ frame: StreamFrame,
+ signal: AbortSignal
+): Promise<void> {
+ const pending: unknown = onFrame?.(frame)
+ // Only a thenable signals backpressure; a `void` callback may return anything.
+ if (!(pending instanceof Promise) || signal.aborted) return
+ await new Promise<void>((resolve, reject) => {
+ const onAbort = () => resolve()
+ signal.addEventListener('abort', onAbort, { once: true })
+ pending.then(
+ () => {
+ signal.removeEventListener('abort', onAbort)
+ resolve()
+ },
+ err => {
+ signal.removeEventListener('abort', onAbort)
+ reject(err)
+ }
+ )
+ })
+}
+
function ingestSseBlock(
part: string,
pending: Map<string, PendingToolCall>
@@ -544,25 +590,47 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && Array.isArray(value) === false
}
+/**
+ * Bounds for the admin catalog/test upstream call: a hard deadline covering
+ * headers and body, a streamed body cap, and normalized-model caps aligned
+ * with control-api's catalog sync limits.
+ */
+export const CATALOG_LIMITS = {
+ timeoutMs: 15_000,
+ maxBodyBytes: 1_048_576,
+ maxModels: 256,
+ maxModelIdLength: 128,
+} as const
+
export async function listGrokModels(input: {
accessToken: string
fetchFn: typeof fetch
lookup?: OriginPolicyOptions['lookup']
+ /** Test seam; production uses CATALOG_LIMITS.timeoutMs. */
+ timeoutMs?: number
}): Promise<{
outcome: 'ready' | 'auth-rejected' | 'unavailable'
models: Array<{ model: string; displayName?: string }>
}> {
const url = assertAllowedUpstreamUrl(GROK_CATALOG_ORIGIN, 'catalog')
const headers = grokUpstreamHeaders(input.accessToken, { accept: 'application/json' })
- const response = await fetchFrozenOrigin({
- url,
- fetchFn: input.fetchFn,
- lookup: input.lookup,
- init: {
- method: 'GET',
- headers,
- },
- })
+ const signal = AbortSignal.timeout(input.timeoutMs ?? CATALOG_LIMITS.timeoutMs)
+ let response: Response
+ try {
+ response = await fetchFrozenOrigin({
+ url,
+ fetchFn: input.fetchFn,
+ lookup: input.lookup,
+ init: {
+ method: 'GET',
+ headers,
+ signal,
+ },
+ })
+ } catch (err) {
+ if (signal.aborted) throw catalogTimeoutError()
+ throw err
+ }
if (response.status === 401) return { outcome: 'auth-rejected', models: [] }
if (!response.ok) {
logger.warn(
@@ -571,7 +639,8 @@ export async function listGrokModels(input: {
)
return { outcome: 'unavailable', models: [] }
}
- const body = (await response.json()) as unknown
+ const raw = await readBoundedCatalogBody(response, signal)
+ const body = JSON.parse(raw) as unknown
return { outcome: 'ready', models: normalizeModels(body) }
}
@@ -579,6 +648,7 @@ export async function testGrokConnection(input: {
accessToken: string
fetchFn: typeof fetch
lookup?: OriginPolicyOptions['lookup']
+ timeoutMs?: number
}): Promise<{ outcome: 'ready' | 'auth-rejected' | 'unavailable' }> {
const listed = await listGrokModels(input)
return { outcome: listed.outcome }
@@ -593,10 +663,20 @@ function normalizeModels(body: unknown): Array<{ model: string; displayName?: st
? body.data
: []
const models: Array<{ model: string; displayName?: string }> = []
+ let droppedOverlongIds = 0
+ let droppedOverLimit = 0
for (const row of rows) {
if (!isPlainObject(row)) continue
const model = String(row.model || row.slug || row.id || '').trim()
if (!model) continue
+ if (model.length > CATALOG_LIMITS.maxModelIdLength) {
+ droppedOverlongIds += 1
+ continue
+ }
+ if (models.length >= CATALOG_LIMITS.maxModels) {
+ droppedOverLimit += 1
+ continue
+ }
const displayName =
typeof row.displayName === 'string'
? row.displayName
@@ -605,5 +685,60 @@ function normalizeModels(body: unknown): Array<{ model: string; displayName?: st
: undefined
models.push(displayName ? { model, displayName } : { model })
}
+ if (droppedOverlongIds > 0 || droppedOverLimit > 0) {
+ logger.warn(
+ {
+ event: 'grok_catalog_bounded',
+ received: rows.length,
+ accepted: models.length,
+ droppedOverlongIds,
+ droppedOverLimit,
+ },
+ 'Grok catalog response exceeded proxy bounds'
+ )
+ }
return models
}
+
+function catalogTimeoutError(): GrokTransportError {
+ return new GrokTransportError('provider_unavailable', 'catalog upstream deadline exceeded')
+}
+
+/** Read the catalog body under the deadline, cancelling past the byte cap. */
+async function readBoundedCatalogBody(response: Response, signal: AbortSignal): Promise<string> {
+ if (!response.body) return ''
+ const reader = response.body.getReader()
+ let onAbort: (() => void) | undefined
+ const aborted = new Promise<never>((_, reject) => {
+ onAbort = () => reject(catalogTimeoutError())
+ if (signal.aborted) onAbort()
+ else signal.addEventListener('abort', onAbort, { once: true })
+ })
+ aborted.catch(() => undefined)
+ const chunks: Uint8Array[] = []
+ let total = 0
+ try {
+ for (;;) {
+ const { done, value } = await Promise.race([reader.read(), aborted])
+ if (done) break
+ total += value.byteLength
+ if (total > CATALOG_LIMITS.maxBodyBytes) {
+ throw new GrokTransportError('provider_unavailable', 'catalog upstream body exceeds limit')
+ }
+ chunks.push(value)
+ }
+ } catch (err) {
+ await reader.cancel().catch(() => undefined)
+ if (err instanceof GrokTransportError) throw err
+ if (signal.aborted) throw catalogTimeoutError()
+ throw err
+ } finally {
+ if (onAbort) signal.removeEventListener('abort', onAbort)
+ try {
+ reader.releaseLock()
+ } catch {
+ // A pending read may still hold the lock after cancel; nothing to release.
+ }
+ }
+ return Buffer.concat(chunks).toString('utf8')
+}
diff --git a/grok-llm-proxy/src/requestLimits.ts b/grok-llm-proxy/src/requestLimits.ts
index 5ee10f58b..ba22dd3b7 100644
--- a/grok-llm-proxy/src/requestLimits.ts
+++ b/grok-llm-proxy/src/requestLimits.ts
@@ -35,23 +35,36 @@ export class StreamGate {
private queued = 0
constructor(
- private readonly maxConcurrent = STREAM_LIMITS.maxConcurrentStreams,
- private readonly maxQueued = STREAM_LIMITS.maxQueuedRequests
+ private readonly maxConcurrent: number = STREAM_LIMITS.maxConcurrentStreams,
+ private readonly maxQueued: number = STREAM_LIMITS.maxQueuedRequests
) {}
- async acquire(): Promise<() => void> {
+ /**
+ * Take a stream slot. When `signal` aborts (client disconnected) while the
+ * caller is still queued, the waiter is rejected and its queue slot freed, so
+ * a dropped client never proceeds to redeem an attempt.
+ */
+ async acquire(signal?: AbortSignal): Promise<() => void> {
+ if (signal?.aborted) throw new RequestLimitError('stream request was aborted')
if (this.running >= this.maxConcurrent) {
if (this.queued >= this.maxQueued) throw new RequestLimitError('stream queue is full')
this.queued += 1
try {
- await new Promise<void>(resolve => {
+ await new Promise<void>((resolve, reject) => {
+ let timer: ReturnType<typeof setTimeout> | undefined
+ const onAbort = () => {
+ if (timer !== undefined) clearTimeout(timer)
+ reject(new RequestLimitError('stream request was aborted'))
+ }
const wait = () => {
if (this.running < this.maxConcurrent) {
+ signal?.removeEventListener('abort', onAbort)
resolve()
return
}
- setTimeout(wait, 10)
+ timer = setTimeout(wait, 10)
}
+ signal?.addEventListener('abort', onAbort, { once: true })
wait()
})
} finally {
diff --git a/grok-llm-proxy/src/server.ts b/grok-llm-proxy/src/server.ts
index 8d9648e6e..38f26d81a 100644
--- a/grok-llm-proxy/src/server.ts
+++ b/grok-llm-proxy/src/server.ts
@@ -165,7 +165,7 @@ export function createProxyApps(
// Abort only when the client drops the response before we finish writing.
abortWhenClientDisconnects(req, res, abort)
try {
- release = await streamGate.acquire()
+ release = await streamGate.acquire(abort.signal)
res.status(200)
res.setHeader('content-type', 'text/event-stream')
res.setHeader('cache-control', 'no-cache')
@@ -188,9 +188,7 @@ export function createProxyApps(
finalize: input => client.finalize(input),
fetchFn,
lookup,
- onFrame: frame => {
- res.write(`data: ${JSON.stringify(frame)}\n\n`)
- },
+ onFrame: frame => writeSseChunk(res, `data: ${JSON.stringify(frame)}\n\n`, abort.signal),
})
res.write(
`data: ${JSON.stringify({ type: 'done', outcome: result.outcome, ...(result.usage ? { usage: result.usage } : {}) })}\n\n`
@@ -346,6 +344,32 @@ function mapError(err: unknown): { status: number; code: string } {
return { status: 503, code: 'provider_unavailable' }
}
+/**
+ * Write one SSE chunk and honor socket backpressure. Returns undefined when
+ * the chunk was accepted (hot path stays synchronous); otherwise a promise that
+ * settles on 'drain', or when the client closes / the stream aborts so a
+ * departed consumer never pins the stream slot.
+ */
+export function writeSseChunk(
+ res: Response,
+ chunk: string,
+ signal: AbortSignal
+): Promise<void> | undefined {
+ if (res.write(chunk)) return undefined
+ return new Promise<void>(resolve => {
+ const done = () => {
+ res.off('drain', done)
+ res.off('close', done)
+ signal.removeEventListener('abort', done)
+ resolve()
+ }
+ res.on('drain', done)
+ res.on('close', done)
+ signal.addEventListener('abort', done, { once: true })
+ if (signal.aborted || res.destroyed) done()
+ })
+}
+
export function abortWhenClientDisconnects(
req: Request,
res: Response,
diff --git a/grok-llm-proxy/src/toolNameMap.ts b/grok-llm-proxy/src/toolNameMap.ts
index 73a4fc7d1..2c0383172 100644
--- a/grok-llm-proxy/src/toolNameMap.ts
+++ b/grok-llm-proxy/src/toolNameMap.ts
@@ -1,7 +1,7 @@
import { createHash } from 'node:crypto'
// Conservative standard OpenAI function-name envelope. This is not evidence
-// that the Grok /grok/responses endpoint rejects wider canonical MCP names.
+// that the Grok /v1/responses endpoint rejects wider canonical MCP names.
const wireNamePattern = /^[A-Za-z0-9_-]{1,64}$/
export class ToolNameMap {
diff --git a/grok-llm-proxy/test/approvedToolsUpstream.test.ts b/grok-llm-proxy/test/approvedToolsUpstream.test.ts
index 5f12dcee0..9cc9fbb2f 100644
--- a/grok-llm-proxy/test/approvedToolsUpstream.test.ts
+++ b/grok-llm-proxy/test/approvedToolsUpstream.test.ts
@@ -72,6 +72,25 @@ async function complete(
}
describe('approved-tools isolated upstream boundary', () => {
+ it('measures explicit non-strict definitions without altering omitted or true values', async () => {
+ const simulator = createApprovedToolsUpstream()
+ const definitions = tools.map((tool, index) => ({
+ ...tool,
+ ...(index === 0 ? { strict: false } : index === 1 ? { strict: true } : {}),
+ }))
+ const before = JSON.stringify(definitions)
+ const result = await request(
+ simulator,
+ [{ role: 'user', content: 'verification receipt' }],
+ definitions
+ )
+ expect(result.response.status).toBe(200)
+ expect(simulator.evidence().requests).toMatchObject([
+ { definitionCount: 3, explicitNonStrictCount: 1 },
+ ])
+ expect(JSON.stringify(definitions)).toBe(before)
+ })
+
it('accepts the BasicSafety envelope with the real bridge execution target', async () => {
await complete(
createApprovedToolsUpstream(),
@@ -324,7 +343,7 @@ describe('approved-tools isolated upstream boundary', () => {
const catalog = await simulator.fetchFn('https://cli-chat-proxy.grok.com/v1/models')
expect(await catalog.json()).toMatchObject({ models: [{ slug: 'gpt-5.3-grok' }] })
for (const url of [
- 'http://cli-chat-proxy.grok.com/backend-api/grok/responses',
+ 'http://cli-chat-proxy.grok.com/v1/responses',
'https://example.com/',
URL + '/other',
]) {
diff --git a/grok-llm-proxy/test/approvedToolsUpstream.ts b/grok-llm-proxy/test/approvedToolsUpstream.ts
index 40358ddfe..7270532a4 100644
--- a/grok-llm-proxy/test/approvedToolsUpstream.ts
+++ b/grok-llm-proxy/test/approvedToolsUpstream.ts
@@ -287,6 +287,7 @@ export function createApprovedToolsUpstream() {
// Only bounded measurements, never request or result contents.
requests: [] as Array<{
definitionCount: number
+ explicitNonStrictCount: number
definitionBytes: number
inputBytes: number
connectorDefinitionCount: number
@@ -343,6 +344,7 @@ export function createApprovedToolsUpstream() {
).length
evidence.requests.push({
definitionCount: tools.length,
+ explicitNonStrictCount: tools.filter(tool => tool.strict === false).length,
definitionBytes: Buffer.byteLength(JSON.stringify(tools)),
inputBytes: Buffer.byteLength(JSON.stringify(payload.input)),
connectorDefinitionCount,
diff --git a/grok-llm-proxy/test/catalogBounds.test.ts b/grok-llm-proxy/test/catalogBounds.test.ts
new file mode 100644
index 000000000..413461c30
--- /dev/null
+++ b/grok-llm-proxy/test/catalogBounds.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest'
+import { CATALOG_LIMITS, listGrokModels, testGrokConnection } from '../src/grokTransport.js'
+
+const lookup = async () => [{ address: '1.2.3.4', family: 4 }]
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+}
+
+/** Rejects when the request has no deadline signal; otherwise hangs until it aborts. */
+const stalledFetch = (async (_url: unknown, init?: RequestInit) =>
+ new Promise<Response>((_, reject) => {
+ const signal = init?.signal
+ if (!signal) {
+ reject(new Error('catalog fetch carries no deadline signal'))
+ return
+ }
+ signal.addEventListener('abort', () => reject(signal.reason), { once: true })
+ })) as typeof fetch
+
+describe('Grok catalog upstream bounds', () => {
+ it('uses a 15s deadline, a 1 MiB body cap, and the control-api model caps', () => {
+ expect(CATALOG_LIMITS).toEqual({
+ timeoutMs: 15_000,
+ maxBodyBytes: 1_048_576,
+ maxModels: 256,
+ maxModelIdLength: 128,
+ })
+ })
+
+ it('lists a normal catalog', async () => {
+ const listed = await listGrokModels({
+ accessToken: 'tok',
+ fetchFn: (async () =>
+ jsonResponse({ data: [{ id: 'gpt-5.1', title: 'GPT 5.1' }] })) as typeof fetch,
+ lookup,
+ })
+ expect(listed).toEqual({
+ outcome: 'ready',
+ models: [{ model: 'gpt-5.1', displayName: 'GPT 5.1' }],
+ })
+ })
+
+ it('fails a stalled catalog request at the deadline instead of hanging', async () => {
+ await expect(
+ listGrokModels({ accessToken: 'tok', fetchFn: stalledFetch, lookup, timeoutMs: 50 })
+ ).rejects.toMatchObject({ code: 'provider_unavailable' })
+ await expect(
+ testGrokConnection({ accessToken: 'tok', fetchFn: stalledFetch, lookup, timeoutMs: 50 })
+ ).rejects.toMatchObject({ code: 'provider_unavailable' })
+ })
+
+ it('fails a catalog body that stalls after headers at the deadline', async () => {
+ const fetchFn = (async () =>
+ new Response(new ReadableStream<Uint8Array>({ pull: () => new Promise(() => {}) }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })) as typeof fetch
+ const started = Date.now()
+ await expect(
+ listGrokModels({ accessToken: 'tok', fetchFn, lookup, timeoutMs: 50 })
+ ).rejects.toMatchObject({ code: 'provider_unavailable' })
+ expect(Date.now() - started).toBeLessThan(2_000)
+ })
+
+ it('stops reading and fails a catalog body larger than the cap', async () => {
+ const chunk = new TextEncoder().encode(' '.repeat(64 * 1024))
+ let pulledBytes = 0
+ const fetchFn = (async () =>
+ new Response(
+ new ReadableStream<Uint8Array>(
+ {
+ pull(controller) {
+ // Finite (3x the cap) so a missing cap fails on the assertion, not OOM.
+ if (pulledBytes >= 3 * CATALOG_LIMITS.maxBodyBytes) {
+ controller.close()
+ return
+ }
+ pulledBytes += chunk.byteLength
+ controller.enqueue(chunk)
+ },
+ },
+ { highWaterMark: 0 }
+ ),
+ { status: 200, headers: { 'content-type': 'application/json' } }
+ )) as typeof fetch
+ await expect(listGrokModels({ accessToken: 'tok', fetchFn, lookup })).rejects.toMatchObject({
+ code: 'provider_unavailable',
+ })
+ expect(pulledBytes).toBeLessThanOrEqual(CATALOG_LIMITS.maxBodyBytes + 2 * chunk.byteLength)
+ })
+
+ it('caps the normalized catalog at 256 models and drops ids longer than 128 chars', async () => {
+ const overlong = 'm'.repeat(129)
+ const rows = [
+ { id: overlong },
+ { id: 'm'.repeat(128) },
+ ...Array.from({ length: 300 }, (_, index) => ({ id: `model-${index}` })),
+ ]
+ const listed = await listGrokModels({
+ accessToken: 'tok',
+ fetchFn: (async () => jsonResponse({ data: rows })) as typeof fetch,
+ lookup,
+ })
+ expect(listed.outcome).toBe('ready')
+ expect(listed.models).toHaveLength(256)
+ expect(listed.models.some(row => row.model === overlong)).toBe(false)
+ expect(listed.models[0]).toEqual({ model: 'm'.repeat(128) })
+ expect(listed.models.every(row => row.model.length <= 128)).toBe(true)
+ })
+})
diff --git a/grok-llm-proxy/test/contractFreeze.test.ts b/grok-llm-proxy/test/contractFreeze.test.ts
index cb9d43b1a..cd935e7e6 100644
--- a/grok-llm-proxy/test/contractFreeze.test.ts
+++ b/grok-llm-proxy/test/contractFreeze.test.ts
@@ -42,6 +42,7 @@ describe('grok-subscription contract freeze', () => {
expect(fixture.origins.catalog).toBe(GROK_CATALOG_ORIGIN)
expect(fixture.origins.oauthDevice).toBe('https://auth.x.ai/oauth2/device/code')
expect(fixture.origins.oauthToken).toBe('https://auth.x.ai/oauth2/token')
+ expect(fixture.origins.oauthRevoke).toBe('https://auth.x.ai/oauth2/revoke')
expect(fixture.supportedOperations).not.toContain('oauth_browser')
expect(fixture.supportedOperations).toContain('oauth_device')
expect(fixture.limits.maxToolCalls).toBe(LIMITS.maxToolCalls)
@@ -56,4 +57,23 @@ describe('grok-subscription contract freeze', () => {
expect(GROK_COMPLETIONS_ORIGIN).not.toContain('api.x.ai')
expect(GROK_CATALOG_ORIGIN).not.toContain('api.x.ai')
})
+
+ it('mirrors the exact OAuth origins control-api dials, including revoke', () => {
+ // control-api owns the OAuth client; the proxy never dials auth.x.ai. Cross-
+ // check the frozen fixture against control-api's exported constants by
+ // source so a drift in either side fails here without importing control-api.
+ const fixture = JSON.parse(readFileSync(fixturePath, 'utf8')) as {
+ origins: Record<string, string>
+ }
+ const oauthSource = readFileSync(
+ join(here, '../../control-api/src/services/grokSubscriptionOAuth.ts'),
+ 'utf8'
+ )
+ const constant = (name: string): string | undefined =>
+ new RegExp(`export const ${name} = '([^']+)'`).exec(oauthSource)?.[1]
+ expect(constant('GROK_OAUTH_DEVICE_URL')).toBe(fixture.origins.oauthDevice)
+ expect(constant('GROK_OAUTH_TOKEN_URL')).toBe(fixture.origins.oauthToken)
+ expect(constant('GROK_OAUTH_REVOKE_URL')).toBe(fixture.origins.oauthRevoke)
+ expect(fixture.origins.oauthRevoke).toBe('https://auth.x.ai/oauth2/revoke')
+ })
})
diff --git a/grok-llm-proxy/test/controlApiClient.test.ts b/grok-llm-proxy/test/controlApiClient.test.ts
index b7c723e2e..bc4726b9e 100644
--- a/grok-llm-proxy/test/controlApiClient.test.ts
+++ b/grok-llm-proxy/test/controlApiClient.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from 'vitest'
import { type IncomingMessage, type Server, createServer } from 'node:http'
import { ControlApiClient, ControlApiClientError } from '../src/controlApiClient.js'
+import { GROK_CATALOG_ORIGIN, GROK_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
const LOOPBACK_V4 = ['127', '0', '0', '1'].join('.')
@@ -62,6 +63,19 @@ describe('ControlApiClient', () => {
if (String(req.url).endsWith('/redeem')) {
seenTokens.push(String((body as { executionTicket: string }).executionTicket))
}
+ if (String(req.url).endsWith('/finalize')) {
+ // control-api echoes the persisted terminal outcome on finalize.
+ const raw = res as unknown as {
+ statusCode: number
+ setHeader: (name: string, value: string) => void
+ end: (chunk: string) => void
+ }
+ raw.statusCode = 200
+ raw.setHeader('content-type', 'application/json')
+ raw.end(
+ JSON.stringify({ providerAttemptId: 'att-1', outcome: 'success', duplicate: false })
+ )
+ }
})
try {
const client = new ControlApiClient({
@@ -134,3 +148,116 @@ describe('ControlApiClient', () => {
}
})
})
+
+describe('ControlApiClient response hardening', () => {
+ function jsonServer(body: unknown) {
+ return listen((_req, _body, res) => {
+ const raw = res as unknown as {
+ statusCode: number
+ setHeader: (name: string, value: string) => void
+ end: (chunk: string) => void
+ }
+ raw.statusCode = 200
+ raw.setHeader('content-type', 'application/json')
+ raw.end(JSON.stringify(body))
+ })
+ }
+
+ function client(url: string): ControlApiClient {
+ return new ControlApiClient({
+ baseUrl: `${url}/api/v1`,
+ serviceName: 'grok-llm-proxy',
+ serviceToken: 'dev-grok-llm-proxy-token',
+ })
+ }
+
+ const receipt = {
+ schemaVersion: 'grok-attempt-receipt.v1' as const,
+ providerAttemptId: 'att-1',
+ requestHash: 'b'.repeat(64),
+ outcome: 'success' as const,
+ }
+
+ it.each([['bogus'], [42], [null]])(
+ 'maps an unrecognized finalize outcome %j to unknown, never success',
+ async outcome => {
+ const server = await jsonServer({ providerAttemptId: 'att-1', outcome, duplicate: false })
+ try {
+ const finalized = await client(server.url).finalize({
+ attemptReceipt: 'a'.repeat(64),
+ receipt,
+ })
+ expect(finalized.outcome).toBe('unknown')
+ } finally {
+ await server.close()
+ }
+ }
+ )
+
+ it.each(['success', 'canceled', 'error', 'unknown'] as const)(
+ 'passes through the recognized finalize outcome %s',
+ async outcome => {
+ const server = await jsonServer({ providerAttemptId: 'att-1', outcome, duplicate: true })
+ try {
+ const finalized = await client(server.url).finalize({
+ attemptReceipt: 'a'.repeat(64),
+ receipt,
+ })
+ expect(finalized).toEqual({ providerAttemptId: 'att-1', outcome, duplicate: true })
+ } finally {
+ await server.close()
+ }
+ }
+ )
+
+ function redeemBody(maxStreamDurationMs: unknown): Record<string, unknown> {
+ return {
+ accessToken: 'tok-live',
+ transport: {
+ protocolVersion: 'grok-subscription-transport.v1',
+ completionsOrigin: GROK_COMPLETIONS_ORIGIN,
+ catalogOrigin: GROK_CATALOG_ORIGIN,
+ operation: 'completion_stream',
+ servedModel: 'gpt-5.1',
+ ...(maxStreamDurationMs === undefined ? {} : { maxStreamDurationMs }),
+ },
+ expiryClass: 'short_lived',
+ attemptReceipt: 'a'.repeat(64),
+ }
+ }
+
+ it.each([[0], [-1], [-300_000], [null], ['300000']])(
+ 'rejects a redeem transport maxStreamDurationMs of %j as provider_unavailable',
+ async value => {
+ const server = await jsonServer(redeemBody(value))
+ try {
+ await expect(
+ client(server.url).redeem({
+ executionTicket: 'ticket-1',
+ requestHash: 'b'.repeat(64),
+ operation: 'completion_stream',
+ })
+ ).rejects.toMatchObject({ code: 'provider_unavailable' })
+ } finally {
+ await server.close()
+ }
+ }
+ )
+
+ it('keeps a positive maxStreamDurationMs and defaults an absent one to 300000', async () => {
+ const positive = await jsonServer(redeemBody(120_000))
+ const absent = await jsonServer(redeemBody(undefined))
+ try {
+ const input = {
+ executionTicket: 'ticket-1',
+ requestHash: 'b'.repeat(64),
+ operation: 'completion_stream' as const,
+ }
+ expect((await client(positive.url).redeem(input)).transport.maxStreamDurationMs).toBe(120_000)
+ expect((await client(absent.url).redeem(input)).transport.maxStreamDurationMs).toBe(300_000)
+ } finally {
+ await positive.close()
+ await absent.close()
+ }
+ })
+})
diff --git a/grok-llm-proxy/test/grokTransport.conformance.test.ts b/grok-llm-proxy/test/grokTransport.conformance.test.ts
index bd4cb3294..d7b2892ed 100644
--- a/grok-llm-proxy/test/grokTransport.conformance.test.ts
+++ b/grok-llm-proxy/test/grokTransport.conformance.test.ts
@@ -4,7 +4,12 @@ import {
parseGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
import type { RedeemAttemptSuccess } from '../src/controlApiClient.js'
-import { GrokTransportError, streamGrokCompletion } from '../src/grokTransport.js'
+import {
+ GROK_UPSTREAM_TEMPERATURE_PROBE_CONFIRMED,
+ GrokTransportError,
+ type StreamGrokCompletionInput,
+ streamGrokCompletion,
+} from '../src/grokTransport.js'
import { GROK_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
const REQUEST = {
@@ -16,6 +21,12 @@ const REQUEST = {
messages: [{ role: 'user' as const, content: 'hello' }],
}
+type FetchInput = string | URL | Request
+
+function headerOf(init: RequestInit | undefined, name: string): string | undefined {
+ return (init?.headers as Record<string, string> | undefined)?.[name]
+}
+
const REQUEST_HASH = hashGrokCompletionRequestV1(REQUEST)
function accessTokenFor(label: string): string {
@@ -57,6 +68,105 @@ function sseResponse(
}
describe('streamGrokCompletion', () => {
+ it('does not read further upstream bytes while the frame consumer is back-pressured', async () => {
+ const encoder = new TextEncoder()
+ const events = [
+ 'data: {"type":"response.output_text.delta","delta":"one"}\n\n',
+ 'data: {"type":"response.output_text.delta","delta":"two"}\n\n',
+ 'data: {"type":"response.completed","response":{"usage":{}}}\n\n',
+ ]
+ let pulls = 0
+ const fetchFn = vi.fn(async () => {
+ const body = new ReadableStream<Uint8Array>(
+ {
+ pull(controller) {
+ const next = events[pulls]
+ pulls += 1
+ if (next === undefined) controller.close()
+ else controller.enqueue(encoder.encode(next))
+ },
+ },
+ { highWaterMark: 0 }
+ )
+ return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } })
+ })
+ let releaseDrain: (() => void) | undefined
+ const drained = new Promise<void>(resolve => {
+ releaseDrain = resolve
+ })
+ const frames: unknown[] = []
+ const pending = streamGrokCompletion({
+ executionTicket: 'ticket-drain',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-drain',
+ hostRef: 'research-host',
+ model: REQUEST.model,
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-drain',
+ },
+ redeem: async () => redeemSuccess(),
+ finalize: vi.fn(async () => ({
+ providerAttemptId: 'att-drain',
+ outcome: 'success' as const,
+ duplicate: false,
+ })),
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ onFrame: frame => {
+ frames.push(frame)
+ // First frame fills the client buffer; later frames are accepted.
+ return frames.length === 1 ? drained : undefined
+ },
+ })
+ await new Promise(resolve => setTimeout(resolve, 50))
+ expect(frames).toEqual([{ type: 'text', text: 'one' }])
+ expect(pulls).toBe(1)
+ releaseDrain?.()
+ const result = await pending
+ expect(result.outcome).toBe('success')
+ expect(frames).toEqual([
+ { type: 'text', text: 'one' },
+ { type: 'text', text: 'two' },
+ ])
+ })
+
+ it('does not redeem when the client aborted before the attempt was dispatched', async () => {
+ const redeem = vi.fn(async () => redeemSuccess())
+ const finalize = vi.fn(async () => ({
+ providerAttemptId: 'att-pre-abort',
+ outcome: 'canceled' as const,
+ duplicate: false,
+ }))
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
+ sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
+ )
+ const abort = new AbortController()
+ abort.abort()
+ const result = await streamGrokCompletion({
+ executionTicket: 'ticket-pre-abort',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-pre-abort',
+ hostRef: 'research-host',
+ model: REQUEST.model,
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-pre-abort',
+ },
+ signal: abort.signal,
+ redeem,
+ finalize,
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ })
+ expect(result.outcome).toBe('canceled')
+ expect(redeem).not.toHaveBeenCalled()
+ expect(fetchFn).not.toHaveBeenCalled()
+ expect(finalize).not.toHaveBeenCalled()
+ })
+
it.each(['response.failed', 'unterminated'])(
'does not emit partial tool calls after %s',
async terminal => {
@@ -83,9 +193,11 @@ describe('streamGrokCompletion', () => {
outcome: 'success' as const,
duplicate: false,
})),
- fetchFn: vi.fn(async () => sseResponse(frames)),
+ fetchFn: vi.fn(async (_url: FetchInput, _init?: RequestInit) => sseResponse(frames)),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => emitted.push(frame),
+ onFrame: frame => {
+ emitted.push(frame)
+ },
})
if (terminal === 'unterminated') expect((await pending).outcome).toBe('unknown')
else await expect(pending).rejects.toThrow(/upstream response failed/)
@@ -123,9 +235,11 @@ describe('streamGrokCompletion', () => {
},
redeem: vi.fn(async () => redeemSuccess()),
finalize,
- fetchFn: vi.fn(async () => sseResponse(frames)),
+ fetchFn: vi.fn(async (_url: FetchInput, _init?: RequestInit) => sseResponse(frames)),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => emitted.push(frame),
+ onFrame: frame => {
+ emitted.push(frame)
+ },
})
if (count === 64) {
expect((await pending).outcome).toBe('success')
@@ -147,7 +261,7 @@ describe('streamGrokCompletion', () => {
duplicate: false,
}))
const frames: unknown[] = []
- const fetchFn = vi.fn(async (url: string) => {
+ const fetchFn = vi.fn(async (url: FetchInput, _init?: RequestInit) => {
expect(url).toBe(GROK_COMPLETIONS_ORIGIN)
return sseResponse([
'data: {"type":"response.output_text.delta","delta":"hi"}\n\n',
@@ -171,7 +285,9 @@ describe('streamGrokCompletion', () => {
finalize,
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => frames.push(frame),
+ onFrame: frame => {
+ frames.push(frame)
+ },
})
expect(redeem).toHaveBeenCalledOnce()
@@ -190,17 +306,17 @@ describe('streamGrokCompletion', () => {
receipt: expect.objectContaining({ outcome: 'success', requestHash: REQUEST_HASH }),
})
)
- expect(String(fetchFn.mock.calls[0]?.[1]?.headers?.['authorization'])).toContain(
+ expect(String(headerOf(fetchFn.mock.calls[0]?.[1], 'authorization'))).toContain(
accessTokenFor('live')
)
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['user-agent']).toBe('evenfire-grok-subscription')
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['openai-beta']).toBeUndefined()
- expect(fetchFn.mock.calls[0]?.[1]?.headers?.['x-xai-token-auth']).toBeUndefined()
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'user-agent')).toBe('evenfire-grok-subscription')
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'openai-beta')).toBeUndefined()
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'x-xai-token-auth')).toBeUndefined()
expect(String(fetchFn.mock.calls[0]?.[1]?.body)).toContain('"store":false')
})
it('flushes a completed event that arrives without a trailing blank line', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse([
'data: {"type":"response.completed","response":{"usage":{"input_tokens":1,"output_tokens":1}}}',
])
@@ -230,7 +346,7 @@ describe('streamGrokCompletion', () => {
})
it('parses CRLF-delimited SSE frames', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse([
'data: {"type":"response.completed","response":{"usage":{"input_tokens":4,"output_tokens":5}}}\r\n\r\n',
])
@@ -260,7 +376,9 @@ describe('streamGrokCompletion', () => {
})
it('maps upstream 402/403 to provider_unavailable', async () => {
- const fetchFn = vi.fn(async () => new Response('paywall', { status: 403 }))
+ const fetchFn = vi.fn(
+ async (_url: FetchInput, _init?: RequestInit) => new Response('paywall', { status: 403 })
+ )
await expect(
streamGrokCompletion({
executionTicket: 'ticket-1',
@@ -276,7 +394,7 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess({ accessToken: 'opaque-token' }),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'error',
+ outcome: 'error' as const,
duplicate: false,
})),
fetchFn,
@@ -326,7 +444,7 @@ describe('streamGrokCompletion', () => {
redeemSuccess({ transport: { ...redeemSuccess().transport, servedModel: 'other' } }),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'error',
+ outcome: 'error' as const,
duplicate: false,
})),
fetchFn: vi.fn(),
@@ -355,7 +473,7 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'error',
+ outcome: 'error' as const,
duplicate: false,
})),
fetchFn,
@@ -388,7 +506,7 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -414,10 +532,12 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'error',
+ outcome: 'error' as const,
duplicate: false,
})),
- fetchFn: vi.fn(async () => new Response('denied', { status: 401 })),
+ fetchFn: vi.fn(
+ async (_url: FetchInput, _init?: RequestInit) => new Response('denied', { status: 401 })
+ ),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
})
).rejects.toMatchObject({ code: 'connection_unavailable' })
@@ -475,7 +595,7 @@ describe('streamGrokCompletion', () => {
tokens.push(input.executionTicket)
return redeemSuccess({ accessToken: accessTokenFor(input.executionTicket) })
})
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
const ticket = {
@@ -493,7 +613,7 @@ describe('streamGrokCompletion', () => {
redeem,
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -507,23 +627,23 @@ describe('streamGrokCompletion', () => {
redeem,
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
})
expect(tokens).toEqual(['t-a', 't-b'])
- expect(String(fetchFn.mock.calls[0]?.[1]?.headers?.['authorization'])).toContain(
+ expect(String(headerOf(fetchFn.mock.calls[0]?.[1], 'authorization'))).toContain(
accessTokenFor('t-a')
)
- expect(String(fetchFn.mock.calls[1]?.[1]?.headers?.['authorization'])).toContain(
+ expect(String(headerOf(fetchFn.mock.calls[1]?.[1], 'authorization'))).toContain(
accessTokenFor('t-b')
)
})
it('does not retry after an ambiguous upstream response', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.output_text.delta","delta":"partial"}\n\n'])
)
const result = await streamGrokCompletion({
@@ -540,7 +660,7 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'unknown',
+ outcome: 'unknown' as const,
duplicate: false,
})),
fetchFn,
@@ -576,7 +696,7 @@ describe('streamGrokCompletion', () => {
transportHints: { promptCacheKey: 'sess-1' },
}
const requestHash = hashGrokCompletionRequestV1(request)
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
await streamGrokCompletion({
@@ -593,7 +713,7 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -695,7 +815,9 @@ describe('streamGrokCompletion', () => {
}),
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => emitted.push(frame),
+ onFrame: frame => {
+ emitted.push(frame)
+ },
})
expect(result.outcome).toBe('success')
expect(emitted).toContainEqual({ type: 'tool_call', id: 'new-call', name, arguments: {} })
@@ -744,7 +866,9 @@ describe('streamGrokCompletion', () => {
finalize,
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => emitted.push(frame),
+ onFrame: frame => {
+ emitted.push(frame)
+ },
})
).rejects.toMatchObject({
code: 'provider_unavailable',
@@ -760,7 +884,7 @@ describe('streamGrokCompletion', () => {
})
it('omits Notify-like generation fields on the Responses wire', async () => {
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
await streamGrokCompletion({
@@ -777,7 +901,7 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -791,7 +915,7 @@ describe('streamGrokCompletion', () => {
expect(body.input).toEqual([{ role: 'user', content: 'hello' }])
})
- it('keeps analysis instructions and binds max_output_tokens on the Grok wire', async () => {
+ it('keeps analysis instructions, binds max_output_tokens, and withholds probe-gated temperature', async () => {
const request = {
...REQUEST,
messages: [
@@ -801,7 +925,7 @@ describe('streamGrokCompletion', () => {
generation: { maxOutputTokens: 4096, temperature: 0.2 },
}
const requestHash = hashGrokCompletionRequestV1(request)
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
)
await streamGrokCompletion({
@@ -818,7 +942,7 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
@@ -828,17 +952,23 @@ describe('streamGrokCompletion', () => {
expect(body.instructions).toBe('review this repository')
expect(body.input).toEqual([{ role: 'user', content: 'findings' }])
expect(body.max_output_tokens).toBe(4096)
- expect(body.temperature).toBe(0.2)
+ // B-M10: temperature stays in the authorize hash but is not sent upstream
+ // until a live SuperGrok probe confirms /v1/responses accepts it.
+ expect(GROK_UPSTREAM_TEMPERATURE_PROBE_CONFIRMED).toBe(false)
+ expect(body).not.toHaveProperty('temperature')
+ expect(hashGrokCompletionRequestV1(request)).toBe(requestHash)
expect(body).not.toHaveProperty('text')
expect(body).not.toHaveProperty('service_tier')
})
it('maps upstream 400 to invalid_request and finalizes error without usage', async () => {
- const finalize = vi.fn(async () => ({
- providerAttemptId: 'att-1',
- outcome: 'error' as const,
- duplicate: false,
- }))
+ const finalize = vi.fn(
+ async (_input: Parameters<StreamGrokCompletionInput['finalize']>[0]) => ({
+ providerAttemptId: 'att-1',
+ outcome: 'error' as const,
+ duplicate: false,
+ })
+ )
await expect(
streamGrokCompletion({
executionTicket: 'ticket-1',
@@ -853,7 +983,10 @@ describe('streamGrokCompletion', () => {
},
redeem: async () => redeemSuccess(),
finalize,
- fetchFn: vi.fn(async () => new Response('bad request', { status: 400 })),
+ fetchFn: vi.fn(
+ async (_url: FetchInput, _init?: RequestInit) =>
+ new Response('bad request', { status: 400 })
+ ),
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
})
).rejects.toMatchObject({ code: 'invalid_request' })
@@ -867,7 +1000,7 @@ describe('streamGrokCompletion', () => {
it('emits a tool call only after argument deltas complete', async () => {
const frames: unknown[] = []
- const fetchFn = vi.fn(async () =>
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) =>
sseResponse([
'data: {"type":"response.output_item.added","item":{"type":"function_call","id":"item-1","call_id":"call-9","name":"lookup","arguments":""}}\n\n',
'data: {"type":"response.function_call_arguments.delta","item_id":"item-1","delta":"{\\"q\\":"}}\n\n',
@@ -890,12 +1023,14 @@ describe('streamGrokCompletion', () => {
redeem: async () => redeemSuccess(),
finalize: vi.fn(async () => ({
providerAttemptId: 'att-1',
- outcome: 'success',
+ outcome: 'success' as const,
duplicate: false,
})),
fetchFn,
lookup: async () => [{ address: '1.2.3.4', family: 4 }],
- onFrame: frame => frames.push(frame),
+ onFrame: frame => {
+ frames.push(frame)
+ },
})
expect(frames).toEqual([
{ type: 'tool_call', id: 'call-9', name: 'lookup', arguments: { q: 'x' } },
diff --git a/grok-llm-proxy/test/requestLimits.test.ts b/grok-llm-proxy/test/requestLimits.test.ts
new file mode 100644
index 000000000..ed7ec59fa
--- /dev/null
+++ b/grok-llm-proxy/test/requestLimits.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { RequestLimitError, StreamGate } from '../src/requestLimits.js'
+
+describe('StreamGate', () => {
+ it('admits a queued waiter once a running stream releases', async () => {
+ const gate = new StreamGate(1, 1)
+ const release = await gate.acquire()
+ let admitted = false
+ const queued = gate.acquire().then(next => {
+ admitted = true
+ return next
+ })
+ await new Promise(resolve => setTimeout(resolve, 30))
+ expect(admitted).toBe(false)
+ release()
+ const releaseQueued = await queued
+ expect(admitted).toBe(true)
+ releaseQueued()
+ })
+
+ it('rejects immediately without taking a slot when the signal is already aborted', async () => {
+ const gate = new StreamGate(1, 1)
+ const abort = new AbortController()
+ abort.abort()
+ await expect(gate.acquire(abort.signal)).rejects.toBeInstanceOf(RequestLimitError)
+ // The running slot was not consumed: a fresh caller is admitted at once.
+ const release = await Promise.race([
+ gate.acquire(),
+ new Promise<never>((_, reject) =>
+ setTimeout(() => reject(new Error('slot leaked by aborted caller')), 100)
+ ),
+ ])
+ release()
+ })
+
+ it('rejects a queued waiter when its client aborts and frees the queue slot', async () => {
+ const gate = new StreamGate(1, 1)
+ const release = await gate.acquire()
+ const abort = new AbortController()
+ const queued = gate.acquire(abort.signal)
+ abort.abort()
+ await expect(
+ Promise.race([
+ queued,
+ new Promise<never>((_, reject) =>
+ setTimeout(() => reject(new Error('queued waiter ignored abort')), 200)
+ ),
+ ])
+ ).rejects.toBeInstanceOf(RequestLimitError)
+ // The queue slot is free again, so a new waiter queues instead of "queue is full".
+ const next = gate.acquire()
+ release()
+ const releaseNext = await next
+ releaseNext()
+ })
+})
diff --git a/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts b/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
new file mode 100644
index 000000000..0c392b51d
--- /dev/null
+++ b/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
@@ -0,0 +1,452 @@
+/**
+ * Hermetic runtime-path e2e (Grok port of
+ * codex-llm-proxy/test/runtimePath.hermetic.e2e.test.ts): authorize (mocked
+ * control-api redeem) → proxy runtime listener → REAL loopback Grok fixture
+ * upstream (an HTTP server on 127.0.0.1 that streams Responses-shaped SSE) →
+ * finalize receipt.
+ *
+ * The full proxy pipeline (platform JWT, execution ticket, request-hash
+ * freeze, execution kill switch, origin policy, tool-name mapping, SSE mapping,
+ * finalize contract) runs unmocked. Only two injection seams are substituted,
+ * both wired to live infrastructure in production:
+ * - ControlApiClient (redeem/finalize) — an in-memory grant table standing
+ * in for control-api's Grok authorizer, keyed by the recipe-shaped hostRef.
+ * - fetchFn/lookup — the frozen cli-chat-proxy.grok.com origin is still
+ * asserted by the unmodified origin policy; only the socket is pointed at
+ * the loopback fixture. No live Grok OAuth or SuperGrok call is made.
+ *
+ * Unlike the Codex suite there is no shared tests/e2e Grok fixture upstream
+ * yet, so the fixture lives in-process here and speaks plain HTTP on loopback
+ * (no TLS material needed); the streamed body is still read from a real socket.
+ */
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import jwt from 'jsonwebtoken'
+import { generateKeyPairSync } from 'node:crypto'
+import { type IncomingMessage, type Server, type ServerResponse, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import request from 'supertest'
+import {
+ hashGrokCompletionRequestV1,
+ parseGrokCompletionRequestV1,
+} from '@clerum/grok-provider-attempt-contract'
+import type { GrokLlmProxyConfig } from '../src/config.js'
+import {
+ type ControlApiClient,
+ ControlApiClientError,
+ type FinalizeAttemptSuccess,
+ type RedeemAttemptSuccess,
+} from '../src/controlApiClient.js'
+import { GROK_UPSTREAM_USER_AGENT } from '../src/grokUpstreamHeaders.js'
+import { GROK_CATALOG_ORIGIN, GROK_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
+import { type ProxyServers, createProxyApps } from '../src/server.js'
+
+const ACCESS_TOKEN = 'test-access-hermetic-grok'
+const MODEL = 'grok-4-fast'
+const RECIPE_HOST_REF = 'sandbox-recipes/e2e-grok-recipe'
+const CONNECTED_GRANTS: Record<string, { connectionKey: string; models: string[] }> = {
+ [RECIPE_HOST_REF]: { connectionKey: 'e2e-supergrok', models: [MODEL] },
+}
+
+// Optional-field MCP tool: only `key` is required. The upstream simulates the
+// model calling it; the proxy must carry these exact arguments back.
+const UPDATE_TOOL = {
+ name: 'eventasks__workitem_update',
+ description: 'Update a work item.',
+ parameters: {
+ type: 'object',
+ properties: {
+ key: { type: 'string' },
+ description: { type: 'string' },
+ labels: { type: 'array', items: { type: 'string' } },
+ },
+ required: ['key'],
+ },
+}
+const CALL_ARGUMENTS = { key: 'BUG-1', description: 'Updated description' }
+
+const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+ modulusLength: 2048,
+ publicKeyEncoding: { type: 'spki', format: 'pem' },
+ privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+})
+
+function config(overrides: Partial<GrokLlmProxyConfig> = {}): GrokLlmProxyConfig {
+ return {
+ runtimePort: 0,
+ adminPort: 0,
+ probePort: 0,
+ maxBodyBytes: 1_048_576,
+ maxStreamDurationMs: 30_000,
+ maxDeadlineMs: 30_000,
+ jwtIssuer: 'control-api',
+ jwtPublicKey: publicKey,
+ executionEnabled: true,
+ controlApiBaseUrl: 'http://control-api.invalid/api/v1',
+ controlApiServiceName: 'grok-llm-proxy',
+ controlApiServiceToken: 'unused-in-hermetic-e2e',
+ ...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(hostRef: string): string {
+ return sign(
+ {
+ sub: hostRef,
+ hostRefs: [hostRef],
+ workflowControlScopes: ['llm:grok:execute'],
+ scope: 'workflow:approval:request',
+ },
+ 'workflow-approvals'
+ )
+}
+
+function executionTicket(input: {
+ hostRef: string
+ requestHash: string
+ providerAttemptId: string
+}): string {
+ return sign(
+ {
+ jti: '55555555-5555-4555-8555-555555555555',
+ typ: 'grok-execution-ticket',
+ hostRef: input.hostRef,
+ model: MODEL,
+ requestHash: input.requestHash,
+ providerAttemptId: input.providerAttemptId,
+ },
+ 'grok-llm-proxy'
+ )
+}
+
+function completionRequest(): Record<string, unknown> {
+ return {
+ schemaVersion: 'grok-completion-request.v1',
+ requestId: 'req-hermetic-grok-1',
+ idempotencyKey: 'idem-hermetic-grok-1',
+ provider: 'grok-subscription',
+ model: MODEL,
+ messages: [{ role: 'user', content: 'Say hello through Grok subscription' }],
+ }
+}
+
+function sseFrames(body: string): Array<Record<string, unknown>> {
+ return body
+ .split('\n\n')
+ .map(part => part.trim())
+ .filter(part => part.startsWith('data:'))
+ .map(part => JSON.parse(part.slice(5).trim()) as Record<string, unknown>)
+}
+
+type RedeemCall = Parameters<ControlApiClient['redeem']>[0]
+type FinalizeCall = Parameters<ControlApiClient['finalize']>[0]
+
+function makeControlApiMock(): {
+ client: ControlApiClient
+ redeems: RedeemCall[]
+ finalizes: FinalizeCall[]
+} {
+ const redeems: RedeemCall[] = []
+ const finalizes: FinalizeCall[] = []
+ const client = {
+ async redeem(input: RedeemCall): Promise<RedeemAttemptSuccess> {
+ redeems.push(input)
+ const grant = input.hostRef ? CONNECTED_GRANTS[input.hostRef] : undefined
+ if (!grant) throw new ControlApiClientError('no_grant', 'no Grok grant is assigned')
+ if (!input.model || !grant.models.includes(input.model)) {
+ throw new ControlApiClientError('model_not_allowed', 'model is not offered on the grant')
+ }
+ return {
+ accessToken: ACCESS_TOKEN,
+ transport: {
+ protocolVersion: 'grok-subscription-transport.v1',
+ completionsOrigin: GROK_COMPLETIONS_ORIGIN,
+ catalogOrigin: GROK_CATALOG_ORIGIN,
+ operation: 'completion_stream',
+ servedModel: input.model,
+ maxStreamDurationMs: 30_000,
+ },
+ expiryClass: 'short_lived',
+ attemptReceipt: 'c'.repeat(64),
+ }
+ },
+ async finalize(input: FinalizeCall): Promise<FinalizeAttemptSuccess> {
+ finalizes.push(input)
+ return {
+ providerAttemptId: input.receipt.providerAttemptId,
+ outcome: input.receipt.outcome,
+ duplicate: false,
+ }
+ },
+ } as unknown as ControlApiClient
+ return { client, redeems, finalizes }
+}
+
+// ─── loopback Grok fixture upstream ─────────────────────────────────────────
+
+const counters = { streams: 0, models: 0, rejected: 0 }
+const upstreamBodies: Array<Record<string, unknown>> = []
+let upstream: Server | undefined
+let upstreamBase = ''
+let servers: ProxyServers | undefined
+
+function readBody(req: IncomingMessage): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const chunks: Buffer[] = []
+ req.on('data', chunk => chunks.push(chunk as Buffer))
+ req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+ req.on('error', reject)
+ })
+}
+
+function json(res: ServerResponse, status: number, body: unknown): void {
+ res.writeHead(status, { 'content-type': 'application/json' })
+ res.end(JSON.stringify(body))
+}
+
+async function handleUpstream(req: IncomingMessage, res: ServerResponse): Promise<void> {
+ const url = new URL(req.url || '/', 'http://grok-test-upstream.local')
+ if (
+ req.headers.authorization !== `Bearer ${ACCESS_TOKEN}` ||
+ req.headers['user-agent'] !== GROK_UPSTREAM_USER_AGENT
+ ) {
+ counters.rejected += 1
+ json(res, 401, { error: 'unauthorized' })
+ return
+ }
+ if (req.method === 'GET' && url.pathname === '/v1/models') {
+ counters.models += 1
+ json(res, 200, { data: [{ id: MODEL, object: 'model' }] })
+ return
+ }
+ if (req.method === 'POST' && url.pathname === '/v1/responses') {
+ const body = JSON.parse((await readBody(req)) || '{}') as Record<string, unknown>
+ upstreamBodies.push(body)
+ const tools = Array.isArray(body.tools) ? (body.tools as Array<{ name?: string }>) : []
+ counters.streams += 1
+ res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' })
+ // The proxy dispatches on the `type` INSIDE each data payload.
+ res.write(`data: ${JSON.stringify({ type: 'response.output_text.delta', delta: 'hello' })}\n\n`)
+ const wireTool = tools[0]?.name
+ if (wireTool) {
+ res.write(
+ `data: ${JSON.stringify({
+ type: 'response.output_item.done',
+ item: {
+ type: 'function_call',
+ call_id: 'call-hermetic-grok',
+ name: wireTool,
+ arguments: JSON.stringify(CALL_ARGUMENTS),
+ },
+ })}\n\n`
+ )
+ }
+ res.end(
+ `data: ${JSON.stringify({
+ type: 'response.completed',
+ response: { usage: { input_tokens: 3, output_tokens: 1 } },
+ })}\n\n`
+ )
+ return
+ }
+ json(res, 404, { error: 'not_found' })
+}
+
+/**
+ * Reroute the frozen cli-chat-proxy.grok.com origin to the loopback fixture.
+ * The URL given to fetchFn already passed the unmodified origin policy; only
+ * the socket destination changes.
+ */
+function rewriteFetch(url: string | URL | Request, init?: RequestInit): Promise<Response> {
+ const parsed = new URL(String(url))
+ expect(parsed.origin).toBe('https://cli-chat-proxy.grok.com')
+ return fetch(new URL(parsed.pathname + parsed.search, upstreamBase), init)
+}
+
+const lookup = async () => [{ address: '104.18.32.47', family: 4 }]
+
+beforeAll(async () => {
+ upstream = createServer((req, res) => {
+ handleUpstream(req, res).catch(err => {
+ json(res, 500, { error: err instanceof Error ? err.message : 'upstream_error' })
+ })
+ })
+ await new Promise<void>(resolve => upstream?.listen(0, '127.0.0.1', () => resolve()))
+ const { port } = upstream.address() as AddressInfo
+ upstreamBase = `http://127.0.0.1:${port}`
+})
+
+afterAll(async () => {
+ await servers?.close()
+ await new Promise<void>(resolve => (upstream ? upstream.close(() => resolve()) : resolve()))
+})
+
+describe('hermetic Grok authorize → proxy → fixture upstream → finalize', () => {
+ it('streams a completion through the fixture upstream and finalizes a success receipt', async () => {
+ const { client, redeems, finalizes } = makeControlApiMock()
+ servers = createProxyApps(config(), { controlApiClient: client, fetchFn: rewriteFetch, lookup })
+ const beforeStreams = counters.streams
+ upstreamBodies.length = 0
+
+ const raw = { ...completionRequest(), tools: [structuredClone(UPDATE_TOOL)] }
+ const original = structuredClone(raw)
+ const parsed = parseGrokCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const providerAttemptId = 'att-hermetic-grok-1'
+
+ const res = await request(servers.runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken(RECIPE_HOST_REF)}`)
+ .send({
+ executionTicket: executionTicket({
+ hostRef: RECIPE_HOST_REF,
+ requestHash,
+ providerAttemptId,
+ }),
+ requestHash,
+ request: raw,
+ })
+
+ expect(res.status).toBe(200)
+ expect(res.headers['content-type']).toContain('text/event-stream')
+ const frames = sseFrames(res.text)
+ expect(frames).toContainEqual({ type: 'text', text: 'hello' })
+ expect(frames.filter(frame => frame.type === 'tool_call')).toEqual([
+ {
+ type: 'tool_call',
+ id: 'call-hermetic-grok',
+ name: UPDATE_TOOL.name,
+ arguments: CALL_ARGUMENTS,
+ },
+ ])
+ // The stream ends in a done frame carrying the success outcome and usage.
+ expect(frames.at(-1)).toEqual({
+ type: 'done',
+ outcome: 'success',
+ usage: { inputTokens: 3, outputTokens: 1 },
+ })
+
+ expect(upstreamBodies).toHaveLength(1)
+ expect(upstreamBodies[0]).toMatchObject({ model: MODEL, stream: true, store: false })
+ expect(upstreamBodies[0]?.tools).toEqual([{ type: 'function', ...UPDATE_TOOL, strict: false }])
+ expect(raw).toEqual(original)
+
+ expect(redeems).toHaveLength(1)
+ expect(redeems[0]).toMatchObject({
+ requestHash,
+ model: MODEL,
+ hostRef: RECIPE_HOST_REF,
+ operation: 'completion_stream',
+ })
+ expect(finalizes).toHaveLength(1)
+ expect(finalizes[0]?.attemptReceipt).toBe('c'.repeat(64))
+ expect(finalizes[0]?.receipt).toEqual({
+ schemaVersion: 'grok-attempt-receipt.v1',
+ providerAttemptId,
+ requestHash,
+ outcome: 'success',
+ usage: { inputTokens: 3, outputTokens: 1 },
+ })
+ expect(counters.streams).toBe(beforeStreams + 1)
+ expect(res.text).not.toMatch(/test-access-hermetic|attemptReceipt|refresh/i)
+
+ await servers.close()
+ servers = undefined
+ })
+
+ it('fails closed before touching the upstream when the recipe grant is unassigned', async () => {
+ const { client, redeems, finalizes } = makeControlApiMock()
+ servers = createProxyApps(config(), { controlApiClient: client, fetchFn: rewriteFetch, lookup })
+ const beforeStreams = counters.streams
+
+ const unassignedHostRef = 'sandbox-recipes/e2e-grok-recipe-unassigned'
+ const raw = completionRequest()
+ const parsed = parseGrokCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashGrokCompletionRequestV1(parsed.value)
+
+ const res = await request(servers.runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken(unassignedHostRef)}`)
+ .send({
+ executionTicket: executionTicket({
+ hostRef: unassignedHostRef,
+ requestHash,
+ providerAttemptId: 'att-hermetic-grok-2',
+ }),
+ requestHash,
+ request: raw,
+ })
+
+ expect(res.status).toBe(403)
+ expect(JSON.parse(res.text)).toEqual({ error: 'no_grant' })
+ expect(redeems).toHaveLength(1)
+ expect(finalizes).toHaveLength(0)
+ expect(counters.streams).toBe(beforeStreams)
+
+ await servers.close()
+ servers = undefined
+ })
+
+ it('lists the catalog through the admin listener with a valid permit', async () => {
+ servers = createProxyApps(config(), { fetchFn: rewriteFetch, lookup })
+ const beforeModels = counters.models
+ const permit = sign(
+ { sub: 'admin-1', typ: 'grok-admin-permit', operation: 'catalog_list' },
+ 'grok-llm-proxy-admin'
+ )
+ const res = await request(servers.adminApp)
+ .post('/internal/admin/v1/grok/models')
+ .set('Authorization', `Bearer ${permit}`)
+ .send({ accessToken: ACCESS_TOKEN })
+ expect(res.status).toBe(200)
+ expect(res.body).toEqual({ outcome: 'ready', models: [{ model: MODEL }] })
+ expect(counters.models).toBe(beforeModels + 1)
+
+ await servers.close()
+ servers = undefined
+ })
+
+ it('never reaches the upstream while the execution kill switch is off', async () => {
+ const { client, redeems } = makeControlApiMock()
+ servers = createProxyApps(config({ executionEnabled: false }), {
+ controlApiClient: client,
+ fetchFn: rewriteFetch,
+ lookup,
+ })
+ const beforeStreams = counters.streams
+ const raw = completionRequest()
+ const parsed = parseGrokCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashGrokCompletionRequestV1(parsed.value)
+
+ const res = await request(servers.runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken(RECIPE_HOST_REF)}`)
+ .send({
+ executionTicket: executionTicket({
+ hostRef: RECIPE_HOST_REF,
+ requestHash,
+ providerAttemptId: 'att-hermetic-grok-off',
+ }),
+ requestHash,
+ request: raw,
+ })
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'disabled' })
+ expect(redeems).toHaveLength(0)
+ expect(counters.streams).toBe(beforeStreams)
+
+ await servers.close()
+ servers = undefined
+ })
+})
diff --git a/grok-llm-proxy/test/server.security.test.ts b/grok-llm-proxy/test/server.security.test.ts
index e7cddaffa..6e53b9461 100644
--- a/grok-llm-proxy/test/server.security.test.ts
+++ b/grok-llm-proxy/test/server.security.test.ts
@@ -2,9 +2,14 @@ import { describe, expect, it } from 'vitest'
import jwt from 'jsonwebtoken'
import { generateKeyPairSync } from 'node:crypto'
import request from 'supertest'
+import {
+ hashGrokCompletionRequestV1,
+ parseGrokCompletionRequestV1,
+} from '@clerum/grok-provider-attempt-contract'
import { verifyAdminPermit } from '../src/auth/adminPermitVerifier.js'
import { verifyExecutionTicket } from '../src/auth/executionTicketVerifier.js'
import { type GrokLlmProxyConfig, loadConfig } from '../src/config.js'
+import { ControlApiClient, ControlApiClientError } from '../src/controlApiClient.js'
import { createProxyApps } from '../src/server.js'
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
@@ -284,3 +289,159 @@ describe('grok-llm-proxy security surface', () => {
).toThrow(/bounded positive integer/)
})
})
+
+describe('grok-llm-proxy execution kill switch', () => {
+ const lookup = async () => [{ address: '1.2.3.4', family: 4 }]
+
+ function validCompletionBody(): Record<string, unknown> {
+ const raw = {
+ schemaVersion: 'grok-completion-request.v1',
+ requestId: 'req-kill-switch',
+ idempotencyKey: 'idem-kill-switch',
+ provider: 'grok-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'hello' }],
+ }
+ const parsed = parseGrokCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashGrokCompletionRequestV1(parsed.value)
+ const executionTicket = sign(
+ {
+ jti: '33333333-3333-4333-8333-333333333333',
+ typ: 'grok-execution-ticket',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId: 'att-kill-switch',
+ },
+ 'grok-llm-proxy'
+ )
+ return { executionTicket, requestHash, request: raw }
+ }
+
+ function recordingClient(): { client: ControlApiClient; redeems: unknown[] } {
+ const redeems: unknown[] = []
+ const client = {
+ async redeem(input: unknown) {
+ redeems.push(input)
+ throw new ControlApiClientError('no_grant', 'no grant in kill-switch test')
+ },
+ async finalize() {
+ throw new Error('finalize must not run in kill-switch test')
+ },
+ } as unknown as ControlApiClient
+ return { client, redeems }
+ }
+
+ it('returns 404 disabled for a fully valid runtime JWT + ticket when execution is disabled', async () => {
+ const body = validCompletionBody()
+
+ // Liveness witness: the identical request reaches redeem when enabled.
+ const enabled = recordingClient()
+ const live = createProxyApps(config({ executionEnabled: true, maxBodyBytes: 65_536 }), {
+ controlApiClient: enabled.client,
+ lookup,
+ })
+ const reached = await request(live.runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send(body)
+ expect(reached.status).toBe(403)
+ expect(JSON.parse(reached.text)).toEqual({ error: 'no_grant' })
+ expect(enabled.redeems).toHaveLength(1)
+
+ const disabled = recordingClient()
+ const off = createProxyApps(config({ executionEnabled: false, maxBodyBytes: 65_536 }), {
+ controlApiClient: disabled.client,
+ lookup,
+ })
+ const res = await request(off.runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send(body)
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'disabled' })
+ expect(disabled.redeems).toHaveLength(0)
+ })
+
+ it('returns 404 disabled for a valid admin permit when execution is disabled', async () => {
+ const upstream = () =>
+ new Response(JSON.stringify({ data: [{ id: 'gpt-5.1' }] }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+
+ // Liveness witness: the identical admin call reaches the catalog upstream when enabled.
+ let enabledCalls = 0
+ const live = createProxyApps(config({ executionEnabled: true, maxBodyBytes: 65_536 }), {
+ fetchFn: (async () => {
+ enabledCalls += 1
+ return upstream()
+ }) as typeof fetch,
+ lookup,
+ })
+ const reached = await request(live.adminApp)
+ .post('/internal/admin/v1/grok/models')
+ .set('Authorization', `Bearer ${adminPermit()}`)
+ .send({ accessToken: 'tok' })
+ expect(reached.status).toBe(200)
+ expect(reached.body.outcome).toBe('ready')
+ expect(enabledCalls).toBe(1)
+
+ let disabledCalls = 0
+ const off = createProxyApps(config({ executionEnabled: false, maxBodyBytes: 65_536 }), {
+ fetchFn: (async () => {
+ disabledCalls += 1
+ return upstream()
+ }) as typeof fetch,
+ lookup,
+ })
+ const res = await request(off.adminApp)
+ .post('/internal/admin/v1/grok/models')
+ .set('Authorization', `Bearer ${adminPermit()}`)
+ .send({ accessToken: 'tok' })
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'disabled' })
+ expect(disabledCalls).toBe(0)
+ })
+})
+
+describe('grok-llm-proxy startup config', () => {
+ const base = {
+ GROK_LLM_PROXY_JWT_PUBLIC_KEY: publicKey,
+ GROK_LLM_PROXY_CONTROL_API_URL:
+ 'http://control-api-rpc-gateway.control-plane.svc.cluster.local:8090/api/v1',
+ GROK_LLM_PROXY_CONTROL_API_TOKEN: 'dev-grok-llm-proxy-token',
+ }
+
+ it('loads a complete environment', () => {
+ const loaded = loadConfig(base)
+ expect(loaded.controlApiBaseUrl).toBe(base.GROK_LLM_PROXY_CONTROL_API_URL)
+ expect(loaded.controlApiServiceToken).toBe('dev-grok-llm-proxy-token')
+ expect(loaded.controlApiServiceName).toBe('grok-llm-proxy')
+ })
+
+ it.each([undefined, '', ' '])('fails at startup when the control-api URL is %j', value => {
+ expect(() => loadConfig({ ...base, GROK_LLM_PROXY_CONTROL_API_URL: value })).toThrow(
+ /GROK_LLM_PROXY_CONTROL_API_URL/
+ )
+ })
+
+ it.each(['not a url', 'ftp://control-api/api/v1', 'file:///etc/passwd'])(
+ 'fails at startup when the control-api URL %j is not http(s)',
+ value => {
+ expect(() => loadConfig({ ...base, GROK_LLM_PROXY_CONTROL_API_URL: value })).toThrow(
+ /GROK_LLM_PROXY_CONTROL_API_URL/
+ )
+ }
+ )
+
+ it.each([undefined, '', ' '])(
+ 'fails at startup when the control-api service token is %j',
+ value => {
+ expect(() => loadConfig({ ...base, GROK_LLM_PROXY_CONTROL_API_TOKEN: value })).toThrow(
+ /GROK_LLM_PROXY_CONTROL_API_TOKEN/
+ )
+ }
+ )
+})
diff --git a/grok-llm-proxy/test/sseBackpressure.test.ts b/grok-llm-proxy/test/sseBackpressure.test.ts
new file mode 100644
index 000000000..d90235c10
--- /dev/null
+++ b/grok-llm-proxy/test/sseBackpressure.test.ts
@@ -0,0 +1,273 @@
+import { describe, expect, it } from 'vitest'
+import jwt from 'jsonwebtoken'
+import { generateKeyPairSync } from 'node:crypto'
+import { EventEmitter } from 'node:events'
+import { request as httpRequest } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import {
+ hashGrokCompletionRequestV1,
+ parseGrokCompletionRequestV1,
+} from '@clerum/grok-provider-attempt-contract'
+import type { GrokLlmProxyConfig } from '../src/config.js'
+import type {
+ ControlApiClient,
+ FinalizeAttemptSuccess,
+ RedeemAttemptSuccess,
+} from '../src/controlApiClient.js'
+import { GROK_CATALOG_ORIGIN, GROK_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
+import { createProxyApps, writeSseChunk } from '../src/server.js'
+
+function fakeResponse(writeResult: boolean) {
+ const written: string[] = []
+ const res = Object.assign(new EventEmitter(), {
+ destroyed: false,
+ write(chunk: string) {
+ written.push(chunk)
+ return writeResult
+ },
+ })
+ return { res, written }
+}
+
+async function settled(promise: Promise<unknown>, withinMs = 30): Promise<boolean> {
+ let done = false
+ void promise.then(() => {
+ done = true
+ })
+ await new Promise(resolve => setTimeout(resolve, withinMs))
+ return done
+}
+
+describe('writeSseChunk backpressure', () => {
+ it('does not wait when the socket accepted the chunk', async () => {
+ const { res, written } = fakeResponse(true)
+ const pending = writeSseChunk(res as never, 'data: {}\n\n', new AbortController().signal)
+ expect(pending).toBeUndefined()
+ expect(written).toEqual(['data: {}\n\n'])
+ })
+
+ it('waits for drain when res.write reports a full buffer', async () => {
+ const { res } = fakeResponse(false)
+ const pending = writeSseChunk(res as never, 'data: {}\n\n', new AbortController().signal)
+ expect(pending).toBeInstanceOf(Promise)
+ expect(await settled(pending as Promise<void>)).toBe(false)
+ res.emit('drain')
+ expect(await settled(pending as Promise<void>)).toBe(true)
+ })
+
+ it('stops waiting when the client closes or the stream aborts', async () => {
+ const closed = fakeResponse(false)
+ const onClose = writeSseChunk(closed.res as never, 'x', new AbortController().signal)
+ closed.res.emit('close')
+ expect(await settled(onClose as Promise<void>)).toBe(true)
+
+ const aborted = fakeResponse(false)
+ const abort = new AbortController()
+ const onAbort = writeSseChunk(aborted.res as never, 'x', abort.signal)
+ abort.abort()
+ expect(await settled(onAbort as Promise<void>)).toBe(true)
+ })
+})
+
+const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+ modulusLength: 2048,
+ publicKeyEncoding: { type: 'spki', format: 'pem' },
+ privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+})
+
+function sign(payload: Record<string, unknown>, audience: string): string {
+ return jwt.sign(payload, privateKey, {
+ algorithm: 'RS256',
+ issuer: 'control-api',
+ audience,
+ expiresIn: 60,
+ })
+}
+
+function config(): GrokLlmProxyConfig {
+ return {
+ runtimePort: 0,
+ adminPort: 0,
+ probePort: 0,
+ maxBodyBytes: 1_048_576,
+ maxStreamDurationMs: 60_000,
+ maxDeadlineMs: 60_000,
+ jwtIssuer: 'control-api',
+ jwtPublicKey: publicKey,
+ executionEnabled: true,
+ controlApiBaseUrl: 'http://control-api.invalid/api/v1',
+ controlApiServiceName: 'grok-llm-proxy',
+ controlApiServiceToken: 'unused',
+ }
+}
+
+const DELTA_BYTES = 64 * 1024
+const DELTA_COUNT = 1000
+const TOTAL_BYTES = DELTA_BYTES * DELTA_COUNT
+
+describe('slow SSE consumer', () => {
+ it('stops pulling the upstream while the client is not reading, then delivers everything', async () => {
+ const hostRef = 'research-host'
+ const raw = {
+ schemaVersion: 'grok-completion-request.v1',
+ requestId: 'req-backpressure',
+ idempotencyKey: 'idem-backpressure',
+ provider: 'grok-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'stream a lot' }],
+ }
+ const parsed = parseGrokCompletionRequestV1(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashGrokCompletionRequestV1(parsed.value)
+
+ const finalizes: string[] = []
+ const client = {
+ async redeem(): Promise<RedeemAttemptSuccess> {
+ return {
+ accessToken: 'test-access-backpressure',
+ transport: {
+ protocolVersion: 'grok-subscription-transport.v1',
+ completionsOrigin: GROK_COMPLETIONS_ORIGIN,
+ catalogOrigin: GROK_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> {
+ finalizes.push(input.receipt.outcome)
+ return {
+ providerAttemptId: input.receipt.providerAttemptId,
+ outcome: input.receipt.outcome,
+ duplicate: false,
+ }
+ },
+ } as unknown as ControlApiClient
+
+ const delta = 'x'.repeat(DELTA_BYTES)
+ const encoder = new TextEncoder()
+ let pulledDeltas = 0
+ const fetchFn = (async () => {
+ let sentCompleted = false
+ const body = new ReadableStream<Uint8Array>(
+ {
+ pull(controller) {
+ if (pulledDeltas < DELTA_COUNT) {
+ pulledDeltas += 1
+ controller.enqueue(
+ encoder.encode(
+ `data: ${JSON.stringify({ type: 'response.output_text.delta', delta })}\n\n`
+ )
+ )
+ return
+ }
+ if (!sentCompleted) {
+ sentCompleted = true
+ controller.enqueue(
+ encoder.encode('data: {"type":"response.completed","response":{"usage":{}}}\n\n')
+ )
+ return
+ }
+ controller.close()
+ },
+ },
+ { highWaterMark: 0 }
+ )
+ return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } })
+ }) as typeof fetch
+
+ const servers = createProxyApps(config(), {
+ 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
+ try {
+ const payload = JSON.stringify({
+ executionTicket: sign(
+ {
+ jti: '44444444-4444-4444-8444-444444444444',
+ typ: 'grok-execution-ticket',
+ hostRef,
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId: 'att-backpressure',
+ },
+ 'grok-llm-proxy'
+ ),
+ requestHash,
+ request: raw,
+ })
+ const platform = sign(
+ {
+ sub: `default/${hostRef}`,
+ hostRefs: [hostRef],
+ workflowControlScopes: ['llm:grok:execute'],
+ scope: 'workflow:approval:request',
+ },
+ 'workflow-approvals'
+ )
+
+ const text = await new Promise<string>((resolve, reject) => {
+ const req = httpRequest(
+ {
+ host: '127.0.0.1',
+ port,
+ method: 'POST',
+ path: '/internal/runtime/v1/grok/completions',
+ headers: {
+ 'content-type': 'application/json',
+ authorization: `Bearer ${platform}`,
+ 'content-length': Buffer.byteLength(payload),
+ },
+ },
+ res => {
+ // Slow consumer: stop reading immediately and wait for the proxy
+ // to settle before asserting how much upstream it consumed.
+ res.pause()
+ void (async () => {
+ let last = -1
+ const deadline = Date.now() + 5_000
+ while (Date.now() < deadline) {
+ await new Promise(r => setTimeout(r, 250))
+ if (pulledDeltas === last) break
+ last = pulledDeltas
+ }
+ try {
+ expect(pulledDeltas * DELTA_BYTES).toBeLessThan(TOTAL_BYTES / 2)
+ } catch (err) {
+ res.destroy()
+ reject(err)
+ return
+ }
+ const chunks: Buffer[] = []
+ res.on('data', chunk => chunks.push(chunk as Buffer))
+ res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+ res.on('error', reject)
+ res.resume()
+ })()
+ }
+ )
+ req.on('error', reject)
+ req.end(payload)
+ })
+
+ expect(pulledDeltas).toBe(DELTA_COUNT)
+ const frames = text
+ .split('\n\n')
+ .filter(part => part.startsWith('data: '))
+ .map(part => JSON.parse(part.slice(6)) as { type: string; outcome?: string })
+ expect(frames.filter(frame => frame.type === 'text')).toHaveLength(DELTA_COUNT)
+ expect(frames.at(-1)).toMatchObject({ type: 'done', outcome: 'success' })
+ expect(finalizes).toEqual(['success'])
+ } finally {
+ await servers.close()
+ }
+ }, 30_000)
+})
diff --git a/grok-llm-proxy/tsconfig.test.json b/grok-llm-proxy/tsconfig.test.json
new file mode 100644
index 000000000..c8c4f5393
--- /dev/null
+++ b/grok-llm-proxy/tsconfig.test.json
@@ -0,0 +1,14 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "noEmit": true,
+ "rootDir": ".",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "lib": ["ES2023"],
+ "declaration": false,
+ "sourceMap": false
+ },
+ "include": ["src/**/*", "test/**/*", "vitest.config.ts"],
+ "exclude": ["node_modules", "dist"]
+}