Skip to content

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

TypeScript

feat(mcp-host): add Grok spend path and live policy binding

Jose Gabriel Ramirez Encinas2ffc73812251
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 47760cf25..d42966141 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.332",
+ "version": "0.1.333",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.332",
+ "version": "0.1.333",
"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 8946336ac..3ee5ab1aa 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.332",
+ "version": "0.1.333",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
@@ -28,6 +28,7 @@
"@anthropic-ai/sdk": "^0.32.0",
"@aws-sdk/client-bedrock-runtime": "^3.895.0",
"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",
+ "@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
"@clerum/llm-provider-attempt-contract": "file:../packages/llm-provider-attempt-contract",
"@clerum/llm-providers": "file:../packages/llm-providers",
"@google/genai": "^2.10.0",
diff --git a/mcp-host/src/config.devProvider.test.ts b/mcp-host/src/config.devProvider.test.ts
index 49023b20a..bee602e4d 100644
--- a/mcp-host/src/config.devProvider.test.ts
+++ b/mcp-host/src/config.devProvider.test.ts
@@ -32,5 +32,6 @@ describe('resolveDevModelProvider', () => {
new RegExp(`Valid providers: ${ALL_PROVIDERS.join(', ')}`)
)
expect(ALL_PROVIDERS).toContain('codex-subscription')
+ expect(ALL_PROVIDERS).toContain('grok-subscription')
})
})
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index c0d4a797a..0f16e4036 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -69,6 +69,10 @@ export interface Config {
codexSubscriptionEnabled: boolean
// Server-owned Codex proxy URL. Callers cannot override this per request.
codexProxyRuntimeBaseUrl: string
+ grokSubscriptionEnabled: boolean
+ grokProxyRuntimeBaseUrl: string
+ grokPolicyRevision: number
+ grokPolicyHash: string
// Explicit authorize override for tests/dev. Host chat ignores an empty hash
// and binds policyRevision/policyHash from the allowlist ConfigMap instead.
codexPolicyRevision: number
@@ -670,6 +674,13 @@ export const config: Config = {
// ConfigMap. Set both env vars together only as a test/dev override.
codexPolicyRevision: parseInt(getEnv('CODEX_POLICY_REVISION', '1')!, 10),
codexPolicyHash: getEnv('CODEX_POLICY_HASH', '')!,
+ grokSubscriptionEnabled: process.env.MCP_HOST_GROK_SUBSCRIPTION_ENABLED === 'true',
+ grokProxyRuntimeBaseUrl: getEnv(
+ 'GROK_LLM_PROXY_RUNTIME_URL',
+ 'http://grok-llm-proxy.control-plane.svc.cluster.local:8080'
+ )!,
+ grokPolicyRevision: parseInt(getEnv('GROK_POLICY_REVISION', '1')!, 10),
+ grokPolicyHash: getEnv('GROK_POLICY_HASH', '')!,
// Dev mode MCP servers
devMcpServers: devMode ? parseDevMcpServers() : undefined,
diff --git a/mcp-host/src/config/configStore.test.ts b/mcp-host/src/config/configStore.test.ts
index 2d5dd7720..b5b7babc5 100644
--- a/mcp-host/src/config/configStore.test.ts
+++ b/mcp-host/src/config/configStore.test.ts
@@ -106,7 +106,14 @@ function makeFakeCoreApi(initial: {
function build(opts: {
llmSecretRef?: string | null
- provider?: 'openai' | 'claude' | 'zai' | 'bailian' | 'codex-subscription' | null
+ provider?:
+ | 'openai'
+ | 'claude'
+ | 'zai'
+ | 'bailian'
+ | 'codex-subscription'
+ | 'grok-subscription'
+ | null
connectionRef?: string | null
secrets?: Record<string, Record<string, string>>
configMaps?: Record<string, Record<string, string>>
@@ -829,6 +836,51 @@ describe('ConfigStore — allowlist tier (R3)', () => {
expect(store.codexPolicyBinding()?.models).toEqual(['gpt-5.1'])
})
+ it('exposes Grok catalog/credential revisions from grok-connections only', async () => {
+ const built = build({
+ provider: 'grok-subscription',
+ connectionRef: 'team-grok',
+ secrets: { 'chatllm-api-keys': { 'openai-api-key': 'sk' } },
+ allowlistConfigMapName: ALLOWLIST_CM,
+ configMaps: {
+ [ALLOWLIST_CM]: {
+ 'grok-subscription': JSON.stringify([{ model: 'grok-4.6' }, { model: 'grok-4.5' }]),
+ 'codex-subscription': JSON.stringify([{ model: 'gpt-5.1' }]),
+ },
+ },
+ configMapAnnotations: {
+ [ALLOWLIST_CM]: {
+ 'clerum.io/catalog-revision': '99',
+ 'clerum.io/connection-revision': '88',
+ 'clerum.io/codex-connections': JSON.stringify({
+ 'team-grok': {
+ catalogRevision: 99,
+ connectionRevision: 88,
+ models: ['gpt-5.1'],
+ },
+ }),
+ 'clerum.io/grok-connections': JSON.stringify({
+ 'team-grok': {
+ catalogRevision: 5,
+ connectionRevision: 2,
+ models: ['grok-4.6'],
+ },
+ }),
+ },
+ },
+ })
+ store = built.store
+ await store.start()
+ expect(store.grokPolicyBinding()).toEqual({
+ catalogRevision: 5,
+ credentialRevision: 2,
+ connectionKey: 'team-grok',
+ models: ['grok-4.6'],
+ })
+ expect(store.allowedModels().get('grok-subscription')).toEqual([{ model: 'grok-4.6' }])
+ expect(store.codexPolicyBinding()?.catalogRevision).toBe(99)
+ })
+
it('does not inherit another grant when the assigned connection is missing from the map', async () => {
const built = build({
provider: 'codex-subscription',
diff --git a/mcp-host/src/config/configStore.ts b/mcp-host/src/config/configStore.ts
index f19a8dde8..1f2a518c9 100644
--- a/mcp-host/src/config/configStore.ts
+++ b/mcp-host/src/config/configStore.ts
@@ -35,6 +35,7 @@ import {
CODEX_CONNECTIONS_ANNOTATION,
CONNECTION_REVISION_ANNOTATION,
type CodexPolicyBinding,
+ toGrokPolicyBinding,
toPolicyBinding,
} from '@clerum/codex-catalog-projection'
import { assignedConnectionRef } from '../llm/hostLlmBinding'
@@ -65,7 +66,7 @@ export const PROVIDER_ENV_NAME = Object.fromEntries(
p,
primarySlot(descriptorFor(p)).envName,
])
-) as Record<Exclude<LlmProvider, 'codex-subscription'>, string>
+) as Record<Exclude<LlmProvider, 'codex-subscription' | 'grok-subscription'>, string>
/**
* Every provider credential env var name across ALL providers and ALL their
@@ -249,6 +250,8 @@ export class ConfigStore {
private allowlistMissingWarned = false
/** Catalog/credential pair from allowlist CM annotations, or null. */
private codexBinding: CodexPolicyBinding | null = null
+ /** Grok catalog/credential pair from grok-connections, or null. */
+ private grokBinding: CodexPolicyBinding | null = null
constructor(opts: ConfigStoreOptions) {
this.opts = opts
@@ -490,6 +493,15 @@ export class ConfigStore {
return this.codexBinding
}
+ /**
+ * Live Grok catalog/credential revisions from `clerum.io/grok-connections`.
+ * Null when the CM is absent, the Grok map is missing, or the assigned key
+ * is unassigned. Never reads Codex annotations.
+ */
+ grokPolicyBinding(): CodexPolicyBinding | null {
+ return this.grokBinding
+ }
+
// ─── Bootstrap (initial list) ────────────────────────────────────────
private async bootstrapLlmSecret(): Promise<void> {
@@ -559,10 +571,15 @@ export class ConfigStore {
data?: Record<string, string>
metadata?: { annotations?: Record<string, string> }
}): boolean {
- const nextBinding = toPolicyBinding(cm, assignedConnectionRef(this.opts.connectionRef))
- const modelsChanged = this.applyAllowlistData(cm.data ?? {}, nextBinding)
- const bindingChanged = !codexBindingsEqual(this.codexBinding, nextBinding)
+ const assigned = assignedConnectionRef(this.opts.connectionRef)
+ const nextBinding = toPolicyBinding(cm, assigned)
+ const nextGrokBinding = toGrokPolicyBinding(cm, assigned)
+ const modelsChanged = this.applyAllowlistData(cm.data ?? {}, nextBinding, nextGrokBinding)
+ const bindingChanged =
+ !codexBindingsEqual(this.codexBinding, nextBinding) ||
+ !codexBindingsEqual(this.grokBinding, nextGrokBinding)
this.codexBinding = nextBinding
+ this.grokBinding = nextGrokBinding
return modelsChanged || bindingChanged
}
@@ -578,7 +595,8 @@ export class ConfigStore {
*/
private applyAllowlistData(
data: Record<string, string>,
- binding: CodexPolicyBinding | null = null
+ binding: CodexPolicyBinding | null = null,
+ grokBinding: CodexPolicyBinding | null = null
): boolean {
const next = new Map<string, AllowedModelEntry[]>()
for (const [provider, raw] of Object.entries(data)) {
@@ -637,6 +655,14 @@ export class ConfigStore {
// models[]. Keep the flat catalog. A map entry that omits models[]
// is parsed as [] and fail-closes here.
}
+ if (provider === 'grok-subscription') {
+ if (!grokBinding) {
+ entries = []
+ } else if (Array.isArray(grokBinding.models)) {
+ const allowed = new Set(grokBinding.models)
+ entries = entries.filter(entry => allowed.has(entry.model))
+ }
+ }
next.set(provider, entries)
}
const changed = !allowlistMapsEqual(this.allowedModelsMap, next)
@@ -655,6 +681,7 @@ export class ConfigStore {
this.allowlistDelivered = false
this.allowedModelsMap = new Map()
this.codexBinding = null
+ this.grokBinding = null
if (!this.allowlistMissingWarned) {
this.allowlistMissingWarned = true
llmAllowlistMissingTotal.inc()
diff --git a/mcp-host/src/llm/__tests__/grokLlmProxyClient.test.ts b/mcp-host/src/llm/__tests__/grokLlmProxyClient.test.ts
new file mode 100644
index 000000000..f404e81e1
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/grokLlmProxyClient.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest'
+import { GrokLlmProxyClient, resolveGrokProxyRuntimeUrl } from '../grokLlmProxyClient'
+
+function sse(frames: unknown[]): ReadableStream<Uint8Array> {
+ const encoder = new TextEncoder()
+ const payload = frames.map(frame => `data: ${JSON.stringify(frame)}\n\n`).join('')
+ return new ReadableStream({
+ start(controller) {
+ controller.enqueue(encoder.encode(payload))
+ controller.close()
+ },
+ })
+}
+
+describe('GrokLlmProxyClient', () => {
+ it('streams to the frozen Grok runtime path and never accepts a caller URL', async () => {
+ const fetchFn = vi.fn().mockResolvedValue({
+ ok: true,
+ body: sse([
+ { type: 'text', text: 'hello' },
+ { type: 'done', outcome: 'success' },
+ ]),
+ })
+ const client = new GrokLlmProxyClient({
+ runtimeUrl: resolveGrokProxyRuntimeUrl(
+ 'http://grok-llm-proxy.control-plane.svc.cluster.local:8080'
+ ),
+ readPlatformJwt: () => 'platform-jwt',
+ fetchFn: fetchFn as unknown as typeof fetch,
+ })
+ const result = await client.stream({
+ executionTicket: 'ticket-123456',
+ requestHash: 'a'.repeat(64),
+ request: { model: 'grok-4.6' },
+ })
+ expect(fetchFn.mock.calls[0][0]).toBe(
+ 'http://grok-llm-proxy.control-plane.svc.cluster.local:8080/internal/runtime/v1/grok/completions'
+ )
+ expect(result.text).toBe('hello')
+ })
+})
diff --git a/mcp-host/src/llm/__tests__/grokPolicyBinding.test.ts b/mcp-host/src/llm/__tests__/grokPolicyBinding.test.ts
new file mode 100644
index 000000000..0fe62a3b2
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/grokPolicyBinding.test.ts
@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
+import {
+ readLiveGrokPolicyBinding,
+ resolveGrokAttemptPolicy,
+ setGrokPolicyBindingReader,
+} from '../grokPolicyBinding'
+
+describe('resolveGrokAttemptPolicy', () => {
+ afterEach(() => {
+ setGrokPolicyBindingReader(() => null)
+ })
+
+ it('uses a well-formed env override without consulting the live binding', () => {
+ const envHash = 'c'.repeat(64)
+ expect(
+ resolveGrokAttemptPolicy({
+ model: 'grok-4.6',
+ envRevision: 1,
+ envHash,
+ binding: { catalogRevision: 7, credentialRevision: 3, connectionKey: 'team-grok' },
+ })
+ ).toEqual({ policyRevision: 1, policyHash: envHash })
+ })
+
+ it('computes the per-model hash from the Grok catalog/credential pair', () => {
+ const binding = { catalogRevision: 7, credentialRevision: 3, connectionKey: 'team-grok' }
+ const resolved = resolveGrokAttemptPolicy({
+ model: 'grok-4.6',
+ envRevision: 1,
+ envHash: '',
+ binding,
+ })
+ expect(resolved).toEqual({
+ policyRevision: 7,
+ policyHash: computeGrokPolicyHash({
+ model: 'grok-4.6',
+ catalogRevision: 7,
+ credentialRevision: 3,
+ connectionKey: 'team-grok',
+ }),
+ })
+ })
+
+ it('returns null when the catalog revision is missing or not yet synced', () => {
+ expect(
+ resolveGrokAttemptPolicy({
+ model: 'grok-4.6',
+ envRevision: 1,
+ envHash: '',
+ binding: null,
+ })
+ ).toBeNull()
+ })
+
+ it('exposes the registered live reader to Host chat construction', () => {
+ setGrokPolicyBindingReader(() => ({
+ catalogRevision: 7,
+ credentialRevision: 3,
+ connectionKey: 'team-grok',
+ }))
+ expect(readLiveGrokPolicyBinding()).toEqual({
+ catalogRevision: 7,
+ credentialRevision: 3,
+ connectionKey: 'team-grok',
+ })
+ })
+})
diff --git a/mcp-host/src/llm/__tests__/grokSubscription.test.ts b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
new file mode 100644
index 000000000..d5450fc98
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest'
+import { GrokProxyError } from '../grokLlmProxyClient'
+import { GrokSubscriptionProvider } from '../grokSubscription'
+
+const requestHash = 'a'.repeat(64)
+
+function deps(overrides?: { stream?: ReturnType<typeof vi.fn> }) {
+ const authorize = vi.fn().mockResolvedValue({
+ providerAttemptId: 'attempt-1',
+ requestHash,
+ executionTicket: 'ticket-123456',
+ expiresAt: '2026-08-20T10:00:00.000Z',
+ })
+ const stream =
+ overrides?.stream ??
+ vi.fn().mockResolvedValue({
+ text: 'hello from grok proxy',
+ toolCalls: [],
+ outcome: 'success',
+ })
+ return {
+ authorizer: { authorize },
+ proxy: { stream },
+ attemptContext: vi.fn(() => ({
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ hostRef: 'chatllm',
+ })),
+ }
+}
+
+describe('GrokSubscriptionProvider', () => {
+ it.each(['unknown', 'canceled', 'error'])(
+ 'never returns executable calls from a %s batch',
+ async outcome => {
+ const wired = deps({
+ stream: vi.fn().mockResolvedValue({
+ text: 'partial',
+ outcome,
+ toolCalls: [{ id: 'partial', name: 'echo', arguments: {} }],
+ }),
+ })
+ const provider = new GrokSubscriptionProvider('grok-4.6', wired as never)
+ await expect(
+ provider.completeSingleTurnWithTools(
+ [{ role: 'user', content: 'hi' }],
+ [{ name: 'echo', description: 'echo', parameters: {} }]
+ )
+ ).rejects.toThrow(/successful terminal outcome/)
+ }
+ )
+
+ it('rejects an oversized successful proxy batch before returning any executable tools', async () => {
+ const wired = deps({
+ stream: vi.fn().mockResolvedValue({
+ text: '',
+ outcome: 'success',
+ toolCalls: Array.from({ length: 65 }, (_, index) => ({
+ id: `call-${index}`,
+ name: 'echo',
+ arguments: {},
+ })),
+ }),
+ })
+ const provider = new GrokSubscriptionProvider('grok-4.6', wired as never)
+ await expect(
+ provider.completeSingleTurnWithTools(
+ [{ role: 'user', content: 'hi' }],
+ [{ name: 'echo', description: 'echo', parameters: {} }]
+ )
+ ).rejects.toBeInstanceOf(GrokProxyError)
+ })
+})
diff --git a/mcp-host/src/llm/__tests__/makeProvider.throws.test.ts b/mcp-host/src/llm/__tests__/makeProvider.throws.test.ts
index 85ce29296..c0373c6a6 100644
--- a/mcp-host/src/llm/__tests__/makeProvider.throws.test.ts
+++ b/mcp-host/src/llm/__tests__/makeProvider.throws.test.ts
@@ -37,6 +37,21 @@ describe('makeProvider — divergent provider without a factory', () => {
})
})
+describe('makeProvider — Grok broker', () => {
+ it('fails closed when the execution flag is off', () => {
+ delete process.env.MCP_HOST_GROK_SUBSCRIPTION_ENABLED
+ expect(() => makeProvider('grok-subscription', {})).toThrow(/is disabled/)
+ })
+
+ it('fails closed without runtime authorizer/proxy dependencies when the flag is on', () => {
+ process.env.MCP_HOST_GROK_SUBSCRIPTION_ENABLED = 'true'
+ expect(() => makeProvider('grok-subscription', {})).toThrow(
+ /requires an explicit model and runtime authorizer/
+ )
+ delete process.env.MCP_HOST_GROK_SUBSCRIPTION_ENABLED
+ })
+})
+
describe('makeProvider — Codex broker', () => {
it('fails closed when the execution flag is off', () => {
delete process.env.MCP_HOST_CODEX_SUBSCRIPTION_ENABLED
diff --git a/mcp-host/src/llm/__tests__/registry.test.ts b/mcp-host/src/llm/__tests__/registry.test.ts
index fbeb869ae..2be3ad7b6 100644
--- a/mcp-host/src/llm/__tests__/registry.test.ts
+++ b/mcp-host/src/llm/__tests__/registry.test.ts
@@ -28,12 +28,13 @@ describe('provider registry — auto-detection order (§5.9)', () => {
])
})
- it('registers all 22 static providers plus the Codex broker', () => {
+ it('registers all 22 static providers plus the Codex and Grok brokers', () => {
expect(
ALL_PROVIDERS.filter(p => descriptorFor(p).authMode === 'static-credentials')
).toHaveLength(22)
expect(ALL_PROVIDERS).toContain('codex-subscription')
- expect(ALL_PROVIDERS).toHaveLength(23)
+ expect(ALL_PROVIDERS).toContain('grok-subscription')
+ expect(ALL_PROVIDERS).toHaveLength(24)
for (const p of [
'openrouter',
'gemini',
diff --git a/mcp-host/src/llm/grokLlmProxyClient.ts b/mcp-host/src/llm/grokLlmProxyClient.ts
new file mode 100644
index 000000000..c48f67181
--- /dev/null
+++ b/mcp-host/src/llm/grokLlmProxyClient.ts
@@ -0,0 +1,143 @@
+export const GROK_PROXY_COMPLETIONS_PATH = '/internal/runtime/v1/grok/completions'
+
+export class GrokProxyError extends Error {
+ /**
+ * `dispatched` records whether a request had already left this process when
+ * the error was raised. It defaults to `true` because every construction
+ * site except the pre-stream abort happens after the fetch was issued, and
+ * the safe default is the one that keeps the attempt fenced.
+ */
+ constructor(
+ readonly code: string,
+ message: string,
+ readonly dispatched: boolean = true
+ ) {
+ super(message)
+ this.name = 'GrokProxyError'
+ }
+}
+
+export type GrokProxyFrame =
+ | { type: 'text'; text: string }
+ | { type: 'tool_call'; id: string; name: string; arguments: Record<string, unknown> }
+ | {
+ type: 'done'
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+ usage?: { inputTokens: number; outputTokens: number }
+ }
+ | { type: 'error'; code: string }
+
+export type GrokProxyStreamResult = {
+ text: string
+ toolCalls: Array<{ id: string; name: string; arguments: Record<string, unknown> }>
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+ /** Present only when the proxy forwarded real upstream token counts. */
+ usage?: { inputTokens: number; outputTokens: number }
+}
+
+export type GrokLlmProxyClientOptions = {
+ runtimeUrl: string
+ readPlatformJwt: () => string
+ refreshOnUnauthorized?: () => Promise<void>
+ fetchFn?: typeof fetch
+}
+
+export class GrokLlmProxyClient {
+ constructor(private readonly options: GrokLlmProxyClientOptions) {
+ if (!options.runtimeUrl.startsWith('http://') && !options.runtimeUrl.startsWith('https://')) {
+ throw new Error('[GrokProxy] runtime URL must be an absolute server-owned URL')
+ }
+ }
+
+ async stream(input: {
+ executionTicket: string
+ requestHash: string
+ request: unknown
+ deadlineMs?: number
+ signal?: AbortSignal
+ }): Promise<GrokProxyStreamResult> {
+ if (input.signal?.aborted) {
+ throw new GrokProxyError('canceled', 'aborted before proxy stream', false)
+ }
+ return this.streamOnce(input, Boolean(this.options.refreshOnUnauthorized))
+ }
+
+ private async streamOnce(
+ input: {
+ executionTicket: string
+ requestHash: string
+ request: unknown
+ deadlineMs?: number
+ signal?: AbortSignal
+ },
+ retryOnUnauthorized: boolean
+ ): Promise<GrokProxyStreamResult> {
+ const jwt = this.options.readPlatformJwt()
+ const fetchFn = this.options.fetchFn ?? fetch
+ const response = await fetchFn(this.options.runtimeUrl, {
+ method: 'POST',
+ headers: {
+ authorization: `Bearer ${jwt}`,
+ 'content-type': 'application/json',
+ },
+ body: JSON.stringify({
+ executionTicket: input.executionTicket,
+ requestHash: input.requestHash,
+ request: input.request,
+ ...(input.deadlineMs !== undefined ? { deadlineMs: input.deadlineMs } : {}),
+ }),
+ signal: input.signal,
+ })
+ if (!response.ok) {
+ if (response.status === 401 && retryOnUnauthorized && this.options.refreshOnUnauthorized) {
+ await this.options.refreshOnUnauthorized()
+ return this.streamOnce(input, false)
+ }
+ const payload = (await response.json().catch(() => ({}))) as Record<string, unknown>
+ const code = typeof payload.error === 'string' ? payload.error : 'provider_unavailable'
+ throw new GrokProxyError(code, `proxy stream failed with ${response.status} (${code})`)
+ }
+ if (!response.body) {
+ throw new GrokProxyError('provider_unavailable', 'proxy stream had no body')
+ }
+ return readProxySse(response.body)
+ }
+}
+
+export function resolveGrokProxyRuntimeUrl(base: string): string {
+ const trimmed = base.replace(/\/+$/, '')
+ if (trimmed.endsWith(GROK_PROXY_COMPLETIONS_PATH)) return trimmed
+ return `${trimmed}${GROK_PROXY_COMPLETIONS_PATH}`
+}
+
+async function readProxySse(body: ReadableStream<Uint8Array>): Promise<GrokProxyStreamResult> {
+ const reader = body.getReader()
+ const decoder = new TextDecoder()
+ let buffer = ''
+ let text = ''
+ const toolCalls: GrokProxyStreamResult['toolCalls'] = []
+ let outcome: GrokProxyStreamResult['outcome'] = 'unknown'
+ let usage: GrokProxyStreamResult['usage']
+ while (true) {
+ const { done, value } = await reader.read()
+ if (done) break
+ buffer += decoder.decode(value, { stream: true })
+ const parts = buffer.split('\n\n')
+ buffer = parts.pop() ?? ''
+ for (const part of parts) {
+ const line = part.split('\n').find(entry => entry.startsWith('data: '))
+ if (!line) continue
+ const frame = JSON.parse(line.slice(6)) as GrokProxyFrame
+ if (frame.type === 'error') {
+ throw new GrokProxyError(frame.code, `proxy stream failed with ${frame.code}`)
+ }
+ if (frame.type === 'text') text += frame.text
+ if (frame.type === 'tool_call') toolCalls.push(frame)
+ if (frame.type === 'done') {
+ outcome = frame.outcome
+ if (frame.usage) usage = frame.usage
+ }
+ }
+ }
+ return { text, toolCalls, outcome, ...(usage ? { usage } : {}) }
+}
diff --git a/mcp-host/src/llm/grokPolicyBinding.ts b/mcp-host/src/llm/grokPolicyBinding.ts
new file mode 100644
index 000000000..864219548
--- /dev/null
+++ b/mcp-host/src/llm/grokPolicyBinding.ts
@@ -0,0 +1,59 @@
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
+
+const POLICY_HASH_RE = /^[a-f0-9]{64}$/
+
+export type GrokPolicyBinding = {
+ catalogRevision: number
+ credentialRevision: number
+ connectionKey: string
+}
+
+export type GrokAttemptPolicy = {
+ policyRevision: number
+ policyHash: string
+}
+
+let reader: () => GrokPolicyBinding | null = () => null
+
+export function setGrokPolicyBindingReader(fn: () => GrokPolicyBinding | null): void {
+ reader = fn
+}
+
+export function readLiveGrokPolicyBinding(): GrokPolicyBinding | null {
+ return reader()
+}
+
+export function resolveGrokAttemptPolicy(input: {
+ model: string
+ envRevision: number
+ envHash: string
+ binding: GrokPolicyBinding | null
+}): GrokAttemptPolicy | null {
+ const envHash = input.envHash.trim()
+ if (
+ POLICY_HASH_RE.test(envHash) &&
+ Number.isInteger(input.envRevision) &&
+ input.envRevision >= 1
+ ) {
+ return { policyRevision: input.envRevision, policyHash: envHash }
+ }
+ const binding = input.binding
+ if (
+ !binding ||
+ !Number.isInteger(binding.catalogRevision) ||
+ binding.catalogRevision < 1 ||
+ !Number.isInteger(binding.credentialRevision) ||
+ binding.credentialRevision < 1
+ ) {
+ return null
+ }
+ return {
+ policyRevision: binding.catalogRevision,
+ policyHash: computeGrokPolicyHash({
+ model: input.model,
+ catalogRevision: binding.catalogRevision,
+ credentialRevision: binding.credentialRevision,
+ connectionKey: binding.connectionKey,
+ }),
+ }
+}
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
new file mode 100644
index 000000000..d40d30165
--- /dev/null
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -0,0 +1,357 @@
+import { randomUUID } from 'node:crypto'
+import {
+ type GrokCompletionRequestV1,
+ LIMITS,
+ hashGrokCompletionRequestV1,
+} from '@clerum/grok-provider-attempt-contract'
+import { LlmErrorCode } from '../core/errors'
+import {
+ CompletionResponse,
+ ChatMessage as CoreChatMessage,
+ FinishReason,
+ ToolCompletionResponse,
+ ToolDefinition,
+} from '../core/types'
+import { logger } from '../logger'
+import { classifyUnknown } from './errorClassification'
+import { GrokLlmProxyClient, GrokProxyError } from './grokLlmProxyClient'
+import { CodexAuthorizeError, ProviderAttemptAuthorizer } from './providerAttemptAuthorizer'
+import type { LlmProvider } from './registryCore'
+import type { ClassifiedError, SingleTurnProvider } from './types'
+
+export type GrokAttemptContext = {
+ invocationId?: string
+ attemptGeneration?: number
+ providerAttemptIndex?: number
+ pluginWorkloadSdkProviderAttemptId?: string
+ targetRef?: string
+ policyRevision: number
+ policyHash: string
+ hostRef?: string
+ recipeNamespace?: string
+ recipeName?: string
+ userId?: string
+}
+
+function mapGrokUsage(usage?: { inputTokens: number; outputTokens: number }): {
+ usage: { input_tokens: number; output_tokens: number; total_tokens: number }
+ usage_reported: boolean
+} {
+ const inputTokens = usage?.inputTokens
+ const outputTokens = usage?.outputTokens
+ const usageKnown =
+ typeof inputTokens === 'number' &&
+ typeof outputTokens === 'number' &&
+ Number.isInteger(inputTokens) &&
+ Number.isInteger(outputTokens) &&
+ inputTokens >= 0 &&
+ outputTokens >= 0
+ return {
+ usage: {
+ input_tokens: usageKnown ? inputTokens : 0,
+ output_tokens: usageKnown ? outputTokens : 0,
+ total_tokens: usageKnown ? inputTokens + outputTokens : 0,
+ },
+ usage_reported: usageKnown,
+ }
+}
+
+export type GrokSubscriptionDeps = {
+ authorizer: ProviderAttemptAuthorizer
+ proxy: GrokLlmProxyClient
+ attemptContext: (input: { model: string }) => GrokAttemptContext
+}
+
+function assertTerminalGrokOutcome(result: {
+ text: string
+ toolCalls: Array<{ id: string; name: string; arguments: Record<string, unknown> }>
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+}): void {
+ if (result.toolCalls.length > LIMITS.maxToolCalls) {
+ throw new GrokProxyError('provider_unavailable', `tool calls exceed ${LIMITS.maxToolCalls}`)
+ }
+ if (result.toolCalls.length > 0 && result.outcome !== 'success') {
+ throw new GrokProxyError(
+ 'provider_unavailable',
+ 'tool calls require a successful terminal outcome'
+ )
+ }
+ if (result.outcome === 'error') {
+ throw new GrokProxyError('provider_unavailable', 'proxy stream ended with an error outcome')
+ }
+ if (result.outcome === 'unknown' && !result.text && result.toolCalls.length === 0) {
+ throw new GrokProxyError(
+ 'provider_unavailable',
+ 'proxy stream ended without a terminal outcome'
+ )
+ }
+}
+
+export class GrokSubscriptionProvider implements SingleTurnProvider {
+ private nextProviderAttemptIndex = 1
+
+ constructor(
+ private readonly model: string,
+ private readonly deps: GrokSubscriptionDeps
+ ) {
+ if (!model.trim()) {
+ throw new Error('[LLM] makeProvider: grok-subscription requires an explicit model')
+ }
+ }
+
+ getProviderType(): LlmProvider {
+ return 'grok-subscription'
+ }
+
+ classifyError(err: unknown): ClassifiedError {
+ const code =
+ err instanceof CodexAuthorizeError || err instanceof GrokProxyError ? err.code : undefined
+ // Every CodexAuthorizeError throw site precedes `proxy.stream`, so an
+ // authorize failure proves nothing was dispatched. A GrokProxyError knows
+ // whether its own request had left the process. Anything else stays
+ // undefined — an unrecognized error is not evidence of a missing call.
+ const providerDispatched =
+ err instanceof CodexAuthorizeError
+ ? false
+ : err instanceof GrokProxyError
+ ? err.dispatched
+ : undefined
+ if (
+ code === 'insufficient_scope' ||
+ code === 'no_grant' ||
+ code === 'host_binding_mismatch' ||
+ code === 'origin_denied'
+ ) {
+ return {
+ code: LlmErrorCode.AuthenticationFailed,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
+ if (code === 'budget_denied') {
+ return {
+ code: LlmErrorCode.InsufficientQuota,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
+ if (code === 'model_not_allowed') {
+ return {
+ code: LlmErrorCode.ModelNotAvailable,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
+ if (code === 'rate_limited') {
+ return {
+ code: LlmErrorCode.RateLimited,
+ retryable: true,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
+ if (code === 'provider_unavailable' || code === 'connection_unavailable') {
+ return {
+ code: LlmErrorCode.ModelOverloaded,
+ retryable: true,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
+ if (code) {
+ return {
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ ...(providerDispatched !== undefined ? { providerDispatched } : {}),
+ }
+ }
+ return classifyUnknown(err)
+ }
+
+ async completeSingleTurn(
+ messages: CoreChatMessage[],
+ options?: { max_tokens?: number; temperature?: number; signal?: AbortSignal }
+ ): Promise<CompletionResponse> {
+ const result = await this.execute(messages, undefined, options)
+ assertTerminalGrokOutcome(result)
+ const usage = mapGrokUsage(result.usage)
+ return {
+ content: result.text,
+ usage: usage.usage,
+ usage_reported: usage.usage_reported,
+ finish_reason:
+ result.outcome === 'canceled' || result.outcome === 'unknown'
+ ? FinishReason.Unknown
+ : FinishReason.Stop,
+ providerAttemptId: result.providerAttemptId,
+ providerAttemptIndex: result.providerAttemptIndex,
+ }
+ }
+
+ async completeSingleTurnWithTools(
+ messages: CoreChatMessage[],
+ tools: ToolDefinition[],
+ options?: {
+ max_tokens?: number
+ temperature?: number
+ tool_choice?: string
+ signal?: AbortSignal
+ }
+ ): Promise<ToolCompletionResponse> {
+ const result = await this.execute(messages, tools, options)
+ assertTerminalGrokOutcome(result)
+ const usage = mapGrokUsage(result.usage)
+ return {
+ content: result.text || null,
+ tool_calls:
+ result.toolCalls.length > 0
+ ? result.toolCalls.map(call => ({
+ id: call.id,
+ name: call.name,
+ arguments: call.arguments,
+ }))
+ : null,
+ usage: usage.usage,
+ usage_reported: usage.usage_reported,
+ finish_reason:
+ result.toolCalls.length > 0
+ ? FinishReason.ToolUse
+ : result.outcome === 'canceled' || result.outcome === 'unknown'
+ ? FinishReason.Unknown
+ : FinishReason.Stop,
+ }
+ }
+
+ private async execute(
+ messages: CoreChatMessage[],
+ tools: ToolDefinition[] | undefined,
+ options?: {
+ max_tokens?: number
+ temperature?: number
+ tool_choice?: string
+ signal?: AbortSignal
+ }
+ ) {
+ if (options?.signal?.aborted) {
+ throw new GrokProxyError('canceled', 'aborted before authorize', false)
+ }
+ const request = this.buildRequest(messages, tools, options)
+ const requestHash = hashGrokCompletionRequestV1(request)
+ const context = this.deps.attemptContext({ model: this.model })
+ if (
+ !Number.isInteger(context.policyRevision) ||
+ context.policyRevision < 1 ||
+ !/^[a-f0-9]{64}$/.test(context.policyHash)
+ ) {
+ throw new CodexAuthorizeError('no_grant', 'Codex catalog policy binding is missing')
+ }
+ const providerAttemptIndex = context.providerAttemptIndex ?? this.nextProviderAttemptIndex++
+ const authorized = await this.deps.authorizer.authorize(
+ {
+ request,
+ requestHash,
+ invocationId: context.invocationId ?? request.requestId,
+ attemptGeneration: context.attemptGeneration ?? 1,
+ providerAttemptIndex,
+ policyRevision: context.policyRevision,
+ policyHash: context.policyHash,
+ hostRef: context.hostRef,
+ recipeNamespace: context.recipeNamespace,
+ recipeName: context.recipeName,
+ userId: context.userId,
+ ...(context.pluginWorkloadSdkProviderAttemptId
+ ? { pluginWorkloadSdkProviderAttemptId: context.pluginWorkloadSdkProviderAttemptId }
+ : {}),
+ ...(context.targetRef ? { targetRef: context.targetRef } : {}),
+ },
+ // Authorize shares the caller's deadline. Without this the attempt could
+ // keep a cancelled request alive on the control-api hop while the bridge
+ // has already given up on it.
+ { ...(options?.signal ? { signal: options.signal } : {}) }
+ )
+ if (!('accessToken' in authorized)) {
+ // Bound: authorize returns ticket material only.
+ }
+ const streamed = await this.deps.proxy.stream({
+ executionTicket: authorized.executionTicket,
+ requestHash: authorized.requestHash,
+ request,
+ signal: options?.signal,
+ })
+ return {
+ ...streamed,
+ providerAttemptId: authorized.providerAttemptId,
+ providerAttemptIndex,
+ }
+ }
+
+ private buildRequest(
+ messages: CoreChatMessage[],
+ tools: ToolDefinition[] | undefined,
+ options?: { max_tokens?: number; temperature?: number; tool_choice?: string }
+ ): GrokCompletionRequestV1 {
+ const request: GrokCompletionRequestV1 = {
+ schemaVersion: 'grok-completion-request.v1',
+ requestId: randomUUID(),
+ idempotencyKey: randomUUID(),
+ provider: 'grok-subscription',
+ model: this.model,
+ messages: messages.map(message => ({
+ role: message.role,
+ content: message.content ?? '',
+ ...(message.name ? { name: message.name } : {}),
+ ...(message.tool_call_id ? { toolCallId: message.tool_call_id } : {}),
+ ...(message.role === 'assistant' && message.tool_calls && message.tool_calls.length > 0
+ ? {
+ toolCalls: message.tool_calls.map(call => ({
+ id: call.id,
+ name: call.name,
+ arguments: call.arguments,
+ })),
+ }
+ : {}),
+ })),
+ }
+ if (tools && tools.length > 0) {
+ // Presentation is owned by the agent loop. Preserve its final definitions
+ // in both the authorized hash and the proxy request; MCP names are not
+ // permissions and must never be discarded by the provider adapter.
+ logger.debug(
+ { provider: 'grok-subscription', presentedCount: tools.length },
+ 'Tool definitions prepared for authorization'
+ )
+ request.tools = tools.map(tool => ({
+ name: tool.name,
+ description: tool.description,
+ parameters: tool.parameters,
+ }))
+ }
+
+ if (
+ options?.temperature !== undefined ||
+ options?.max_tokens !== undefined ||
+ options?.tool_choice
+ ) {
+ request.generation = {
+ ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+ ...(options.max_tokens !== undefined ? { maxOutputTokens: options.max_tokens } : {}),
+ ...(options.tool_choice === 'auto' ||
+ options.tool_choice === 'none' ||
+ options.tool_choice === 'required'
+ ? { toolChoice: options.tool_choice }
+ : {}),
+ }
+ }
+ return request
+ }
+}
diff --git a/mcp-host/src/llm/index.ts b/mcp-host/src/llm/index.ts
index 668bf24fc..44cdba89c 100644
--- a/mcp-host/src/llm/index.ts
+++ b/mcp-host/src/llm/index.ts
@@ -8,6 +8,9 @@ import { CodexLlmProxyClient, resolveCodexProxyRuntimeUrl } from './codexLlmProx
import { readCodexPlatformJwt, refreshCodexPlatformJwt } from './codexPlatformJwt'
import { readLiveCodexPolicyBinding, resolveCodexAttemptPolicy } from './codexPolicyBinding'
import type { CodexAttemptContext } from './codexSubscription'
+import { GrokLlmProxyClient, resolveGrokProxyRuntimeUrl } from './grokLlmProxyClient'
+import { readLiveGrokPolicyBinding, resolveGrokAttemptPolicy } from './grokPolicyBinding'
+import type { GrokAttemptContext } from './grokSubscription'
import { OpenAIProvider } from './openai'
import { ProviderAttemptAuthorizer, resolveCodexAuthorizeUrl } from './providerAttemptAuthorizer'
import { makeProvider } from './registry'
@@ -22,6 +25,38 @@ export type { ClassifiedError, SingleTurnProvider } from './types'
const DEFAULT_CODEX_AUTHORIZE_GATEWAY =
'http://nginx-workflow-approval-gateway.control-plane.svc.cluster.local:8092'
+function createGrokRuntimeDeps(captured?: GrokAttemptContext) {
+ const gateway = (config.mcpHostGatewayUrl ?? '').trim() || DEFAULT_CODEX_AUTHORIZE_GATEWAY
+ return {
+ authorizer: new ProviderAttemptAuthorizer({
+ authorizeUrl: resolveCodexAuthorizeUrl(gateway),
+ readPlatformJwt: readCodexPlatformJwt,
+ refreshOnUnauthorized: refreshCodexPlatformJwt,
+ }),
+ proxy: new GrokLlmProxyClient({
+ runtimeUrl: resolveGrokProxyRuntimeUrl(config.grokProxyRuntimeBaseUrl),
+ readPlatformJwt: readCodexPlatformJwt,
+ refreshOnUnauthorized: refreshCodexPlatformJwt,
+ }),
+ attemptContext: ({ model }: { model: string }): GrokAttemptContext => {
+ if (captured) return captured
+ const resolved = resolveGrokAttemptPolicy({
+ model,
+ envRevision: config.grokPolicyRevision,
+ envHash: config.grokPolicyHash,
+ binding: readLiveGrokPolicyBinding(),
+ })
+ if (!resolved) {
+ return { policyRevision: 0, policyHash: '' }
+ }
+ return {
+ ...resolved,
+ hostRef: config.hostName,
+ }
+ },
+ }
+}
+
function createCodexRuntimeDeps(captured?: CodexAttemptContext) {
const gateway = (config.mcpHostGatewayUrl ?? '').trim() || DEFAULT_CODEX_AUTHORIZE_GATEWAY
return {
@@ -99,7 +134,9 @@ export function createLLMProvider(
modelName,
provider === 'codex-subscription'
? { codex: createCodexRuntimeDeps(options?.capturedCodexAttemptContext) }
- : undefined
+ : provider === 'grok-subscription'
+ ? { grok: createGrokRuntimeDeps() }
+ : undefined
)
} catch (err) {
console.error('[LLM] failed to construct provider')
diff --git a/mcp-host/src/llm/registry.ts b/mcp-host/src/llm/registry.ts
index cead3cfe9..8e622a101 100644
--- a/mcp-host/src/llm/registry.ts
+++ b/mcp-host/src/llm/registry.ts
@@ -22,6 +22,7 @@ import { ClaudeProvider } from './claude'
import { type CodexSubscriptionDeps, CodexSubscriptionProvider } from './codexSubscription'
import { buildBedrockConverseDriver } from './drivers/bedrockConverse'
import { buildGoogleGenerativeDriver } from './drivers/googleGenerative'
+import { type GrokSubscriptionDeps, GrokSubscriptionProvider } from './grokSubscription'
import { OpenAIProvider } from './openai'
import { OpenAICompatibleProvider } from './openaiCompatible'
import { type LlmProvider, descriptorFor, primarySlot } from './registryCore'
@@ -29,6 +30,7 @@ import type { SingleTurnProvider } from './types'
export type MakeProviderOptions = {
codex?: CodexSubscriptionDeps
+ grok?: GrokSubscriptionDeps
}
export {
@@ -97,6 +99,16 @@ export function makeProvider(
)
}
return new CodexSubscriptionProvider(model, options.codex)
+ case 'grok-subscription':
+ if (process.env.MCP_HOST_GROK_SUBSCRIPTION_ENABLED !== 'true') {
+ throw new Error('[LLM] makeProvider: grok-subscription is disabled')
+ }
+ if (!model?.trim() || !options?.grok) {
+ throw new Error(
+ '[LLM] makeProvider: grok-subscription requires an explicit model and runtime authorizer/proxy dependencies'
+ )
+ }
+ return new GrokSubscriptionProvider(model, options.grok)
}
// Data-driven arm: anything carrying a baseURL is OpenAI-compatible and is
diff --git a/mcp-host/src/llm/registryCore.ts b/mcp-host/src/llm/registryCore.ts
index 83255ff67..1dc3972a6 100644
--- a/mcp-host/src/llm/registryCore.ts
+++ b/mcp-host/src/llm/registryCore.ts
@@ -201,6 +201,7 @@ const RUNTIME_FIELDS: Record<LlmProvider, RuntimeProviderFields> = {
azure: { defaultModel: 'gpt-4.1', tokenizer: 'openai' },
// Broker: explicit model required later; no Secret slot and no default.
'codex-subscription': { tokenizer: 'fallback' },
+ 'grok-subscription': { tokenizer: 'fallback' },
}
// Order = dev auto-detection priority (first present key wins), inherited from
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index ace4ce076..fd07db920 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -67,6 +67,7 @@ import { FailoverEngine } from './llm/failover/engine'
import { llmFallbackTotal } from './llm/failover/metrics'
import { parseLlmPolicy } from './llm/failover/policy'
import type { FailoverSwitchEvent, FallbackEntry, LlmPolicy } from './llm/failover/types'
+import { setGrokPolicyBindingReader } from './llm/grokPolicyBinding'
import { hostPrimaryLlmBindingChanged } from './llm/hostLlmBinding'
import { PromptCache } from './llm/promptCache'
import { clerumPromptCacheInvalidationsTotal } from './llm/promptCacheMetrics'
@@ -188,6 +189,7 @@ let currentKeys: ApiKeys = {}
let currentProvider: SingleTurnProvider | null = null
let configStore: ConfigStore | null = null
setCodexPolicyBindingReader(() => configStore?.codexPolicyBinding() ?? null)
+setGrokPolicyBindingReader(() => configStore?.grokPolicyBinding() ?? null)
// R5 — provider-fallback. `currentPolicy` is the normalized `spec.llmPolicy`
// (null = no failover); `failoverEngine` holds the Host-wide sticky state
// (cooldown + served pair) and is (re)built only when the policy changes.