Skip to content

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

TypeScript
23.9 KB
Raw Blame
import { randomUUID } from 'node:crypto'
import {
  type CodexCompletionRequest,
  LIMITS,
  VISUAL_LIMITS,
  hashCanonicalCodexRequest,
} from '@clerum/llm-provider-attempt-contract'
import { LlmErrorCode } from '../core/errors'
import {
  CompletionResponse,
  ChatMessage as CoreChatMessage,
  FinishReason,
  ToolCompletionResponse,
  ToolDefinition,
} from '../core/types'
import { logger } from '../logger'
import { resolveVisualDeliveryLimits } from '../visualInput/deliveryLimits'
import {
  attachmentBudgetRefusalMessageFor,
  buildAttachmentBudgetRefusals,
} from './attachmentBudgetRefusal'
import { CodexLlmProxyClient, CodexProxyError } from './codexLlmProxyClient'
import { classifyUnknown } from './errorClassification'
import { type ImageTransportOperation, transportSupportsImageInput } from './imageInput'
import { IMAGE_SOURCE_INVALID, canonicalRefusalCode, projectMessage } from './imageSource'
import { CodexAuthorizeError, ProviderAttemptAuthorizer } from './providerAttemptAuthorizer'
import { authorizeRetryDelayMs, rateLimitRetryDelayMs, waitBeforeRetry } from './rateLimitRetry'
import { type LlmProvider, descriptorFor } from './registryCore'
import type { ClassifiedError, SingleTurnProvider } from './types'

export type CodexAttemptContext = {
  invocationId?: string
  attemptGeneration?: number
  providerAttemptIndex?: number
  pluginWorkloadSdkProviderAttemptId?: string
  targetRef?: string
  policyRevision: number
  policyHash: string
  hostRef?: string
  recipeNamespace?: string
  recipeName?: string
  userId?: string
}

/**
 * The Codex image budget refusals, built from the Codex contract limits (see
 * `buildAttachmentBudgetRefusals` for the rows and their order).
 */
const ATTACHMENT_BUDGET_REFUSALS = buildAttachmentBudgetRefusals({
  maxImageBytes: VISUAL_LIMITS.maxImageBytes,
  maxTotalImageBytes: VISUAL_LIMITS.maxTotalImageBytes,
  maxVisualRequestBodyBytes: LIMITS.maxVisualRequestBodyBytes,
  maxImageDimension: VISUAL_LIMITS.maxImageDimension,
  maxImagePixels: VISUAL_LIMITS.maxImagePixels,
})

/**
 * The user-facing sentence for a contract refusal caused by an attached image,
 * or `undefined` when the refusal is not an image budget.
 */
export function attachmentBudgetRefusalMessage(
  contractMessage: string,
  requestCarriesImage: boolean
): string | undefined {
  return attachmentBudgetRefusalMessageFor(
    ATTACHMENT_BUDGET_REFUSALS,
    contractMessage,
    requestCarriesImage
  )
}

function mapCodexUsage(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 CodexSubscriptionDeps = {
  authorizer: ProviderAttemptAuthorizer
  proxy: CodexLlmProxyClient
  attemptContext: (input: { model: string }) => CodexAttemptContext
}

/**
 * Pre-authorize rejections. These are known, non-retryable codes: the request
 * itself cannot succeed, so neither may trigger a retry or a provider fallback.
 */
const CODEX_REQUEST_INVALID = 'invalid_request'
/** A local image budget refusal (`ATTACHMENT_BUDGET_REFUSALS`). */
const CODEX_ATTACHMENT_TOO_LARGE = 'attachment_too_large'

function assertTerminalCodexOutcome(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) {
    // Defence in depth: codex-llm-proxy enforces the same limit first.
    throw new CodexProxyError(
      'tool_call_limit_exceeded',
      `tool calls exceed ${LIMITS.maxToolCalls}`
    )
  }
  if (result.toolCalls.length > 0 && result.outcome !== 'success') {
    throw new CodexProxyError(
      'provider_unavailable',
      'tool calls require a successful terminal outcome'
    )
  }
  if (result.outcome === 'error') {
    throw new CodexProxyError('provider_unavailable', 'proxy stream ended with an error outcome')
  }
  if (result.outcome === 'unknown' && !result.text && result.toolCalls.length === 0) {
    throw new CodexProxyError(
      'provider_unavailable',
      'proxy stream ended without a terminal outcome'
    )
  }
  // Only `success` may become a completion. Partial text from an unknown
  // terminal state or a cancellation is interrupted output: surfacing it as a
  // finished answer would let callers ack it as complete and count it as a
  // healthy call. The request was already dispatched, so keep it fenced.
  if (result.outcome === 'unknown') {
    throw new CodexProxyError(
      'outcome_unknown',
      'proxy stream ended without a successful terminal outcome'
    )
  }
  if (result.outcome === 'canceled') {
    throw new CodexProxyError(
      'canceled',
      'proxy stream was canceled before a successful terminal outcome'
    )
  }
}

