Skip to content

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

TypeScript

fix(grok): surface xAI's client-version refusal instead of a fake overload

Jose Gabriel Ramirez Encinas27b9c656bc9a
diff --git a/grok-llm-proxy/src/grokTransport.ts b/grok-llm-proxy/src/grokTransport.ts
index 51441d4d8..21bc70362 100644
--- a/grok-llm-proxy/src/grokTransport.ts
+++ b/grok-llm-proxy/src/grokTransport.ts
@@ -281,6 +281,15 @@ async function readUpstreamStream(input: {
'upstream rejected the Grok credential'
)
}
+ if (response.status === 426) {
+ // xAI's cli-chat-proxy enforces a minimum Grok CLI client version and
+ // answers 426 when the caller does not present an accepted one. Retrying
+ // cannot help: an operator has to ship a client identity xAI accepts.
+ throw new GrokTransportError(
+ 'client_upgrade_required',
+ 'xAI requires a newer Grok client version for subscription inference; contact support to upgrade Evenfire’s Grok client'
+ )
+ }
if (response.status === 402 || response.status === 403) {
throw new GrokTransportError(
'provider_unavailable',
diff --git a/grok-llm-proxy/src/server.ts b/grok-llm-proxy/src/server.ts
index 38f26d81a..20a9576f6 100644
--- a/grok-llm-proxy/src/server.ts
+++ b/grok-llm-proxy/src/server.ts
@@ -336,6 +336,7 @@ function mapError(err: unknown): { status: number; code: string } {
insufficient_scope: 403,
disabled: 404,
ticket_replayed: 409,
+ client_upgrade_required: 426,
connection_unavailable: 503,
provider_unavailable: 503,
}
diff --git a/grok-llm-proxy/test/grokTransport.conformance.test.ts b/grok-llm-proxy/test/grokTransport.conformance.test.ts
index d7b2892ed..b52673e2d 100644
--- a/grok-llm-proxy/test/grokTransport.conformance.test.ts
+++ b/grok-llm-proxy/test/grokTransport.conformance.test.ts
@@ -132,6 +132,51 @@ describe('streamGrokCompletion', () => {
])
})
+ // Live xAI (probed 2026-09-18) answers 426 with
+ // "Your Grok CLI version (none) is outdated..." when the caller presents no
+ // accepted client version. Retrying cannot fix it, so it must not look like
+ // a transient outage.
+ it('maps an upstream 426 to a non-retryable client_upgrade_required error', async () => {
+ const redeem = vi.fn(async () => redeemSuccess())
+ const finalize = vi.fn(async () => ({
+ providerAttemptId: 'att-426',
+ outcome: 'error' as const,
+ duplicate: false,
+ }))
+ const fetchFn = vi.fn(async (_url: FetchInput, _init?: RequestInit) => ({
+ ok: false,
+ status: 426,
+ body: null,
+ headers: new Headers(),
+ text: async () =>
+ '{"error":"Your Grok CLI version (none) is outdated. Please update to version 0.1.202 or later."}',
+ })) as unknown as typeof fetch
+ const pending = streamGrokCompletion({
+ executionTicket: 'ticket-426',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-426',
+ hostRef: 'research-host',
+ model: REQUEST.model,
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-426',
+ },
+ redeem,
+ finalize,
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ })
+ await expect(pending).rejects.toMatchObject({
+ code: 'client_upgrade_required',
+ message: expect.stringMatching(/newer Grok client version/i),
+ })
+ expect(redeem).toHaveBeenCalled()
+ expect(finalize).toHaveBeenCalledWith(
+ expect.objectContaining({ receipt: expect.objectContaining({ outcome: 'error' }) })
+ )
+ })
+
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 () => ({
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 7119d9077..3d480e944 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.344",
+ "version": "0.1.345",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.344",
+ "version": "0.1.345",
"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 f71804582..affdcfd6f 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.344",
+ "version": "0.1.345",
"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/__tests__/grokSubscription.test.ts b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
index de89510d2..45c1d1a03 100644
--- a/mcp-host/src/llm/__tests__/grokSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
@@ -309,6 +309,23 @@ describe('GrokSubscriptionProvider', () => {
).rejects.toMatchObject({ code: 'provider_unavailable' })
})
+ // xAI refuses subscription inference when the client version it sees is below
+ // its floor (live 426, probed 2026-09-18). An operator must act, so this is
+ // not an overload and must not be retried or failed over.
+ it('classifies a client upgrade requirement as non-retryable, not an overload', () => {
+ const provider = new GrokSubscriptionProvider('grok-4.6', deps() as never)
+ const classified = provider.classifyError(
+ new GrokProxyError('client_upgrade_required', 'xAI requires a newer Grok client version')
+ )
+ expect(classified).toMatchObject({
+ code: LlmErrorCode.ModelNotAvailable,
+ retryable: false,
+ providerCode: 'client_upgrade_required',
+ })
+ expect(classified.code).not.toBe(LlmErrorCode.ModelOverloaded)
+ expect(classifyFailoverClass(classified.code, classified.retryable)).toBeNull()
+ })
+
it('classifies authorize denials as non-retryable and never dispatched', () => {
const provider = new GrokSubscriptionProvider('grok-4.6', deps() as never)
const scope = provider.classifyError(new CodexAuthorizeError('insufficient_scope', 'scope'))
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
index 3455bf8b4..b3f75f40a 100644
--- a/mcp-host/src/llm/grokSubscription.ts
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -173,6 +173,17 @@ export class GrokSubscriptionProvider implements SingleTurnProvider {
...(providerDispatched !== undefined ? { providerDispatched } : {}),
}
}
+ if (code === 'client_upgrade_required') {
+ // Not retryable and not an outage: xAI refused the client identity, so a
+ // human has to act (upgrade the Grok client Evenfire presents).
+ return {
+ code: LlmErrorCode.ModelNotAvailable,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
if (code === 'provider_unavailable' || code === 'connection_unavailable') {
return {
code: LlmErrorCode.ModelOverloaded,