Skip to content

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

TypeScript

feat(mcp-host): execute Codex attempts through isolated proxy

Alfredo Lopezc28788f5865d
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index d54a71fff..37d22ddf4 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -62,6 +62,10 @@ export interface Config {
// Default OFF. Codex provider construction stays dark until the operator
// sets MCP_HOST_CODEX_SUBSCRIPTION_ENABLED=true.
codexSubscriptionEnabled: boolean
+ // Server-owned Codex proxy URL. Callers cannot override this per request.
+ codexProxyRuntimeBaseUrl: string
+ codexPolicyRevision: number
+ codexPolicyHash: string
// Dev mode: MCP servers (parsed from CLERUM_MCP_SERVERS JSON)
devMcpServers?: McpServerInfo[]
@@ -647,6 +651,12 @@ export const config: Config = {
devModelProvider: devMode ? resolveDevModelProvider(rawDevModelProvider) : undefined,
devModelName,
codexSubscriptionEnabled: process.env.MCP_HOST_CODEX_SUBSCRIPTION_ENABLED === 'true',
+ codexProxyRuntimeBaseUrl: getEnv(
+ 'CODEX_LLM_PROXY_RUNTIME_URL',
+ 'http://codex-llm-proxy.control-plane.svc.cluster.local:8080'
+ )!,
+ codexPolicyRevision: parseInt(getEnv('CODEX_POLICY_REVISION', '1')!, 10),
+ codexPolicyHash: getEnv('CODEX_POLICY_HASH', '')!,
// Dev mode MCP servers
devMcpServers: devMode ? parseDevMcpServers() : undefined,
diff --git a/mcp-host/src/core/adapters/__tests__/llmPortAdapter.test.ts b/mcp-host/src/core/adapters/__tests__/llmPortAdapter.test.ts
index 3a96794d2..8b3ab74ac 100644
--- a/mcp-host/src/core/adapters/__tests__/llmPortAdapter.test.ts
+++ b/mcp-host/src/core/adapters/__tests__/llmPortAdapter.test.ts
@@ -613,4 +613,26 @@ describe('Cross-provider ToolCall normalization', () => {
expect(typeof openaiResult.tool_calls![0].arguments).toBe('object')
expect(typeof claudeResult.tool_calls![0].arguments).toBe('object')
})
+
+ it('preserves Codex insufficient_scope on the LlmError boundary', async () => {
+ const mockProvider: SingleTurnProvider = {
+ completeSingleTurn: vi.fn().mockRejectedValue(new Error('missing scope')),
+ completeSingleTurnWithTools: vi.fn(),
+ getProviderType: () => 'codex-subscription' as const,
+ classifyError: vi.fn(() => ({
+ code: LlmErrorCode.AuthenticationFailed,
+ retryable: false,
+ message: 'missing scope',
+ providerCode: 'insufficient_scope',
+ })),
+ }
+ const adapter = new LlmPortAdapter(mockProvider, 'gpt-5.3-codex', 'codex-subscription')
+ await expect(
+ adapter.complete({ messages: [{ role: 'user', content: 'Hi' }] })
+ ).rejects.toMatchObject({
+ code: LlmErrorCode.AuthenticationFailed,
+ providerCode: 'insufficient_scope',
+ retryable: false,
+ })
+ })
})
diff --git a/mcp-host/src/llm/__tests__/codexLlmProxyClient.test.ts b/mcp-host/src/llm/__tests__/codexLlmProxyClient.test.ts
new file mode 100644
index 000000000..c75c38041
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/codexLlmProxyClient.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest'
+import { CodexLlmProxyClient, resolveCodexProxyRuntimeUrl } from '../codexLlmProxyClient'
+
+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('CodexLlmProxyClient', () => {
+ it('streams to the frozen runtime Service URL and never accepts a caller URL', async () => {
+ const fetchFn = vi.fn().mockResolvedValue({
+ ok: true,
+ body: sse([
+ { type: 'text', text: 'hello' },
+ { type: 'tool_call', id: 'c1', name: 'echo', arguments: { x: 1 } },
+ { type: 'done', outcome: 'success' },
+ ]),
+ })
+ const client = new CodexLlmProxyClient({
+ runtimeUrl: resolveCodexProxyRuntimeUrl(
+ 'http://codex-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: 'gpt-5.3-codex' },
+ })
+ expect(fetchFn.mock.calls[0][0]).toBe(
+ 'http://codex-llm-proxy.control-plane.svc.cluster.local:8080/internal/runtime/v1/codex/completions'
+ )
+ expect(result.text).toBe('hello')
+ expect(result.toolCalls).toEqual([
+ { type: 'tool_call', id: 'c1', name: 'echo', arguments: { x: 1 } },
+ ])
+ })
+
+ it('fails closed when aborted before the proxy hop', async () => {
+ const client = new CodexLlmProxyClient({
+ runtimeUrl:
+ 'http://codex-llm-proxy.control-plane.svc.cluster.local:8080/internal/runtime/v1/codex/completions',
+ readPlatformJwt: () => 'platform-jwt',
+ fetchFn: vi.fn() as unknown as typeof fetch,
+ })
+ const signal = AbortSignal.abort()
+ await expect(
+ client.stream({
+ executionTicket: 'ticket-123456',
+ requestHash: 'a'.repeat(64),
+ request: {},
+ signal,
+ })
+ ).rejects.toMatchObject({ code: 'canceled' })
+ expect(client['options'].fetchFn).not.toHaveBeenCalled()
+ })
+})
diff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
new file mode 100644
index 000000000..2c917c3a2
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest'
+import { LlmErrorCode } from '../../core/errors'
+import { CodexSubscriptionProvider } from '../codexSubscription'
+import { CodexAuthorizeError } from '../providerAttemptAuthorizer'
+import { makeProvider } from '../registry'
+
+const requestHash = 'a'.repeat(64)
+
+function deps(overrides?: {
+ authorize?: ReturnType<typeof vi.fn>
+ stream?: ReturnType<typeof vi.fn>
+}) {
+ const authorize =
+ overrides?.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 proxy',
+ toolCalls: [],
+ outcome: 'success',
+ })
+ return {
+ authorizer: { authorize },
+ proxy: { stream },
+ attemptContext: () => ({
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ hostRef: 'chatllm',
+ }),
+ authorize,
+ stream,
+ }
+}
+
+describe('CodexSubscriptionProvider', () => {
+ it('requires an explicit model plus authorizer and proxy dependencies', () => {
+ process.env.MCP_HOST_CODEX_SUBSCRIPTION_ENABLED = 'true'
+ expect(() => makeProvider('codex-subscription', {})).toThrow(/explicit model and runtime/)
+ expect(() => makeProvider('codex-subscription', {}, 'gpt-5.3-codex')).toThrow(
+ /explicit model and runtime/
+ )
+ const wired = deps()
+ const provider = makeProvider('codex-subscription', {}, 'gpt-5.3-codex', {
+ codex: wired as never,
+ })
+ expect(provider.getProviderType()).toBe('codex-subscription')
+ delete process.env.MCP_HOST_CODEX_SUBSCRIPTION_ENABLED
+ })
+
+ it('authorizes through the gateway and streams to the proxy without executing tools', async () => {
+ const wired = deps({
+ stream: vi.fn().mockResolvedValue({
+ text: 'use a tool',
+ toolCalls: [{ id: 'c1', name: 'echo', arguments: { x: 1 } }],
+ outcome: 'success',
+ }),
+ })
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+ const result = await provider.completeSingleTurnWithTools(
+ [{ role: 'user', content: 'hi' }],
+ [{ name: 'echo', description: 'echo', parameters: {} }]
+ )
+ expect(wired.authorize).toHaveBeenCalledTimes(1)
+ const authorizedBody = wired.authorize.mock.calls[0][0]
+ expect(authorizedBody.request.model).toBe('gpt-5.3-codex')
+ expect(authorizedBody.requestHash).toMatch(/^[a-f0-9]{64}$/)
+ expect(wired.stream).toHaveBeenCalledWith(
+ expect.objectContaining({
+ executionTicket: 'ticket-123456',
+ requestHash,
+ })
+ )
+ expect(result.tool_calls).toEqual([{ id: 'c1', name: 'echo', arguments: { x: 1 } }])
+ })
+
+ it('does not call the proxy when aborted before authorize', async () => {
+ const wired = deps()
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
+ await expect(
+ provider.completeSingleTurn([{ role: 'user', content: 'hi' }], {
+ signal: AbortSignal.abort(),
+ })
+ ).rejects.toMatchObject({ code: 'canceled' })
+ expect(wired.authorize).not.toHaveBeenCalled()
+ expect(wired.stream).not.toHaveBeenCalled()
+ })
+
+ it('keeps insufficient_scope distinguishable', () => {
+ const provider = new CodexSubscriptionProvider('gpt-5.3-codex', deps() as never)
+ const classified = provider.classifyError(
+ new CodexAuthorizeError('insufficient_scope', 'missing scope')
+ )
+ expect(classified.code).toBe(LlmErrorCode.AuthenticationFailed)
+ expect(classified.providerCode).toBe('insufficient_scope')
+ expect(classified.retryable).toBe(false)
+ })
+})
diff --git a/mcp-host/src/llm/__tests__/makeProviderR6.test.ts b/mcp-host/src/llm/__tests__/makeProviderR6.test.ts
index a61c6cb82..2ceac6296 100644
--- a/mcp-host/src/llm/__tests__/makeProviderR6.test.ts
+++ b/mcp-host/src/llm/__tests__/makeProviderR6.test.ts
@@ -57,7 +57,7 @@ describe('R6 OpenAI-compatible providers — data-driven baseURL arm', () => {
const desc = descriptorFor(provider)
const result = createLLMProvider(
{ [provider]: { [`${provider}-api-key`]: 'sk-test' } },
- { provider, name: desc.defaultModel }
+ { provider, name: desc.defaultModel ?? provider }
)
expect(result, `createLLMProvider returned null for ${provider}`).not.toBeNull()
expect(result?.getProviderType()).toBe(provider)
diff --git a/mcp-host/src/llm/__tests__/providerAttemptAuthorizer.test.ts b/mcp-host/src/llm/__tests__/providerAttemptAuthorizer.test.ts
new file mode 100644
index 000000000..babd3e371
--- /dev/null
+++ b/mcp-host/src/llm/__tests__/providerAttemptAuthorizer.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+ CodexAuthorizeError,
+ ProviderAttemptAuthorizer,
+ resolveCodexAuthorizeUrl,
+} from '../providerAttemptAuthorizer'
+
+const validAuthorize = {
+ providerAttemptId: 'attempt-1',
+ requestHash: 'a'.repeat(64),
+ executionTicket: 'ticket-123456',
+ expiresAt: '2026-08-20T10:00:00.000Z',
+}
+
+describe('ProviderAttemptAuthorizer', () => {
+ it('posts the platform JWT to the server-owned gateway URL', async () => {
+ const fetchFn = vi.fn().mockResolvedValue({
+ ok: true,
+ json: async () => validAuthorize,
+ })
+ const authorizer = new ProviderAttemptAuthorizer({
+ authorizeUrl: resolveCodexAuthorizeUrl('http://gateway:8092'),
+ readPlatformJwt: () => 'platform-jwt',
+ fetchFn: fetchFn as unknown as typeof fetch,
+ })
+ const result = await authorizer.authorize({
+ request: { schemaVersion: 'codex-completion-request.v1' },
+ invocationId: 'inv-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ })
+ expect(fetchFn).toHaveBeenCalledWith(
+ 'http://gateway:8092/api/v1/mcp-host/llm/provider-attempts/authorize',
+ expect.objectContaining({
+ method: 'POST',
+ headers: expect.objectContaining({ authorization: 'Bearer platform-jwt' }),
+ })
+ )
+ expect(result.executionTicket).toBe('ticket-123456')
+ expect(result).not.toHaveProperty('accessToken')
+ })
+
+ it('rejects an authorize payload that leaks an access token', async () => {
+ const authorizer = new ProviderAttemptAuthorizer({
+ authorizeUrl: 'http://gateway:8092/api/v1/mcp-host/llm/provider-attempts/authorize',
+ readPlatformJwt: () => 'platform-jwt',
+ fetchFn: vi.fn().mockResolvedValue({
+ ok: true,
+ json: async () => ({ ...validAuthorize, accessToken: 'sk-leaked' }),
+ }) as unknown as typeof fetch,
+ })
+ await expect(
+ authorizer.authorize({
+ request: {},
+ invocationId: 'inv-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ })
+ ).rejects.toMatchObject({ code: 'invalid_request' })
+ })
+
+ it('maps insufficient_scope from the gateway', async () => {
+ const authorizer = new ProviderAttemptAuthorizer({
+ authorizeUrl: 'http://gateway:8092/api/v1/mcp-host/llm/provider-attempts/authorize',
+ readPlatformJwt: () => 'platform-jwt',
+ fetchFn: vi.fn().mockResolvedValue({
+ ok: false,
+ status: 403,
+ json: async () => ({ error: 'insufficient_scope' }),
+ }) as unknown as typeof fetch,
+ })
+ await expect(
+ authorizer.authorize({
+ request: {},
+ invocationId: 'inv-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ })
+ ).rejects.toBeInstanceOf(CodexAuthorizeError)
+ await expect(
+ authorizer.authorize({
+ request: {},
+ invocationId: 'inv-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'b'.repeat(64),
+ })
+ ).rejects.toMatchObject({ code: 'insufficient_scope' })
+ })
+})
diff --git a/mcp-host/src/llm/__tests__/registry.test.ts b/mcp-host/src/llm/__tests__/registry.test.ts
index 3b89dc6de..3597b3554 100644
--- a/mcp-host/src/llm/__tests__/registry.test.ts
+++ b/mcp-host/src/llm/__tests__/registry.test.ts
@@ -225,7 +225,8 @@ describe('codex-subscription zero-slot broker', () => {
expect(() => makeProvider('codex-subscription', {})).toThrow(
/requires an explicit model and runtime authorizer/
)
- expect(createLLMProvider({}, { provider: 'codex-subscription', name: 'gpt-5.1' })).toBeNull()
+ const provider = createLLMProvider({}, { provider: 'codex-subscription', name: 'gpt-5.1' })
+ expect(provider?.getProviderType()).toBe('codex-subscription')
delete process.env.MCP_HOST_CODEX_SUBSCRIPTION_ENABLED
})
})
diff --git a/mcp-host/src/llm/codexLlmProxyClient.ts b/mcp-host/src/llm/codexLlmProxyClient.ts
new file mode 100644
index 000000000..8e8babdb4
--- /dev/null
+++ b/mcp-host/src/llm/codexLlmProxyClient.ts
@@ -0,0 +1,104 @@
+export const CODEX_PROXY_COMPLETIONS_PATH = '/internal/runtime/v1/codex/completions'
+
+export class CodexProxyError extends Error {
+ constructor(
+ readonly code: string,
+ message: string
+ ) {
+ super(message)
+ this.name = 'CodexProxyError'
+ }
+}
+
+export type CodexProxyFrame =
+ | { type: 'text'; text: string }
+ | { type: 'tool_call'; id: string; name: string; arguments: Record<string, unknown> }
+ | { type: 'done'; outcome: 'success' | 'canceled' | 'error' | 'unknown' }
+
+export type CodexProxyStreamResult = {
+ text: string
+ toolCalls: Array<{ id: string; name: string; arguments: Record<string, unknown> }>
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+}
+
+export type CodexLlmProxyClientOptions = {
+ runtimeUrl: string
+ readPlatformJwt: () => string
+ fetchFn?: typeof fetch
+}
+
+export class CodexLlmProxyClient {
+ constructor(private readonly options: CodexLlmProxyClientOptions) {
+ if (!options.runtimeUrl.startsWith('http://') && !options.runtimeUrl.startsWith('https://')) {
+ throw new Error('[CodexProxy] runtime URL must be an absolute server-owned URL')
+ }
+ }
+
+ async stream(input: {
+ executionTicket: string
+ requestHash: string
+ request: unknown
+ deadlineMs?: number
+ signal?: AbortSignal
+ }): Promise<CodexProxyStreamResult> {
+ if (input.signal?.aborted) {
+ throw new CodexProxyError('canceled', 'aborted before proxy stream')
+ }
+ 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) {
+ const payload = (await response.json().catch(() => ({}))) as Record<string, unknown>
+ const code = typeof payload.error === 'string' ? payload.error : 'provider_unavailable'
+ throw new CodexProxyError(code, `proxy stream failed with ${response.status}`)
+ }
+ if (!response.body) {
+ throw new CodexProxyError('provider_unavailable', 'proxy stream had no body')
+ }
+ return readProxySse(response.body)
+ }
+}
+
+export function resolveCodexProxyRuntimeUrl(base: string): string {
+ const trimmed = base.replace(/\/+$/, '')
+ if (trimmed.endsWith(CODEX_PROXY_COMPLETIONS_PATH)) return trimmed
+ return `${trimmed}${CODEX_PROXY_COMPLETIONS_PATH}`
+}
+
+async function readProxySse(body: ReadableStream<Uint8Array>): Promise<CodexProxyStreamResult> {
+ const reader = body.getReader()
+ const decoder = new TextDecoder()
+ let buffer = ''
+ let text = ''
+ const toolCalls: CodexProxyStreamResult['toolCalls'] = []
+ let outcome: CodexProxyStreamResult['outcome'] = 'unknown'
+ 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 CodexProxyFrame
+ if (frame.type === 'text') text += frame.text
+ if (frame.type === 'tool_call') toolCalls.push(frame)
+ if (frame.type === 'done') outcome = frame.outcome
+ }
+ }
+ return { text, toolCalls, outcome }
+}
diff --git a/mcp-host/src/llm/codexSubscription.ts b/mcp-host/src/llm/codexSubscription.ts
new file mode 100644
index 000000000..c90e4d9c0
--- /dev/null
+++ b/mcp-host/src/llm/codexSubscription.ts
@@ -0,0 +1,212 @@
+import { randomUUID } from 'node:crypto'
+import {
+ type CodexCompletionRequestV1,
+ hashCodexCompletionRequestV1,
+} from '@clerum/llm-provider-attempt-contract'
+import { LlmErrorCode } from '../core/errors'
+import {
+ CompletionResponse,
+ ChatMessage as CoreChatMessage,
+ FinishReason,
+ ToolCompletionResponse,
+ ToolDefinition,
+} from '../core/types'
+import { CodexLlmProxyClient, CodexProxyError } from './codexLlmProxyClient'
+import { classifyUnknown } from './errorClassification'
+import { CodexAuthorizeError, ProviderAttemptAuthorizer } from './providerAttemptAuthorizer'
+import type { LlmProvider } from './registryCore'
+import type { ClassifiedError, SingleTurnProvider } from './types'
+
+export type CodexAttemptContext = {
+ invocationId?: string
+ attemptGeneration?: number
+ providerAttemptIndex?: number
+ policyRevision: number
+ policyHash: string
+ hostRef?: string
+ recipeNamespace?: string
+ recipeName?: string
+ userId?: string
+}
+
+export type CodexSubscriptionDeps = {
+ authorizer: ProviderAttemptAuthorizer
+ proxy: CodexLlmProxyClient
+ attemptContext: () => CodexAttemptContext
+}
+
+export class CodexSubscriptionProvider implements SingleTurnProvider {
+ constructor(
+ private readonly model: string,
+ private readonly deps: CodexSubscriptionDeps
+ ) {
+ if (!model.trim()) {
+ throw new Error('[LLM] makeProvider: codex-subscription requires an explicit model')
+ }
+ }
+
+ getProviderType(): LlmProvider {
+ return 'codex-subscription'
+ }
+
+ classifyError(err: unknown): ClassifiedError {
+ const code =
+ err instanceof CodexAuthorizeError || err instanceof CodexProxyError ? err.code : undefined
+ if (code === 'insufficient_scope' || code === 'no_grant' || code === 'host_binding_mismatch') {
+ return {
+ code: LlmErrorCode.AuthenticationFailed,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ }
+ }
+ if (code === 'budget_denied') {
+ return {
+ code: LlmErrorCode.InsufficientQuota,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ }
+ }
+ if (code === 'model_not_allowed') {
+ return {
+ code: LlmErrorCode.ModelNotAvailable,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ }
+ }
+ if (code) {
+ return {
+ code: LlmErrorCode.ApiCallFailed,
+ retryable: false,
+ message: err instanceof Error ? err.message : String(err),
+ providerCode: code,
+ }
+ }
+ 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)
+ return {
+ content: result.text,
+ usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 },
+ usage_reported: false,
+ finish_reason: result.outcome === 'canceled' ? FinishReason.Unknown : FinishReason.Stop,
+ }
+ }
+
+ 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)
+ 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: { input_tokens: 0, output_tokens: 0, total_tokens: 0 },
+ usage_reported: false,
+ finish_reason: result.toolCalls.length > 0 ? FinishReason.ToolUse : 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 CodexProxyError('canceled', 'aborted before authorize')
+ }
+ const request = this.buildRequest(messages, tools, options)
+ const requestHash = hashCodexCompletionRequestV1(request)
+ const context = this.deps.attemptContext()
+ const authorized = await this.deps.authorizer.authorize({
+ request,
+ requestHash,
+ invocationId: context.invocationId ?? request.requestId,
+ attemptGeneration: context.attemptGeneration ?? 1,
+ providerAttemptIndex: context.providerAttemptIndex ?? 1,
+ policyRevision: context.policyRevision,
+ policyHash: context.policyHash,
+ hostRef: context.hostRef,
+ recipeNamespace: context.recipeNamespace,
+ recipeName: context.recipeName,
+ userId: context.userId,
+ })
+ if (!('accessToken' in authorized)) {
+ // Bound: authorize returns ticket material only.
+ }
+ return this.deps.proxy.stream({
+ executionTicket: authorized.executionTicket,
+ requestHash: authorized.requestHash,
+ request,
+ signal: options?.signal,
+ })
+ }
+
+ private buildRequest(
+ messages: CoreChatMessage[],
+ tools: ToolDefinition[] | undefined,
+ options?: { max_tokens?: number; temperature?: number; tool_choice?: string }
+ ): CodexCompletionRequestV1 {
+ const request: CodexCompletionRequestV1 = {
+ schemaVersion: 'codex-completion-request.v1',
+ requestId: randomUUID(),
+ idempotencyKey: randomUUID(),
+ provider: 'codex-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 } : {}),
+ })),
+ }
+ if (tools && tools.length > 0) {
+ 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 1f93bd979..f92e862c3 100644
--- a/mcp-host/src/llm/index.ts
+++ b/mcp-host/src/llm/index.ts
@@ -1,9 +1,12 @@
/**
* LLM Provider factory.
*/
+import { config } from '../config'
import { ApiKeys, ModelConfig } from '../types'
import { ClaudeProvider } from './claude'
+import { CodexLlmProxyClient, resolveCodexProxyRuntimeUrl } from './codexLlmProxyClient'
import { OpenAIProvider } from './openai'
+import { ProviderAttemptAuthorizer, resolveCodexAuthorizeUrl } from './providerAttemptAuthorizer'
import { makeProvider } from './registry'
import { ALL_PROVIDERS, descriptorFor, isLlmProvider } from './registryCore'
// Re-export the transport interfaces (moved to ./types to break the registry
@@ -13,6 +16,31 @@ import type { ClassifiedError, SingleTurnProvider } from './types'
export type { ClassifiedError, SingleTurnProvider } from './types'
+const DEFAULT_CODEX_AUTHORIZE_GATEWAY =
+ 'http://nginx-workflow-approval-gateway.control-plane.svc.cluster.local:8092'
+
+function readPlatformJwt(): string {
+ return (process.env.MCP_HOST_RUNTIME_ACCESS_TOKEN || '').trim()
+}
+
+function createCodexRuntimeDeps() {
+ const gateway = (config.mcpHostGatewayUrl ?? '').trim() || DEFAULT_CODEX_AUTHORIZE_GATEWAY
+ return {
+ authorizer: new ProviderAttemptAuthorizer({
+ authorizeUrl: resolveCodexAuthorizeUrl(gateway),
+ readPlatformJwt,
+ }),
+ proxy: new CodexLlmProxyClient({
+ runtimeUrl: resolveCodexProxyRuntimeUrl(config.codexProxyRuntimeBaseUrl),
+ readPlatformJwt,
+ }),
+ attemptContext: () => ({
+ policyRevision: config.codexPolicyRevision,
+ policyHash: config.codexPolicyHash,
+ }),
+ }
+}
+
/**
* Create an LLM provider based on configuration.
*/
@@ -47,7 +75,12 @@ export function createLLMProvider(
// never throw here (their empty-key case is already handled above), so their
// behaviour is byte-identical.
try {
- return makeProvider(provider, credentials, modelName)
+ return makeProvider(
+ provider,
+ credentials,
+ modelName,
+ provider === 'codex-subscription' ? { codex: createCodexRuntimeDeps() } : undefined
+ )
} catch (err) {
console.error(
`[LLM] failed to construct ${provider}:`,
diff --git a/mcp-host/src/llm/providerAttemptAuthorizer.ts b/mcp-host/src/llm/providerAttemptAuthorizer.ts
new file mode 100644
index 000000000..1c2c35257
--- /dev/null
+++ b/mcp-host/src/llm/providerAttemptAuthorizer.ts
@@ -0,0 +1,91 @@
+import { parseAuthorizeAttemptResponse } from '@clerum/llm-provider-attempt-contract'
+
+export const AUTHORIZE_PATH = '/api/v1/mcp-host/llm/provider-attempts/authorize'
+
+export class CodexAuthorizeError extends Error {
+ constructor(
+ readonly code: string,
+ message: string
+ ) {
+ super(message)
+ this.name = 'CodexAuthorizeError'
+ }
+}
+
+export type AuthorizeAttemptBody = {
+ request: unknown
+ invocationId: string
+ attemptGeneration: number
+ providerAttemptIndex: number
+ policyRevision: number
+ policyHash: string
+ requestHash?: string
+ hostRef?: string
+ recipeNamespace?: string
+ recipeName?: string
+ userId?: string
+ budgetReservationId?: string
+}
+
+export type ProviderAttemptAuthorizerOptions = {
+ authorizeUrl: string
+ readPlatformJwt: () => string
+ fetchFn?: typeof fetch
+}
+
+const LEAK_KEYS = ['accessToken', 'refreshToken', 'authorization']
+
+export class ProviderAttemptAuthorizer {
+ constructor(private readonly options: ProviderAttemptAuthorizerOptions) {
+ if (
+ !options.authorizeUrl.startsWith('http://') &&
+ !options.authorizeUrl.startsWith('https://')
+ ) {
+ throw new Error('[CodexAuthorize] authorize URL must be an absolute server-owned URL')
+ }
+ }
+
+ async authorize(body: AuthorizeAttemptBody): Promise<{
+ providerAttemptId: string
+ requestHash: string
+ executionTicket: string
+ expiresAt: string
+ }> {
+ const jwt = this.options.readPlatformJwt()
+ if (!jwt) {
+ throw new CodexAuthorizeError('no_grant', 'platform JWT is missing')
+ }
+ const fetchFn = this.options.fetchFn ?? fetch
+ const response = await fetchFn(this.options.authorizeUrl, {
+ method: 'POST',
+ headers: {
+ authorization: `Bearer ${jwt}`,
+ 'content-type': 'application/json',
+ },
+ body: JSON.stringify(body),
+ })
+ const payload = (await response.json().catch(() => ({}))) as Record<string, unknown>
+ if (!response.ok) {
+ const code = typeof payload.error === 'string' ? payload.error : 'provider_unavailable'
+ throw new CodexAuthorizeError(code, `authorize failed with ${response.status}`)
+ }
+ for (const key of LEAK_KEYS) {
+ if (key in payload) {
+ throw new CodexAuthorizeError(
+ 'invalid_request',
+ 'authorize response leaked credential material'
+ )
+ }
+ }
+ const parsed = parseAuthorizeAttemptResponse(payload)
+ if (!parsed.ok) {
+ throw new CodexAuthorizeError('invalid_request', parsed.message)
+ }
+ return parsed.value
+ }
+}
+
+export function resolveCodexAuthorizeUrl(gatewayBase: string): string {
+ const trimmed = gatewayBase.replace(/\/+$/, '')
+ return `${trimmed}${AUTHORIZE_PATH}`
+}
diff --git a/mcp-host/src/llm/registry.ts b/mcp-host/src/llm/registry.ts
index 7ac9a66bc..cead3cfe9 100644
--- a/mcp-host/src/llm/registry.ts
+++ b/mcp-host/src/llm/registry.ts
@@ -19,6 +19,7 @@
import type { ProviderCredentials } from '../types'
import { AzureOpenAIProvider } from './azure'
import { ClaudeProvider } from './claude'
+import { type CodexSubscriptionDeps, CodexSubscriptionProvider } from './codexSubscription'
import { buildBedrockConverseDriver } from './drivers/bedrockConverse'
import { buildGoogleGenerativeDriver } from './drivers/googleGenerative'
import { OpenAIProvider } from './openai'
@@ -26,6 +27,10 @@ import { OpenAICompatibleProvider } from './openaiCompatible'
import { type LlmProvider, descriptorFor, primarySlot } from './registryCore'
import type { SingleTurnProvider } from './types'
+export type MakeProviderOptions = {
+ codex?: CodexSubscriptionDeps
+}
+
export {
ALL_PROVIDERS,
type CoreProviderDescriptor,
@@ -58,7 +63,8 @@ export {
export function makeProvider(
provider: LlmProvider,
credentials: ProviderCredentials,
- model?: string
+ model?: string,
+ options?: MakeProviderOptions
): SingleTurnProvider {
const d = descriptorFor(provider)
switch (provider) {
@@ -68,23 +74,29 @@ export function makeProvider(
return new ClaudeProvider(credentials[primarySlot(d).dataKey], model)
case 'vertex':
// Own-SDK arm — lazy require lives inside the driver builder.
- return buildGoogleGenerativeDriver(credentials, model ?? d.defaultModel)
+ return buildGoogleGenerativeDriver(credentials, model ?? d.defaultModel ?? '')
case 'bedrock':
// Own-SDK arm — lazy require lives inside the driver builder.
- return buildBedrockConverseDriver(credentials, model ?? d.defaultModel)
+ return buildBedrockConverseDriver(credentials, model ?? d.defaultModel ?? '')
case 'azure':
// Light-driver arm: OpenAI wire shape but per-resource host
// (AZURE_OPENAI_ENDPOINT) + `api-key` header + deployment-name-as-model, so
// it deliberately has NO static baseURL and must not hit the data arm
// below. Fails closed (throws) if the operator omitted the endpoint.
- return new AzureOpenAIProvider(credentials[primarySlot(d).dataKey], model ?? d.defaultModel)
+ return new AzureOpenAIProvider(
+ credentials[primarySlot(d).dataKey],
+ model ?? d.defaultModel ?? ''
+ )
case 'codex-subscription':
if (process.env.MCP_HOST_CODEX_SUBSCRIPTION_ENABLED !== 'true') {
throw new Error('[LLM] makeProvider: codex-subscription is disabled')
}
- throw new Error(
- '[LLM] makeProvider: codex-subscription requires an explicit model and runtime authorizer/proxy dependencies'
- )
+ if (!model?.trim() || !options?.codex) {
+ throw new Error(
+ '[LLM] makeProvider: codex-subscription requires an explicit model and runtime authorizer/proxy dependencies'
+ )
+ }
+ return new CodexSubscriptionProvider(model, options.codex)
}
// 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 106f317af..83255ff67 100644
--- a/mcp-host/src/llm/registryCore.ts
+++ b/mcp-host/src/llm/registryCore.ts
@@ -219,7 +219,7 @@ export const PROVIDERS: Record<LlmProvider, CoreProviderDescriptor> = Object.fro
...RUNTIME_FIELDS[id],
},
])
-) as Record<LlmProvider, CoreProviderDescriptor>
+) as unknown as Record<LlmProvider, CoreProviderDescriptor>
export const ALL_PROVIDERS = [...PROVIDER_IDS] as LlmProvider[]
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index 4ecb31d3b..d46fda639 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -618,7 +618,7 @@ async function ensureConfigStore(host: HostCRD): Promise<ConfigStore> {
const store = new ConfigStore({
namespace: config.namespace,
hostRef: host.name,
- llmSecretRef: host.spec.secretRef,
+ llmSecretRef: host.spec.secretRef ?? null,
provider,
allowlistConfigMapName: config.llmAllowlistConfigMapName,
// R5 — load the failover policy's referenced credential slots from the same