export class CodexSubscriptionProvider implements SingleTurnProvider {
  getVisualDeliveryLimits(operation: ImageTransportOperation) {
    return transportSupportsImageInput('codex-subscription', operation)
      ? resolveVisualDeliveryLimits('codex-subscription')
      : null
  }
  readonly requiresImageSourceIdentity =
    descriptorFor('codex-subscription').requiresImageSourceIdentity === true
  private nextProviderAttemptIndex = 1

  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
    // Every CodexAuthorizeError throw site precedes `proxy.stream`, so an
    // authorize failure proves nothing was dispatched. A CodexProxyError 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 CodexProxyError
          ? 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 === 'tool_call_limit_exceeded') {
      // Not retryable: `retryable: true` would make this error
      // failover-eligible and enable the workflow fallback after tool
      // results, re-running the turn on another provider. The limit is a
      // contract rejection of the model output, not a provider outage.
      return {
        code: LlmErrorCode.ToolCallLimitExceeded,
        retryable: false,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    if (code === 'invalid_tool_arguments') {
      // The proxy refused a tool call whose arguments are not a JSON object.
      // Same reasoning as the limit above: the model output is invalid, and a
      // retry or failover would re-run the turn on a rejected response.
      return {
        code: LlmErrorCode.InvalidResponse,
        retryable: false,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    if (code === 'stream_duration_exceeded') {
      // Not retryable: the proxy already spent the attempt's whole stream
      // budget. A retry or a failover would spend it again on the same turn.
      return {
        code: LlmErrorCode.StreamDurationExceeded,
        retryable: false,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    if (code === CODEX_ATTACHMENT_TOO_LARGE) {
      // An attached image broke a contract image budget. A shorter
      // conversation cannot fix it and neither can another provider, so it is
      // terminal; the message already names the limit for the user.
      return {
        code: LlmErrorCode.InvalidAttachment,
        retryable: false,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    if (code === IMAGE_SOURCE_INVALID) {
      // A host producer attached an image with no usable provenance source. The
      // same messages fail the same way on every provider, so it is terminal:
      // neither a retry nor a failover can fix it. The arm is explicit so a
      // change to the generic arm below cannot make it retryable.
      return {
        code: LlmErrorCode.ApiCallFailed,
        retryable: false,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    // `payload_too_large` is the proxy's 413 for an envelope over its body
    // limit: the same size refusal of this conversation, one hop later.
    // `context_length_exceeded` is the upstream's refusal of a request over the
    // model's context window, forwarded by the proxy (#731).
    if (
      code === 'request_limit_exceeded' ||
      code === 'payload_too_large' ||
      code === 'context_length_exceeded'
    ) {
      return {
        code: LlmErrorCode.ContextLengthExceeded,
        retryable: false,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    // The proxy's 408 for a body upload over its read deadline: the upstream
    // never saw the body. Not an outage, so never retryable: a retryable class
    // would put this provider in failover cooldown for the Host's own slow
    // upload (#739).
    if (code === 'request_timeout') {
      return {
        code: LlmErrorCode.ApiCallFailed,
        retryable: false,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    // control-api's 403 for a redeem that arrived after the execution ticket's
    // `exp`, passed through by the proxy. The request waited in admission and
    // never reached the provider: a capacity race, not a defect. Retryable, so
    // the next attempt re-authorizes with a fresh ticket; the failover class is
    // `provider_unavailable`. `ticket_replayed` and `ticket_invalid` are
    // defects and stay terminal in the generic arm below (#739).
    if (code === 'ticket_expired') {
      return {
        code: LlmErrorCode.ApiCallFailed,
        retryable: true,
        message: 'execution ticket expired before redeem; re-authorize',
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    // A control-plane hop no live process answered (#720): retryable, with the
    // failover class of the overload arm below; only the label differs.
    if (code === 'control_plane_unavailable') {
      return {
        code: LlmErrorCode.ControlPlaneUnavailable,
        retryable: true,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(providerDispatched !== undefined ? { providerDispatched } : {}),
      }
    }
    // An upstream 4xx the proxy could not map (#720): the same request gets
    // the same answer, so it is terminal and has its own label.
    // httpStatus is the upstream's own status, when the proxy sent it (R1-H2).
    if (code === 'upstream_rejected') {
      const upstreamStatus = err instanceof CodexProxyError ? err.upstreamStatus : undefined
      return {
        code: LlmErrorCode.UpstreamRejected,
        retryable: false,
        message: err instanceof Error ? err.message : String(err),
        providerCode: code,
        ...(upstreamStatus !== undefined ? { httpStatus: upstreamStatus } : {}),
        ...(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)
    assertTerminalCodexOutcome(result)
    const usage = mapCodexUsage(result.usage)
    return {
      content: result.text,
      usage: usage.usage,
      usage_reported: usage.usage_reported,
      finish_reason: 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)
    assertTerminalCodexOutcome(result)
    const usage = mapCodexUsage(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 : 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', { dispatched: false })
    }
    // An over-long history is reported as a context-length failure instead of
    // a generic invalid request; it is thrown before authorize and dispatch.
    if (messages.length > LIMITS.maxMessages) {
      throw new CodexAuthorizeError(
        'request_limit_exceeded',
        `messages exceed ${LIMITS.maxMessages}`
      )
    }
    // Hash and send the validated wire projection — exactly what control-api
    // authorize and the proxy re-derive. Hashing the locally built object let
    // shapes the parser normalizes away (an empty `generation` from a
    // tool-name tool_choice, empty tools/hints) fail authorize with a
    // requestHash mismatch. An invalid request never leaves the process.
    const canonical = hashCanonicalCodexRequest(this.buildRequest(messages, tools, options))
    if (!canonical.ok) {
      // A conversation-volume refusal (bytes, element bound, message count,
      // tool-call count) is a context-length failure, not a malformed request;
      // it is thrown before authorize and dispatch so no provider attempt is
      // spent. Reported as `invalid_request` it reached the UI as "Connection
      // Error", a label that reads as transient, and invited a retry that
      // reproduced it (#731). The message-count guard above already used this
      // classification. An image budget is an attachment failure with its own
      // user-facing message. Any other `size` refusal stays
      // `payload_too_large`, which reaches the user as a context-length
      // failure.
      const attachmentRefusal =
        canonical.code === 'limit'
          ? attachmentBudgetRefusalMessage(
              canonical.message,
              messages.some(message => message.contentParts?.some(part => part.type === 'image'))
            )
          : undefined
      if (attachmentRefusal !== undefined) {
        throw new CodexAuthorizeError(CODEX_ATTACHMENT_TOO_LARGE, attachmentRefusal)
      }
      throw new CodexAuthorizeError(
        canonicalRefusalCode(canonical),
        `codex completion request rejected: ${canonical.message}`
      )
    }
    const wireRequest = canonical.value.request
    const requestHash = canonical.value.requestHash
    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 attempt = async (providerAttemptIndex: number) => {
      const authorized = await this.deps.authorizer.authorize(
        {
          request: wireRequest,
          requestHash,
          invocationId: context.invocationId ?? wireRequest.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: wireRequest,
        signal: options?.signal,
      })
      return {
        ...streamed,
        providerAttemptId: authorized.providerAttemptId,
        providerAttemptIndex,
      }
    }
    try {
      return await attempt(context.providerAttemptIndex ?? this.nextProviderAttemptIndex++)
    } catch (err) {
      // G1-9 (#720): a 429 that advised a short Retry-After is retried once,
      // after that delay, under a new authorize: a redeemed ticket cannot be
      // reused. The 429 may come from the proxy or from control-api's
      // authorize limiter (G1-11). A caller that pins the attempt index owns
      // its own retries. control-api's authorize_capacity_exceeded, refused
      // before any read, is retried once the same way (M-A, review
      // 5426789128); a proxy error of that name is not.
      const waitMs =
        context.providerAttemptIndex !== undefined
          ? undefined
          : err instanceof CodexAuthorizeError
            ? authorizeRetryDelayMs(err.code, err.retryAfterMs)
            : err instanceof CodexProxyError
              ? rateLimitRetryDelayMs(err.code, err.retryAfterMs)
              : undefined
      if (waitMs === undefined) throw err
      await waitBeforeRetry(waitMs, options?.signal)
      // The wait stops watching the signal once its timer fires: an abort in
      // that gap must not reach a second authorize (G1-12).
      options?.signal?.throwIfAborted()
      return attempt(this.nextProviderAttemptIndex++)
    }
  }

  private buildRequest(
    messages: CoreChatMessage[],
    tools: ToolDefinition[] | undefined,
    options?: { max_tokens?: number; temperature?: number; tool_choice?: string }
  ): CodexCompletionRequest {
    const projectedMessages = messages.map(message =>
      projectMessage(message, CODEX_REQUEST_INVALID)
    )
    const presentedTools =
      tools && tools.length > 0
        ? tools.map(tool => ({
            name: tool.name,
            description: tool.description,
            parameters: tool.parameters,
          }))
        : undefined
    if (presentedTools) {
      // 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: 'codex-subscription', presentedCount: presentedTools.length },
        'Tool definitions prepared for authorization'
      )
    }
    const hasGeneration =
      options?.temperature !== undefined ||
      options?.max_tokens !== undefined ||
      Boolean(options?.tool_choice)
    const base: Omit<CodexCompletionRequest, 'schemaVersion'> = {
      requestId: randomUUID(),
      idempotencyKey: randomUUID(),
      provider: 'codex-subscription' as const,
      model: this.model,
      messages: projectedMessages,
      ...(presentedTools ? { tools: presentedTools } : {}),
      ...(hasGeneration
        ? {
            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 }
                : {}),
            },
          }
        : {}),
    }
    // V1 stays byte-identical for a turn with no contentParts. One message with
    // parts, even text-only parts left by redaction, moves the whole request to
    // V2, the only version that carries them.
    if (!projectedMessages.some(message => message.contentParts !== undefined)) {
      return { schemaVersion: 'codex-completion-request.v1', ...base }
    }
    return { schemaVersion: 'codex-completion-request.v2', ...base }
  }
}