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.tsxindex 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.jsonindex 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.jsonindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): Promisconst 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 += 1json(res, 401, { error: 'unauthorized' })diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 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.jsonindex 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.tsindex 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.jsonindex 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.jsonindex 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.jsonindex 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",