Skip to content

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

TypeScript

feat(grok): send the client version xAI gates on under an Evenfire identity

Jose Gabriel Ramirez Encinas8970efc37e72
diff --git a/control-ui/components/CodexSubscriptionHub/index.tsx b/control-ui/components/CodexSubscriptionHub/index.tsx
index f3d6ef2e0..c00a6c475 100644
--- a/control-ui/components/CodexSubscriptionHub/index.tsx
+++ b/control-ui/components/CodexSubscriptionHub/index.tsx
@@ -117,7 +117,7 @@ function nextDevicePollIntervalSeconds(
}
const GROK_TOS =
- 'Connecting a Grok subscription authenticates Evenfire to xAI with the SuperGrok / Grok Build coding-plan OAuth client. Inference stays on cli-chat-proxy.grok.com and is not the metered xAI API.'
+ 'Connecting a Grok subscription authenticates Evenfire to xAI with the SuperGrok / Grok Build coding-plan OAuth client. Inference stays on cli-chat-proxy.grok.com and is not the metered xAI API. Evenfire identifies itself to xAI as Evenfire and sends the Grok Build compatibility version that endpoint requires; this is not an xAI-sanctioned integration, xAI may restrict it, and runs draw on this account’s Grok quota. For a sanctioned path, use an xAI API key instead.'
async function copyDeviceValue(
value: string,
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index ee88e958a..55057f0bb 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.603",
+ "version": "0.1.604",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.603",
+ "version": "0.1.604",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
diff --git a/control-ui/package.json b/control-ui/package.json
index 4746cc0f1..e5c50bedf 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.603",
+ "version": "0.1.604",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 97f699417..c512e963d 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -142,12 +142,35 @@ Proxy robustness (both proxies):
Stamped in `grok-llm-proxy`, never taken from mcp-host or the hashed request:
-- `user-agent: evenfire-grok-subscription`
+- `user-agent: evenfire-grok-subscription grok-build/<clientVersion>`
+- `x-grok-client-version: <clientVersion>` — default `1.0.34`, overridden with
+ `GROK_LLM_PROXY_CLIENT_VERSION`; a malformed override falls back to the pinned
+ default rather than sending a value xAI would refuse
+- `x-grok-client-identifier: evenfire`
+- `x-grok-client-mode: headless`
+- `x-xai-token-auth: xai-grok-cli` — the token TYPE designator for an OAuth
+ session token, not a claim to be the CLI
- `accept: text/event-stream` on stream
-CLI impersonation headers (`x-xai-token-auth`, `x-grok-client-identifier`) stay
-off until a recorded SuperGrok probe requires them. Do not send `OpenAI-Beta`
-or `service_tier`.
+**Probe record (2026-09-18, local minikube against live SuperGrok).** With only
+`user-agent: evenfire-grok-subscription` and no version, `POST /v1/responses`
+returned `426` with `{"error":"Your Grok CLI version (none) is outdated. Please
+update to version 0.1.202 or later …"}`, while `GET /v1/models` succeeded and
+synced a catalog. So xAI gates inference on a client version. Evenfire sends
+that version but keeps its own identity: never `grok-shell`,
+`xai-grok-workspace`, or any other CLI-owned identifier — the same rule the
+Codex adapter follows with `originator: evenfire`
+(`codex-llm-proxy/src/chatgptUpstreamHeaders.ts`). This is not an
+xAI-sanctioned integration; the sanctioned automation path is an xAI API key
+(the separate metered `xai` provider). Prod enablement still needs the D15
+human ToS sign-off, and the Control UI connect copy discloses it.
+
+**When xAI raises the floor**, the proxy returns `426` →
+`client_upgrade_required` (non-retryable, one clean failure, no retry storm).
+Fix it by setting `GROK_LLM_PROXY_CLIENT_VERSION` to a current published
+`@xai-official/grok` release; no code release is required.
+
+Do not send `OpenAI-Beta` or `service_tier`.
`max_output_tokens` is bindable on this wire and is sent.
diff --git a/grok-llm-proxy/src/grokUpstreamHeaders.ts b/grok-llm-proxy/src/grokUpstreamHeaders.ts
index 506f03279..3e9b613c3 100644
--- a/grok-llm-proxy/src/grokUpstreamHeaders.ts
+++ b/grok-llm-proxy/src/grokUpstreamHeaders.ts
@@ -1,17 +1,52 @@
/**
- * Identity headers stamped in the proxy. Live SuperGrok may later require
- * Grok-CLI impersonation headers; the starting freeze uses Evenfire identity
- * only and never sends OpenAI-Beta or api.x.ai headers.
+ * Identity headers stamped in the proxy.
+ *
+ * xAI's Grok Build proxy gates subscription inference on a client version: a
+ * request without one is refused with 426 ("Your Grok CLI version (none) is
+ * outdated"), recorded by the live probe on 2026-09-18. Evenfire therefore
+ * sends the compatibility version xAI checks, but identifies itself honestly:
+ * the client identifier and user agent name Evenfire, never `grok-shell` or
+ * `xai-grok-workspace`. This mirrors the Codex adapter, which sends the
+ * product headers OpenAI expects under `originator: evenfire` and explicitly
+ * does not impersonate `codex_cli_rs`.
+ *
+ * `x-xai-token-auth` designates the token TYPE for any OAuth session token; it
+ * is not a claim to be the CLI.
+ *
+ * The version is the only value xAI moves. Operators override it with
+ * GROK_LLM_PROXY_CLIENT_VERSION when xAI raises the floor, so a bump is a
+ * config change and not a release.
*/
export const GROK_UPSTREAM_USER_AGENT = 'evenfire-grok-subscription'
+export const GROK_UPSTREAM_CLIENT_IDENTIFIER = 'evenfire'
+export const GROK_UPSTREAM_CLIENT_MODE = 'headless'
+export const GROK_UPSTREAM_TOKEN_AUTH = 'xai-grok-cli'
+/** Pinned to a real published @xai-official/grok release (floor was 0.1.202). */
+export const GROK_UPSTREAM_DEFAULT_CLIENT_VERSION = '1.0.34'
+
+const CLIENT_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+
+/**
+ * A real dotted release, or the pinned default. A malformed override falls back
+ * rather than sending a value xAI would reject, which would look like an outage.
+ */
+export function resolveGrokClientVersion(raw: string | undefined): string {
+ const value = raw?.trim() ?? ''
+ return CLIENT_VERSION_PATTERN.test(value) ? value : GROK_UPSTREAM_DEFAULT_CLIENT_VERSION
+}
export function grokUpstreamHeaders(
accessToken: string,
- extra: Record<string, string> = {}
+ extra: Record<string, string> = {},
+ clientVersion: string = resolveGrokClientVersion(process.env.GROK_LLM_PROXY_CLIENT_VERSION)
): Record<string, string> {
return {
authorization: `Bearer ${accessToken}`,
- 'user-agent': GROK_UPSTREAM_USER_AGENT,
+ 'user-agent': `${GROK_UPSTREAM_USER_AGENT} grok-build/${clientVersion}`,
+ 'x-grok-client-version': clientVersion,
+ 'x-grok-client-identifier': GROK_UPSTREAM_CLIENT_IDENTIFIER,
+ 'x-grok-client-mode': GROK_UPSTREAM_CLIENT_MODE,
+ 'x-xai-token-auth': GROK_UPSTREAM_TOKEN_AUTH,
accept: extra.accept ?? 'text/event-stream',
...extra,
}
diff --git a/grok-llm-proxy/test/contractFreeze.test.ts b/grok-llm-proxy/test/contractFreeze.test.ts
index cd935e7e6..ea509da72 100644
--- a/grok-llm-proxy/test/contractFreeze.test.ts
+++ b/grok-llm-proxy/test/contractFreeze.test.ts
@@ -8,7 +8,10 @@ import {
LIMITS,
TRANSPORT_PROTOCOL_VERSION,
} from '@clerum/grok-provider-attempt-contract'
-import { GROK_UPSTREAM_USER_AGENT } from '../src/grokUpstreamHeaders.js'
+import {
+ GROK_UPSTREAM_CLIENT_IDENTIFIER,
+ GROK_UPSTREAM_USER_AGENT,
+} from '../src/grokUpstreamHeaders.js'
import {
GROK_CATALOG_ORIGIN,
GROK_COMPLETIONS_ORIGIN,
@@ -33,7 +36,7 @@ describe('grok-subscription contract freeze', () => {
supportedOperations: string[]
oauthScopes: string[]
limits: Record<string, number>
- identityHeaders: { 'user-agent': string; cliImpersonation: boolean }
+ identityHeaders: Record<string, string | boolean>
forbiddenOrigins: string[]
}
@@ -48,8 +51,17 @@ describe('grok-subscription contract freeze', () => {
expect(fixture.limits.maxToolCalls).toBe(LIMITS.maxToolCalls)
expect(fixture.limits.maxToolCalls).toBe(64)
expect(fixture.limits.maxRetriesPerAttempt).toBe(1)
- expect(fixture.identityHeaders['user-agent']).toBe(GROK_UPSTREAM_USER_AGENT)
+ // Live xAI gates subscription inference on a client version (426 probe,
+ // 2026-09-18), so we send one — but the identity stays Evenfire's and never
+ // claims to be the Grok CLI itself.
+ expect(String(fixture.identityHeaders['user-agent'])).toContain(GROK_UPSTREAM_USER_AGENT)
+ expect(fixture.identityHeaders['x-grok-client-identifier']).toBe(
+ GROK_UPSTREAM_CLIENT_IDENTIFIER
+ )
+ expect(fixture.identityHeaders['x-xai-token-auth']).toBe('xai-grok-cli')
expect(fixture.identityHeaders.cliImpersonation).toBe(false)
+ expect(JSON.stringify(fixture.identityHeaders)).not.toContain('grok-shell')
+ expect(JSON.stringify(fixture.identityHeaders)).not.toContain('xai-grok-workspace')
expect(fixture.oauthScopes).toEqual(
expect.arrayContaining(['openid', 'offline_access', 'grok-cli:access', 'api:access'])
)
diff --git a/grok-llm-proxy/test/grokTransport.conformance.test.ts b/grok-llm-proxy/test/grokTransport.conformance.test.ts
index b52673e2d..364bfde80 100644
--- a/grok-llm-proxy/test/grokTransport.conformance.test.ts
+++ b/grok-llm-proxy/test/grokTransport.conformance.test.ts
@@ -354,9 +354,17 @@ describe('streamGrokCompletion', () => {
expect(String(headerOf(fetchFn.mock.calls[0]?.[1], 'authorization'))).toContain(
accessTokenFor('live')
)
- expect(headerOf(fetchFn.mock.calls[0]?.[1], 'user-agent')).toBe('evenfire-grok-subscription')
+ // xAI gates on a client version; we send it under an Evenfire identity.
+ expect(String(headerOf(fetchFn.mock.calls[0]?.[1], 'user-agent'))).toMatch(
+ /^evenfire-grok-subscription grok-build\/\d+\.\d+\.\d+/
+ )
+ expect(String(headerOf(fetchFn.mock.calls[0]?.[1], 'x-grok-client-version'))).toMatch(
+ /^\d+\.\d+\.\d+/
+ )
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'x-grok-client-identifier')).toBe('evenfire')
+ expect(headerOf(fetchFn.mock.calls[0]?.[1], 'x-xai-token-auth')).toBe('xai-grok-cli')
+ expect(String(JSON.stringify(fetchFn.mock.calls[0]?.[1]?.headers))).not.toContain('grok-shell')
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')
})
diff --git a/grok-llm-proxy/test/grokUpstreamHeaders.test.ts b/grok-llm-proxy/test/grokUpstreamHeaders.test.ts
index 561435565..7a3015b90 100644
--- a/grok-llm-proxy/test/grokUpstreamHeaders.test.ts
+++ b/grok-llm-proxy/test/grokUpstreamHeaders.test.ts
@@ -1,16 +1,42 @@
import { describe, expect, it } from 'vitest'
-import { GROK_UPSTREAM_USER_AGENT, grokUpstreamHeaders } from '../src/grokUpstreamHeaders.js'
+import {
+ GROK_UPSTREAM_CLIENT_IDENTIFIER,
+ GROK_UPSTREAM_DEFAULT_CLIENT_VERSION,
+ GROK_UPSTREAM_USER_AGENT,
+ grokUpstreamHeaders,
+ resolveGrokClientVersion,
+} from '../src/grokUpstreamHeaders.js'
describe('grokUpstreamHeaders', () => {
- it('stamps Evenfire identity and does not impersonate the Grok CLI', () => {
- const headers = grokUpstreamHeaders('access-secret', { 'content-type': 'application/json' })
- expect(headers['user-agent']).toBe(GROK_UPSTREAM_USER_AGENT)
- expect(headers.accept).toBe('text/event-stream')
+ it('sends the compatibility version xAI gates on without impersonating the Grok CLI', () => {
+ const headers = grokUpstreamHeaders(
+ 'access-secret',
+ { 'content-type': 'application/json' },
+ '1.0.34'
+ )
+ expect(headers['x-grok-client-version']).toBe('1.0.34')
+ expect(headers['x-xai-token-auth']).toBe('xai-grok-cli')
+ expect(headers['x-grok-client-identifier']).toBe(GROK_UPSTREAM_CLIENT_IDENTIFIER)
+ expect(headers['x-grok-client-mode']).toBe('headless')
+ expect(headers['user-agent']).toBe(`${GROK_UPSTREAM_USER_AGENT} grok-build/1.0.34`)
expect(headers.authorization).toBe('Bearer access-secret')
- expect(headers['openai-beta']).toBeUndefined()
- expect(headers['x-xai-token-auth']).toBeUndefined()
- expect(headers['x-grok-client-identifier']).toBeUndefined()
+ expect(headers.accept).toBe('text/event-stream')
+ // Identity stays Evenfire's: never the CLI's own identifier or UA product.
expect(JSON.stringify(headers)).not.toContain('grok-shell')
+ expect(JSON.stringify(headers)).not.toContain('xai-grok-workspace')
+ expect(headers['openai-beta']).toBeUndefined()
expect(JSON.stringify(headers)).not.toMatch(/sk-|refresh-secret/i)
})
+
+ it('takes a real dotted release from the operator override', () => {
+ expect(resolveGrokClientVersion('1.2.3')).toBe('1.2.3')
+ expect(resolveGrokClientVersion('0.1.202')).toBe('0.1.202')
+ expect(resolveGrokClientVersion('2.0.0-rc.1')).toBe('2.0.0-rc.1')
+ })
+
+ it('falls back to the pinned release when the override is missing or malformed', () => {
+ for (const bad of [undefined, '', ' ', 'latest', '1.0', 'v1.0.34', '1.0.34; rm -rf /']) {
+ expect(resolveGrokClientVersion(bad)).toBe(GROK_UPSTREAM_DEFAULT_CLIENT_VERSION)
+ }
+ })
})
diff --git a/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts b/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
index 0c392b51d..48b351c29 100644
--- a/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
+++ b/grok-llm-proxy/test/runtimePath.hermetic.e2e.test.ts
@@ -216,7 +216,9 @@ async function handleUpstream(req: IncomingMessage, res: ServerResponse): Promis
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
+ !String(req.headers['user-agent'] ?? '').startsWith(GROK_UPSTREAM_USER_AGENT) ||
+ // Mirror the live gate: refuse a request that carries no client version.
+ !/^\d+\.\d+\.\d+/.test(String(req.headers['x-grok-client-version'] ?? ''))
) {
counters.rejected += 1
json(res, 401, { error: 'unauthorized' })
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index ab901ab32..98cae4676 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.346",
+ "version": "0.1.347",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.346",
+ "version": "0.1.347",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 57b9f0478..8aa4e44c6 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.346",
+ "version": "0.1.347",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/llm/grokLlmProxyClient.ts b/mcp-host/src/llm/grokLlmProxyClient.ts
index 4955604c3..9010735c1 100644
--- a/mcp-host/src/llm/grokLlmProxyClient.ts
+++ b/mcp-host/src/llm/grokLlmProxyClient.ts
@@ -6,7 +6,7 @@ export const GROK_PROXY_COMPLETIONS_PATH = '/internal/runtime/v1/grok/completion
*/
export function grokProxyErrorMessage(code: string, status?: number): string {
if (code === 'client_upgrade_required') {
- return 'Grok subscription inference is unavailable: xAI requires a newer Grok client version than this Evenfire build presents. Contact support to upgrade — retrying will not help.'
+ return 'Grok subscription inference is unavailable: xAI now requires a newer Grok client version than this deployment sends. An operator can set GROK_LLM_PROXY_CLIENT_VERSION to a current Grok Build release, or contact support — retrying will not help.'
}
return status === undefined
? `proxy stream failed with ${code}`
diff --git a/tests/e2e/fixtures/grok-subscription/sanitized-upstream-contract.json b/tests/e2e/fixtures/grok-subscription/sanitized-upstream-contract.json
index f8f4fb599..2a68126fe 100644
--- a/tests/e2e/fixtures/grok-subscription/sanitized-upstream-contract.json
+++ b/tests/e2e/fixtures/grok-subscription/sanitized-upstream-contract.json
@@ -46,7 +46,11 @@
],
"oauthClientId": "b1a00492-073a-47ea-816f-4c329264a828",
"identityHeaders": {
- "user-agent": "evenfire-grok-subscription",
+ "user-agent": "evenfire-grok-subscription grok-build/<clientVersion>",
+ "x-grok-client-version": "<clientVersion; default 1.0.34, GROK_LLM_PROXY_CLIENT_VERSION overrides>",
+ "x-grok-client-identifier": "evenfire",
+ "x-grok-client-mode": "headless",
+ "x-xai-token-auth": "xai-grok-cli",
"cliImpersonation": false
},
"limits": {
diff --git a/tests/e2e/fixtures/package-lock.json b/tests/e2e/fixtures/package-lock.json
index bd211be57..294dde8e7 100644
--- a/tests/e2e/fixtures/package-lock.json
+++ b/tests/e2e/fixtures/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.80",
+ "version": "1.0.81",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.80",
+ "version": "1.0.81",
"dependencies": {
"@kubernetes/client-node": "^1.0.0"
},
diff --git a/tests/e2e/fixtures/package.json b/tests/e2e/fixtures/package.json
index bb4df1519..2e65862dc 100644
--- a/tests/e2e/fixtures/package.json
+++ b/tests/e2e/fixtures/package.json
@@ -1,6 +1,6 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.80",
+ "version": "1.0.81",
"description": "E2E test fixtures and utilities for Clerum testing",
"type": "module",
"main": "index.ts",