Skip to content

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

TypeScript

test(grok-llm-proxy): specify the visual transport budget and its 1/4 gate

Alfredo Lopez9d4959e33ca4
diff --git a/grok-llm-proxy/test/bodyAdmission.test.ts b/grok-llm-proxy/test/bodyAdmission.test.ts
index 7b20d3aa5..fc05f2a9a 100644
--- a/grok-llm-proxy/test/bodyAdmission.test.ts
+++ b/grok-llm-proxy/test/bodyAdmission.test.ts
@@ -12,7 +12,7 @@
*/
import { describe, expect, it, vi } from 'vitest'
import jwt from 'jsonwebtoken'
-import { generateKeyPairSync, randomUUID } from 'node:crypto'
+import { generateKeyPairSync, randomBytes, randomUUID } from 'node:crypto'
import { request as httpRequest } from 'node:http'
import type { AddressInfo } from 'node:net'
import { gzipSync } from 'node:zlib'
@@ -66,6 +66,7 @@ function config(maxBodyBytes: number): GrokLlmProxyConfig {
adminPort: 0,
probePort: 0,
maxBodyBytes,
+ maxVisualBodyBytes: LIMITS.maxVisualRequestBodyBytes,
maxStreamDurationMs: 60_000,
maxDeadlineMs: 60_000,
upstreamIdleTimeoutMs: 600_000,
@@ -802,6 +803,28 @@ describe('grok-llm-proxy encoded bodies (R9-1)', () => {
}
}, 30_000)
+ it('T-R9-1b-grok refuses a gzip body on the visual parser with 415', async () => {
+ const proxy = await heldProxy(maxBodyBytes)
+ proxy.releaseAll()
+ try {
+ // Random base64 barely compresses, so the wire length stays above the
+ // ordinary cap and selects the visual parser.
+ const gzipped = gzipSync(JSON.stringify({ pad: randomBytes(32 * 1024).toString('base64') }))
+ expect(gzipped.length).toBeGreaterThan(maxBodyBytes)
+ const refused = await postEncoded(proxy.port, {
+ path: COMPLETIONS_PATH,
+ token: platformToken,
+ body: gzipped,
+ encoding: 'gzip',
+ })
+ expect(refused.status).toBe(415)
+ expect(JSON.parse(refused.body)).toEqual({ error: 'unsupported_media_type' })
+ expect(proxy.redeemed()).toBe(0)
+ } finally {
+ await proxy.close()
+ }
+ }, 30_000)
+
it('T-R9-1c-grok refuses a gzip admin body with 415', async () => {
const proxy = await heldProxy(maxBodyBytes)
try {
diff --git a/grok-llm-proxy/test/requestLimits.test.ts b/grok-llm-proxy/test/requestLimits.test.ts
index cd7891d79..834365998 100644
--- a/grok-llm-proxy/test/requestLimits.test.ts
+++ b/grok-llm-proxy/test/requestLimits.test.ts
@@ -6,6 +6,8 @@ import {
RequestLimitError,
STREAM_LIMITS,
StreamGate,
+ VISUAL_STREAM_LIMITS,
+ visualStreamGate,
} from '../src/requestLimits.js'
import { DEFAULT_HEARTBEAT_INTERVAL_MS, MAX_HEARTBEAT_INTERVAL_MS } from '../src/sseHeartbeat.js'
@@ -383,4 +385,40 @@ describe('StreamGate', () => {
expect(() => new StreamGate(1, maxQueued), `maxQueued=${maxQueued}`).toThrow(RangeError)
}
})
+
+ // A V2 body above the ordinary cap keeps its image bytes resident for the
+ // whole upstream stream, so it takes a 1-wide sibling of the 8-wide gate.
+ // Widening it needs a new memory measurement against the 768Mi limit.
+ it('pins the visual 1/4 sibling against the ordinary 8/16 stream gate', () => {
+ expect(VISUAL_STREAM_LIMITS).toEqual({ maxConcurrentStreams: 1, maxQueuedRequests: 4 })
+ expect(STREAM_LIMITS.maxConcurrentStreams).toBe(8)
+ expect(STREAM_LIMITS.maxQueuedRequests).toBe(16)
+ })
+
+ it('rejects the 6th visual waiter once 1 is running and 4 are queued', async () => {
+ const gate = new StreamGate(
+ VISUAL_STREAM_LIMITS.maxConcurrentStreams,
+ VISUAL_STREAM_LIMITS.maxQueuedRequests
+ )
+ const held = await gate.acquire()
+ const queued = Array.from({ length: VISUAL_STREAM_LIMITS.maxQueuedRequests }, () =>
+ gate.acquire()
+ )
+ // Witness: the four waiters are queued, not refused, before the sixth.
+ expect(gate.snapshot()).toEqual({ running: 1, queued: 4 })
+ await expect(gate.acquire()).rejects.toBeInstanceOf(RequestLimitError)
+ held()
+ for (const waiter of queued) (await waiter)()
+ expect(gate.snapshot()).toEqual({ running: 0, queued: 0 })
+ })
+
+ it('builds the shared visual gate from VISUAL_STREAM_LIMITS', async () => {
+ const held = await visualStreamGate.acquire()
+ try {
+ expect(visualStreamGate.snapshot()).toEqual({ running: 1, queued: 0 })
+ } finally {
+ held()
+ }
+ expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ })
})
diff --git a/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts b/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
index 32ed06c18..2fb06a27e 100644
--- a/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
+++ b/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
@@ -77,6 +77,7 @@ function config(overrides: Partial<GrokLlmProxyConfig> = {}): GrokLlmProxyConfig
adminPort: 0,
probePort: 0,
maxBodyBytes: DEFAULT_MAX_BODY_BYTES,
+ maxVisualBodyBytes: 35 * 1024 * 1024,
maxStreamDurationMs: 30_000,
maxDeadlineMs: 30_000,
upstreamIdleTimeoutMs: 600_000,
diff --git a/grok-llm-proxy/test/server.security.test.ts b/grok-llm-proxy/test/server.security.test.ts
index daae3ea66..bafa8dd79 100644
--- a/grok-llm-proxy/test/server.security.test.ts
+++ b/grok-llm-proxy/test/server.security.test.ts
@@ -7,7 +7,9 @@ import request from 'supertest'
import {
ENVELOPE_ALLOWANCE_BYTES as CONTRACT_ENVELOPE_ALLOWANCE_BYTES,
LIMITS,
+ hashGrokCompletionRequest,
hashGrokCompletionRequestV1,
+ parseGrokCompletionRequest,
parseGrokCompletionRequestV1,
} from '@clerum/grok-provider-attempt-contract'
import { verifyAdminPermit } from '../src/auth/adminPermitVerifier.js'
@@ -19,7 +21,7 @@ import {
type FinalizeAttemptSuccess,
type RedeemAttemptSuccess,
} from '../src/controlApiClient.js'
-import { MAX_TOOL_CALL_ARGUMENT_BYTES } from '../src/grokTransport.js'
+import { GrokTransportError, MAX_TOOL_CALL_ARGUMENT_BYTES } from '../src/grokTransport.js'
import { REDACT_PATHS, logger } from '../src/logger.js'
import { GROK_CATALOG_ORIGIN, GROK_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
import {
@@ -29,6 +31,7 @@ import {
RequestLimitError,
STREAM_LIMITS,
streamGate,
+ visualStreamGate,
} from '../src/requestLimits.js'
import { createProxyApps } from '../src/server.js'
@@ -44,6 +47,7 @@ function config(overrides: Partial<GrokLlmProxyConfig> = {}): GrokLlmProxyConfig
adminPort: 8081,
probePort: 9090,
maxBodyBytes: 1024,
+ maxVisualBodyBytes: LIMITS.maxVisualRequestBodyBytes,
maxStreamDurationMs: 1_800_000,
maxDeadlineMs: 1_800_000,
upstreamIdleTimeoutMs: 600_000,
@@ -177,6 +181,155 @@ describe('grok-llm-proxy security surface', () => {
expect(res.status).toBe(413)
})
+ it('reserves the visual transport budget for an authenticated ~30 MiB V2 body', async () => {
+ const { runtimeApp, adminApp } = createProxyApps(config({ maxBodyBytes: DEFAULT_MAX_BODY_BYTES }))
+ // Deliberately invalid ticket: this test checks parser admission and the
+ // unchanged ticket gate, without redeeming or contacting any model. 30 MiB
+ // is past the Codex 24 MiB visual ceiling and inside the Grok 35 MiB one.
+ const payload = {
+ executionTicket: 'invalid-ticket',
+ requestHash: 'a'.repeat(64),
+ request: {
+ schemaVersion: 'grok-completion-request.v2',
+ messages: [
+ {
+ role: 'user',
+ contentParts: [{ type: 'image', data: 'A'.repeat(30 * 1024 * 1024) }],
+ },
+ ],
+ },
+ }
+ expect(Buffer.byteLength(JSON.stringify(payload))).toBeGreaterThan(24 * 1024 * 1024)
+ const admitted = await request(runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send(payload)
+ expect(admitted.status).toBe(403)
+ expect(admitted.body.error).toBe('ticket_invalid')
+ expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+
+ // R9-M-B: without a platform JWT the body is never read, so the caller
+ // gets 401 instead of a parser's 413. The 401 is written before the upload
+ // ends; a keep-alive client has the unread rest discarded.
+ const anonymous = await request(runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Connection', 'keep-alive')
+ .send(payload)
+ expect(anonymous.status).toBe(401)
+ const noScope = await request(runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Connection', 'keep-alive')
+ .set('Authorization', `Bearer ${platformToken({ workflowControlScopes: [] })}`)
+ .send(payload)
+ expect(noScope.status).toBe(401)
+ const v1 = await request(runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send({
+ ...payload,
+ request: { ...payload.request, schemaVersion: 'grok-completion-request.v1' },
+ })
+ expect(v1.status).toBe(413)
+ expect(v1.body.error).toBe('payload_too_large')
+ const admin = await request(adminApp)
+ .post('/internal/admin/v1/grok/models')
+ .set('Authorization', `Bearer ${adminPermit()}`)
+ .send(payload)
+ expect(admin.status).toBe(413)
+ expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ }, 30_000)
+
+ it('refuses a declared length past the visual ceiling with 413 before reading it', async () => {
+ const { runtimeApp } = createProxyApps(config({ maxBodyBytes: DEFAULT_MAX_BODY_BYTES }))
+ const pad = 'A'.repeat(LIMITS.maxVisualRequestBodyBytes)
+ const res = await request(runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .set('Connection', 'keep-alive')
+ .send({
+ executionTicket: 'invalid-ticket',
+ requestHash: 'a'.repeat(64),
+ request: { schemaVersion: 'grok-completion-request.v2', pad },
+ })
+ expect(res.status).toBe(413)
+ expect(res.body.error).toBe('payload_too_large')
+ expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ }, 30_000)
+
+ it('answers a transport payload_too_large with HTTP 413 before any SSE byte', async () => {
+ const raw = {
+ schemaVersion: 'grok-completion-request.v2',
+ requestId: 'req-payload-too-large',
+ idempotencyKey: 'idem-payload-too-large',
+ provider: 'grok-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'hello' }],
+ }
+ const parsed = parseGrokCompletionRequest(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
+ const executionTicket = sign(
+ {
+ jti: '12121212-1212-4121-8121-121212121212',
+ typ: 'grok-execution-ticket',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId: 'att-payload-too-large',
+ },
+ 'grok-llm-proxy'
+ )
+ let streamCalls = 0
+ const { runtimeApp, probeApp } = createProxyApps(config({ maxBodyBytes: 65_536 }), {
+ streamCompletion: async () => {
+ streamCalls += 1
+ throw new GrokTransportError('payload_too_large', 'request exceeds maxVisualRequestBodyBytes')
+ },
+ })
+ const res = await request(runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send({ executionTicket, requestHash, request: raw })
+ // Witness: the request reached the transport.
+ expect(streamCalls).toBe(1)
+ expect(res.status).toBe(413)
+ expect(res.body).toEqual({ error: 'payload_too_large' })
+ const metricsText = (await request(probeApp).get('/metrics')).text
+ expect(metricsText).toMatch(/^grok_proxy_attempt_failures_total\{code="payload_too_large"\} 1$/m)
+ })
+
+ it('does not let a V2 declaration raise the non-image budget to 35 MiB', async () => {
+ const { runtimeApp } = createProxyApps(config({ maxBodyBytes: DEFAULT_MAX_BODY_BYTES }))
+ // One byte of text past the non-image ceiling plus its envelope allowance,
+ // far under the 35 MiB visual ceiling the V2 declaration opens.
+ const pad = 'x'.repeat(LIMITS.maxRequestBodyBytes + ENVELOPE_ALLOWANCE_BYTES + 1)
+ const res = await request(runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send({
+ executionTicket: 'invalid-ticket',
+ requestHash: 'a'.repeat(64),
+ request: { schemaVersion: 'grok-completion-request.v2', pad },
+ })
+ expect(res.status).toBe(413)
+ expect(res.body.error).toBe('payload_too_large')
+ // Witness: the same body with an image-sized pad inside contentParts
+ // instead of text passes the size checks and stops at the ticket gate.
+ const imageSized = await request(runtimeApp)
+ .post('/internal/runtime/v1/grok/completions')
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send({
+ executionTicket: 'invalid-ticket',
+ requestHash: 'a'.repeat(64),
+ request: {
+ schemaVersion: 'grok-completion-request.v2',
+ messages: [{ role: 'user', contentParts: [{ type: 'image', data: pad }] }],
+ },
+ })
+ expect(imageSized.status).toBe(403)
+ expect(imageSized.body.error).toBe('ticket_invalid')
+ }, 30_000)
+
it('rejects a platform JWT whose hostRefs do not bind the ticket hostRef', async () => {
const { runtimeApp } = createProxyApps(config())
const foreign = sign(
@@ -595,6 +748,36 @@ describe('grok-llm-proxy startup config', () => {
)
})
+ it('defaults the visual body limit to the contract visual ceiling, with no allowance on top', () => {
+ expect(LIMITS.maxVisualRequestBodyBytes).toBe(36_700_160)
+ expect(loadConfig(base).maxVisualBodyBytes).toBe(LIMITS.maxVisualRequestBodyBytes)
+ })
+
+ it('refuses a visual body limit below the contract visual ceiling', () => {
+ expect(() =>
+ loadConfig({
+ ...base,
+ GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(LIMITS.maxVisualRequestBodyBytes - 1),
+ })
+ ).toThrow('Visual Grok requests require the full shared envelope byte budget')
+ expect(() => loadConfig({ ...base, GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: '1024' })).toThrow(
+ /shared envelope byte budget/
+ )
+ // Witness: the ceiling itself and any larger value load.
+ expect(
+ loadConfig({
+ ...base,
+ GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(LIMITS.maxVisualRequestBodyBytes),
+ }).maxVisualBodyBytes
+ ).toBe(LIMITS.maxVisualRequestBodyBytes)
+ expect(
+ loadConfig({
+ ...base,
+ GROK_LLM_PROXY_MAX_VISUAL_BODY_BYTES: String(LIMITS.maxVisualRequestBodyBytes + 1),
+ }).maxVisualBodyBytes
+ ).toBe(LIMITS.maxVisualRequestBodyBytes + 1)
+ })
+
it('T-R2-6c-grok does not refuse a request at the contract cap with a real ticket as payload_too_large', async () => {
const { runtimeApp } = createProxyApps(config({ maxBodyBytes: loadConfig(base).maxBodyBytes }))
const atCap = { pad: 'x'.repeat(LIMITS.maxRequestBodyBytes - '{"pad":""}'.length) }
@@ -1684,6 +1867,88 @@ describe('grok-llm-proxy ticket-aware stream-gate wait (#739 D1-bis)', () => {
await releaseAndDrain(slots)
}
}, 30_000)
+
+ /** A V2 envelope past `maxBodyBytes`, so it takes the visual gate. */
+ function visualEnvelope(providerAttemptId: string, ticketLifeMs: number): Record<string, unknown> {
+ const raw: Record<string, unknown> = {
+ schemaVersion: 'grok-completion-request.v2',
+ requestId: `req-${providerAttemptId}`,
+ idempotencyKey: `idem-${providerAttemptId}`,
+ provider: 'grok-subscription',
+ model: 'gpt-5.1',
+ messages: [{ role: 'user', content: 'x'.repeat(80_000) }],
+ }
+ const parsed = parseGrokCompletionRequest(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
+ const executionTicket = jwt.sign(
+ {
+ jti: '78787878-7878-4787-8787-787878787878',
+ typ: 'grok-execution-ticket',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash,
+ providerAttemptId,
+ exp: (Date.now() + ticketLifeMs) / 1000,
+ },
+ privateKey,
+ { algorithm: 'RS256', issuer: 'control-api', audience: 'grok-llm-proxy' }
+ )
+ return { executionTicket, requestHash, request: raw }
+ }
+
+ // R17-2 on the visual path: the visual gate is taken before the body is
+ // parsed, so the ticket is read only once the slot frees. A ticket that died
+ // during that wait reaches the ticket gate expired, and the answer is the
+ // retryable ticket_expired, not the stream gate's ticket-life refusal.
+ it('T-R17-2-visual-grok answers ticket_expired when the ticket died while the body waited at the visual gate', async () => {
+ fakeClock()
+ const warn = vi.spyOn(logger, 'warn')
+ let held: (() => void) | undefined
+ try {
+ held = await visualStreamGate.acquire()
+ const control = countingClient('granted')
+ const apps = createProxyApps(config({ maxBodyBytes: 65_536 }), {
+ controlApiClient: control.client,
+ fetchFn: upstream,
+ lookup,
+ })
+ const ticketLifeMs = 20_000
+ const body = visualEnvelope('att-visual-expired', ticketLifeMs)
+ expect(Buffer.byteLength(JSON.stringify(body))).toBeGreaterThan(65_536)
+ const reply = request(apps.runtimeApp)
+ .post(COMPLETIONS)
+ .set('Authorization', `Bearer ${platformToken()}`)
+ .send(body)
+ .then(res => res)
+ await until(() => visualStreamGate.snapshot().queued === 1, 'the body queueing at the visual gate')
+
+ await vi.advanceTimersByTimeAsync(ticketLifeMs)
+ // Witness: the body was still waiting for the slot at the ticket's expiry.
+ expect(await withinReal(reply, 100)).toBeUndefined()
+ held()
+ held = undefined
+ // One stream-gate poll interval.
+ await vi.advanceTimersByTimeAsync(10)
+ const res = await withinReal(reply, 2_000)
+ expect(res?.status).toBe(403)
+ expect(res?.body).toEqual({ error: 'ticket_expired' })
+ expect(control.redeems()).toBe(0)
+
+ const events = warn.mock.calls.map(call => call[0] as unknown as Record<string, unknown>)
+ expect(events.filter(entry => entry?.event === 'grok_proxy_denied')).toEqual([
+ { event: 'grok_proxy_denied', code: 'ticket_expired' },
+ ])
+ expect(events.filter(entry => entry?.event === 'grok_proxy_admission_refused')).toEqual([])
+ // The ticket refusal released the visual slot the body was parsed under.
+ expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ expect(streamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ } finally {
+ held?.()
+ vi.useRealTimers()
+ warn.mockRestore()
+ }
+ }, 30_000)
})
/**
diff --git a/grok-llm-proxy/test/sseBackpressure.test.ts b/grok-llm-proxy/test/sseBackpressure.test.ts
index 88c6e11b3..49a10e3dd 100644
--- a/grok-llm-proxy/test/sseBackpressure.test.ts
+++ b/grok-llm-proxy/test/sseBackpressure.test.ts
@@ -91,6 +91,7 @@ function config(): GrokLlmProxyConfig {
adminPort: 0,
probePort: 0,
maxBodyBytes: DEFAULT_MAX_BODY_BYTES,
+ maxVisualBodyBytes: 35 * 1024 * 1024,
maxStreamDurationMs: 60_000,
maxDeadlineMs: 60_000,
upstreamIdleTimeoutMs: 600_000,
diff --git a/grok-llm-proxy/test/streamGate.handoff.test.ts b/grok-llm-proxy/test/streamGate.handoff.test.ts
new file mode 100644
index 000000000..1f9b98cd5
--- /dev/null
+++ b/grok-llm-proxy/test/streamGate.handoff.test.ts
@@ -0,0 +1,369 @@
+import { generateKeyPairSync } from 'node:crypto'
+import { createServer } from 'node:http'
+import { connect as connectTcp } from 'node:net'
+import jwt from 'jsonwebtoken'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+ hashGrokCompletionRequest,
+ parseGrokCompletionRequest,
+} from '@clerum/grok-provider-attempt-contract'
+import { type GrokLlmProxyConfig } from '../src/config.js'
+import { createProxyApps } from '../src/server.js'
+import {
+ STREAM_LIMITS,
+ VISUAL_STREAM_LIMITS,
+ streamGate,
+ visualStreamGate,
+} from '../src/requestLimits.js'
+
+const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+ modulusLength: 2048,
+ publicKeyEncoding: { type: 'spki', format: 'pem' },
+ privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+})
+
+const COMPLETIONS_PATH = '/internal/runtime/v1/grok/completions'
+
+type SchemaVersion = 'grok-completion-request.v1' | 'grok-completion-request.v2'
+
+function config(overrides: Partial<GrokLlmProxyConfig> = {}): GrokLlmProxyConfig {
+ return {
+ runtimePort: 8080,
+ adminPort: 8081,
+ probePort: 9090,
+ maxBodyBytes: 1_048_576,
+ maxVisualBodyBytes: 35 * 1024 * 1024,
+ maxStreamDurationMs: 1_800_000,
+ maxDeadlineMs: 1_800_000,
+ upstreamIdleTimeoutMs: 600_000,
+ heartbeatIntervalMs: 15_000,
+ jwtIssuer: 'control-api',
+ jwtPublicKey: publicKey,
+ executionEnabled: true,
+ controlApiBaseUrl: '',
+ controlApiServiceName: 'grok-llm-proxy',
+ controlApiServiceToken: '',
+ ...overrides,
+ }
+}
+
+function sign(payload: Record<string, unknown>, audience: string): string {
+ return jwt.sign(payload, privateKey, {
+ algorithm: 'RS256',
+ issuer: 'control-api',
+ audience,
+ expiresIn: 60,
+ })
+}
+
+function platformToken(): string {
+ return sign(
+ {
+ sub: 'default/research-host',
+ hostRefs: ['research-host'],
+ workflowControlScopes: ['llm:grok:execute'],
+ scope: 'workflow:approval:request',
+ },
+ 'workflow-approvals'
+ )
+}
+
+let ticketSeq = 1
+
+function ticket(requestHash: string): string {
+ ticketSeq += 1
+ return sign(
+ {
+ jti: `11111111-1111-4111-8111-${String(ticketSeq).padStart(12, '0')}`,
+ typ: 'grok-execution-ticket',
+ hostRef: 'research-host',
+ model: 'grok-4.6',
+ requestHash,
+ providerAttemptId: `att-${ticketSeq}`,
+ },
+ 'grok-llm-proxy'
+ )
+}
+
+function completionRequest(schemaVersion: SchemaVersion, content = 'hi') {
+ ticketSeq += 1
+ return {
+ schemaVersion,
+ requestId: `req-gate-${ticketSeq}`,
+ idempotencyKey: `idem-gate-${ticketSeq}`,
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ messages: [{ role: 'user', content }],
+ }
+}
+
+function hangStream() {
+ let releaseHeld!: () => void
+ const held = new Promise<void>(resolve => {
+ releaseHeld = resolve
+ })
+ return {
+ release: () => releaseHeld(),
+ impl: async () => {
+ await held
+ return { outcome: 'canceled' as const }
+ },
+ }
+}
+
+async function waitFor(predicate: () => boolean, label: string): Promise<void> {
+ const started = Date.now()
+ while (!predicate()) {
+ if (Date.now() - started > 5_000) throw new Error(label)
+ await new Promise(resolve => setTimeout(resolve, 10))
+ }
+}
+
+function completionPayload(
+ schemaVersion: SchemaVersion,
+ content = 'hi'
+): { token: string; body: string } {
+ const raw = completionRequest(schemaVersion, content)
+ const parsed = parseGrokCompletionRequest(raw)
+ if (!parsed.ok) throw new Error(parsed.message)
+ const requestHash = hashGrokCompletionRequest(parsed.value)
+ return {
+ token: platformToken(),
+ body: JSON.stringify({
+ executionTicket: ticket(requestHash),
+ requestHash,
+ request: raw,
+ }),
+ }
+}
+
+async function postCompletion(
+ port: number,
+ schemaVersion: SchemaVersion,
+ content = 'hi'
+): Promise<Response> {
+ const { token, body } = completionPayload(schemaVersion, content)
+ return fetch(`http://127.0.0.1:${port}${COMPLETIONS_PATH}`, {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${token}`,
+ 'content-type': 'application/json',
+ },
+ body,
+ })
+}
+
+function postChunked(port: number, token: string): Promise<number> {
+ return new Promise((resolve, reject) => {
+ const socket = connectTcp(port, '127.0.0.1', () => {
+ const chunk = Buffer.from('{}')
+ socket.write(
+ `POST ${COMPLETIONS_PATH} HTTP/1.1\r\n` +
+ `Host: 127.0.0.1:${port}\r\n` +
+ `Authorization: Bearer ${token}\r\n` +
+ `Content-Type: application/json\r\n` +
+ `Connection: close\r\n` +
+ `Transfer-Encoding: chunked\r\n` +
+ `\r\n` +
+ `${chunk.length.toString(16)}\r\n`
+ )
+ socket.write(chunk)
+ socket.write('\r\n0\r\n\r\n')
+ })
+ const chunks: Buffer[] = []
+ const finish = () => {
+ const raw = Buffer.concat(chunks).toString('utf8')
+ const match = /^HTTP\/1\.1 (\d+)/.exec(raw)
+ if (!match) {
+ reject(new Error(`no status in ${raw.slice(0, 180)}`))
+ return
+ }
+ resolve(Number(match[1]))
+ }
+ socket.setTimeout(2_000, () => {
+ socket.destroy()
+ finish()
+ })
+ socket.on('data', data => {
+ chunks.push(data)
+ if (Buffer.concat(chunks).toString('utf8').includes('\r\n\r\n')) {
+ socket.destroy()
+ finish()
+ }
+ })
+ socket.on('error', err => {
+ if ((err as NodeJS.ErrnoException).code !== 'ECONNRESET') reject(err)
+ })
+ socket.on('close', finish)
+ })
+}
+
+describe('grok visual stream-gate handoff', () => {
+ const hangs: Array<{ release: () => void }> = []
+ const serversToClose: Array<{ close: () => Promise<void> }> = []
+ const listeners: Array<ReturnType<typeof createServer>> = []
+
+ afterEach(async () => {
+ for (const hang of hangs.splice(0)) hang.release()
+ for (const server of serversToClose.splice(0)) await server.close()
+ await Promise.all(
+ listeners.splice(0).map(
+ listener =>
+ new Promise<void>((resolve, reject) =>
+ listener.close(err => (err ? reject(err) : resolve()))
+ )
+ )
+ )
+ await waitFor(
+ () =>
+ visualStreamGate.snapshot().running === 0 &&
+ visualStreamGate.snapshot().queued === 0 &&
+ streamGate.snapshot().running === 0 &&
+ streamGate.snapshot().queued === 0,
+ 'gates did not drain after release'
+ )
+ })
+
+ function listen(servers: ReturnType<typeof createProxyApps>): number {
+ serversToClose.push(servers)
+ const listener = createServer(servers.runtimeApp).listen(0)
+ listeners.push(listener)
+ const address = listener.address()
+ if (!address || typeof address === 'string') throw new Error('listener has no port')
+ return address.port
+ }
+
+ it('keeps small V1 text off the visual gate while a large V2 stream holds it', async () => {
+ expect(VISUAL_STREAM_LIMITS.maxConcurrentStreams).toBe(1)
+ expect(STREAM_LIMITS.maxConcurrentStreams).toBe(8)
+
+ const small = completionPayload('grok-completion-request.v1')
+ const maxBodyBytes = Buffer.byteLength(small.body) + 512
+ const largeContent = 'x'.repeat(maxBodyBytes)
+ const large = completionPayload('grok-completion-request.v2', largeContent)
+ expect(Buffer.byteLength(large.body)).toBeGreaterThan(maxBodyBytes)
+
+ const hang = hangStream()
+ hangs.push(hang)
+ const port = listen(
+ createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 }), {
+ streamCompletion: hang.impl,
+ })
+ )
+
+ const firstVisual = postCompletion(port, 'grok-completion-request.v2', largeContent)
+ await waitFor(
+ () => visualStreamGate.snapshot().running === 1 && streamGate.snapshot().running === 0,
+ 'large V2 did not hold the visual gate'
+ )
+
+ const v1 = postCompletion(port, 'grok-completion-request.v1')
+ await waitFor(
+ () => streamGate.snapshot().running === 1 && visualStreamGate.snapshot().running === 1,
+ 'small V1 waited on the visual gate instead of the ordinary stream gate'
+ )
+
+ const queued = Array.from({ length: VISUAL_STREAM_LIMITS.maxQueuedRequests }, () =>
+ postCompletion(port, 'grok-completion-request.v2', largeContent)
+ )
+ await waitFor(
+ () => visualStreamGate.snapshot().queued === VISUAL_STREAM_LIMITS.maxQueuedRequests,
+ 'visual queue did not fill to 4'
+ )
+ // One running and four queued: the sixth large V2 is refused.
+ const overflow = await postCompletion(port, 'grok-completion-request.v2', largeContent)
+ expect(overflow.status).toBe(503)
+ expect(await overflow.json()).toEqual({ error: 'provider_unavailable' })
+
+ const textWhileSaturated = postCompletion(port, 'grok-completion-request.v1')
+ await waitFor(
+ () => streamGate.snapshot().running === 2 && visualStreamGate.snapshot().running === 1,
+ 'a small V1 was rejected or queued behind a saturated image stream'
+ )
+
+ hang.release()
+ await Promise.all([v1, textWhileSaturated, firstVisual, ...queued])
+ })
+
+ it('does not queue a chunked platform body behind a saturated image stream', async () => {
+ const small = completionPayload('grok-completion-request.v1')
+ const maxBodyBytes = Buffer.byteLength(small.body) + 512
+ const largeContent = 'x'.repeat(maxBodyBytes)
+ const hang = hangStream()
+ hangs.push(hang)
+ const port = listen(
+ createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 }), {
+ streamCompletion: hang.impl,
+ })
+ )
+
+ const firstVisual = postCompletion(port, 'grok-completion-request.v2', largeContent)
+ await waitFor(
+ () => visualStreamGate.snapshot().running === 1 && visualStreamGate.snapshot().queued === 0,
+ 'large V2 did not fill the visual gate'
+ )
+
+ // #731 R3-2 body admission refuses a body of undeclared length before it
+ // reaches the transport budget, so the answer arrives while the visual
+ // slot is still held.
+ const status = await postChunked(port, platformToken())
+ expect(status).toBe(411)
+ expect(visualStreamGate.snapshot()).toEqual({ running: 1, queued: 0 })
+
+ hang.release()
+ await firstVisual
+ })
+
+ it('rejects a between-cap V1 with 413 and leaves the visual gate empty', async () => {
+ const small = completionPayload('grok-completion-request.v1')
+ const maxBodyBytes = Buffer.byteLength(small.body) + 512
+ const largeContent = 'x'.repeat(maxBodyBytes)
+ const large = completionPayload('grok-completion-request.v1', largeContent)
+ expect(Buffer.byteLength(large.body)).toBeGreaterThan(maxBodyBytes)
+
+ const port = listen(createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 })))
+
+ const response = await fetch(`http://127.0.0.1:${port}${COMPLETIONS_PATH}`, {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${large.token}`,
+ 'content-type': 'application/json',
+ },
+ body: large.body,
+ })
+ expect(response.status).toBe(413)
+ expect(await response.json()).toEqual({ error: 'payload_too_large' })
+ expect(visualStreamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ expect(streamGate.snapshot()).toEqual({ running: 0, queued: 0 })
+ })
+
+ it('releases the visual slot for a whitespace-padded small V2', async () => {
+ const small = completionPayload('grok-completion-request.v2')
+ const maxBodyBytes = Buffer.byteLength(small.body) + 64
+ const padded = `${small.body}${' '.repeat(maxBodyBytes - Buffer.byteLength(small.body) + 1)}`
+ expect(Buffer.byteLength(padded)).toBeGreaterThan(maxBodyBytes)
+
+ const hang = hangStream()
+ hangs.push(hang)
+ const port = listen(
+ createProxyApps(config({ maxBodyBytes, maxVisualBodyBytes: 1024 * 1024 }), {
+ streamCompletion: hang.impl,
+ })
+ )
+
+ const response = fetch(`http://127.0.0.1:${port}${COMPLETIONS_PATH}`, {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${small.token}`,
+ 'content-type': 'application/json',
+ },
+ body: padded,
+ })
+ await waitFor(
+ () => streamGate.snapshot().running === 1 && visualStreamGate.snapshot().running === 0,
+ 'padded small V2 kept the visual slot instead of the ordinary stream gate'
+ )
+ hang.release()
+ await response
+ })
+})
diff --git a/scripts/tests/test-grok-subscription-t0.sh b/scripts/tests/test-grok-subscription-t0.sh
index 7740d55d5..e22a963ca 100755
--- a/scripts/tests/test-grok-subscription-t0.sh
+++ b/scripts/tests/test-grok-subscription-t0.sh
@@ -249,6 +249,7 @@ run_group "grok-llm-proxy" "grok-llm-proxy" \
"test/server.security.test.ts" \
"test/sseBackpressure.test.ts" \
"test/sseHeartbeat.test.ts" \
+ "test/streamGate.handoff.test.ts" \
"test/toolNameMap.test.ts" \
"test/upstreamErrorHint.test.ts"