Skip to content

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

TypeScript
39.8 KB
Raw Blame
import {
  type CodexCompletionRequest,
  LIMITS,
  hashCodexCompletionRequest,
  parseCodexCompletionRequest,
} from '@clerum/llm-provider-attempt-contract'
import { chatgptUpstreamHeaders } from './chatgptUpstreamHeaders.js'
import {
  type FinalizeAttemptSuccess,
  type RedeemAttemptSuccess,
  fetchCauseCode,
} from './controlApiClient.js'
import { logger } from './logger.js'
import {
  CODEX_CATALOG_ORIGIN,
  CODEX_COMPLETIONS_ORIGIN,
  OriginDeniedError,
  type OriginPolicyOptions,
  assertAllowedUpstreamUrl,
  fetchFrozenOrigin,
} from './originPolicy.js'
import { assertBoundedDeadline, assertBoundedIdleTimeout } from './requestLimits.js'
import { ToolNameMap } from './toolNameMap.js'
import { type SafeUsage, parseSafeUsage } from './usage.js'

export type StreamFrame =
  | { type: 'text'; text: string }
  | { type: 'tool_call'; id: string; name: string; arguments: Record<string, unknown> }

/**
 * Receives mapped frames. Returning a promise signals client backpressure: the
 * SSE reader stops pulling upstream bytes until it settles (or the stream
 * aborts), so a slow consumer cannot make the proxy buffer an unbounded stream.
 */
export type FrameSink = (frame: StreamFrame) => void | Promise<void>

export type TransportTicket = {
  jti: string
  hostRef: string
  model: string
  requestHash: string
  providerAttemptId: string
}

export class CodexTransportError extends Error {
  constructor(
    readonly code: string,
    message: string,
    readonly details?: Readonly<Record<string, number | string>>,
    options?: ErrorOptions
  ) {
    super(message, options)
    this.name = 'CodexTransportError'
  }
}

/**
 * Review R3-L1/R4-L1: a rejected undici fetch and a failed dns.lookup wrapped
 * by origin policy both carry a code-shaped cause. It becomes a mapped
 * transport error that keeps only the cause code, so the attempt line logs
 * `causeCode` and never the error itself. An error with no code-shaped cause
 * is returned undefined and stays unmapped, which logs it as a handler defect.
 */
function upstreamFetchFailure(err: unknown): CodexTransportError | undefined {
  const code = fetchCauseCode(err)
  if (code === undefined) return undefined
  return new CodexTransportError('provider_unavailable', 'upstream fetch failed', undefined, {
    cause: { code },
  })
}

/**
 * The proxy cut the upstream stream on one of its two bounds. The wire code
 * stays that of CodexTransportError (`provider_unavailable` for idle silence,
 * `stream_duration_exceeded` for the total cap); `kind` only labels the metric.
 */
export class UpstreamTimeoutError extends CodexTransportError {
  constructor(
    readonly kind: 'idle' | 'total',
    code: string,
    message: string,
    details: Readonly<Record<string, number | string>>
  ) {
    super(code, message, details)
    this.name = 'UpstreamTimeoutError'
  }
}

export type StreamCodexCompletionInput = {
  executionTicket: string
  requestHash: string
  request: unknown
  ticket: TransportTicket
  deadlineMs?: number
  maxDeadlineMs: number
  /** Lowers `STREAM_LIMITS.upstreamIdleTimeoutMs`; never raises it. */
  upstreamIdleTimeoutMs?: number
  signal?: AbortSignal
  redeem: (input: {
    executionTicket: string
    requestHash: string
    model: string
    hostRef: string
    operation: 'completion_stream'
  }) => Promise<RedeemAttemptSuccess>
  /**
   * Called once, after the redeem succeeded and its served model and deadline
   * were accepted, and before the upstream fetch. The server starts its SSE
   * heartbeat here, so a denied redeem still answers with an HTTP status.
   */
  onRedeemed?: () => void
  /**
   * #739 D2 — called once, as soon as the upstream fetch resolved and before
   * its status is inspected: the whole request body has been written by then,
   * whatever the answer. The server releases the body's budget reservation
   * here. Not called when the fetch rejects or never resolves.
   */
  onUpstreamAccepted?: () => void
  finalize: (input: {
    attemptReceipt: string
    receipt: {
      schemaVersion: 'codex-attempt-receipt.v1'
      providerAttemptId: string
      requestHash: string
      outcome: 'success' | 'canceled' | 'error' | 'unknown'
      usage?: SafeUsage
    }
  }) => Promise<FinalizeAttemptSuccess>
  fetchFn: typeof fetch
  lookup?: OriginPolicyOptions['lookup']
  onFrame?: FrameSink
}

export type StreamCodexCompletionResult = {
  outcome: 'success' | 'canceled' | 'error' | 'unknown'
  usage?: SafeUsage
}

/**
 * The validated request, handed from the pre-dispatch checks to the upstream
 * write. It is emptied as soon as the upstream body is built, so a live stream
 * never keeps the parsed tree (up to LIMITS.maxRequestElements values) alive.
 */
type HeldRequest = { request: CodexCompletionRequest | undefined; requestId: string }

/**
 * Every check that needs the whole request, in a synchronous function: its
 * locals end with the call, and only the model, the bounded deadline and the
 * holder survive into the long-lived async frame of the stream.
 */
function prepareCodexCompletion(input: StreamCodexCompletionInput): {
  held: HeldRequest
  model: string
  boundedDeadlineMs: number
} {
  const parsed = parseCodexCompletionRequest(input.request)
  if (!parsed.ok) {
    throw new CodexTransportError(
      parsed.kind === 'size' ? 'payload_too_large' : 'invalid_request',
      parsed.message
    )
  }
  const request = parsed.value
  if (request.schemaVersion === 'codex-completion-request.v2' && input.deadlineMs !== undefined) {
    throw new CodexTransportError(
      'invalid_request',
      'Visual request deadlines must be inside the authorized request'
    )
  }
  const digest = hashCodexCompletionRequest(request)
  if (digest !== input.requestHash || input.ticket.requestHash !== input.requestHash) {
    throw new CodexTransportError('request_hash_mismatch', 'request hash does not match the ticket')
  }
  if (request.model !== input.ticket.model) {
    throw new CodexTransportError('model_not_allowed', 'request model does not match the ticket')
  }
  // The redeem consumes the single-use ticket, so a deadline that cannot be
  // served is refused first, while there is no receipt to finalize.
  const boundedDeadlineMs = assertBoundedDeadline(
    input.deadlineMs ?? request.deadlineMs,
    input.maxDeadlineMs
  )
  return {
    held: { request, requestId: request.requestId },
    model: request.model,
    boundedDeadlineMs,
  }
}

export async function streamCodexCompletion(
  input: StreamCodexCompletionInput
): Promise<StreamCodexCompletionResult> {
  const { held, model, boundedDeadlineMs } = prepareCodexCompletion(input)
  // A client that disconnected before dispatch must not consume the ticket:
  // nothing was redeemed, so there is no attempt receipt to finalize.
  if (input.signal?.aborted) {
    return { outcome: 'canceled' }
  }
  const redeemed = await input.redeem({
    executionTicket: input.executionTicket,
    requestHash: input.requestHash,
    model,
    hostRef: input.ticket.hostRef,
    operation: 'completion_stream',
  })
  if (redeemed.transport.servedModel !== model) {
    await finalizeQuietly(input, redeemed, 'error')
    throw new CodexTransportError('model_not_allowed', 'served model does not match the request')
  }
  const deadlineMs = Math.min(boundedDeadlineMs, redeemed.transport.maxStreamDurationMs)
  const idleTimeoutMs = assertBoundedIdleTimeout(input.upstreamIdleTimeoutMs)
  input.onRedeemed?.()

  const accessToken = redeemed.accessToken
  let outcome: StreamCodexCompletionResult['outcome'] = 'unknown'
  let usage: SafeUsage | undefined
  const started = Date.now()
  try {
    const streamed = await readUpstreamStream({
      held,
      accessToken,
      chatgptAccountId: redeemed.chatgptAccountId,
      deadlineMs,
      idleTimeoutMs,
      signal: input.signal,
      fetchFn: input.fetchFn,
      lookup: input.lookup,
      onFrame: input.onFrame,
      onUpstreamAccepted: input.onUpstreamAccepted,
    })
    outcome = streamed.outcome
    usage = streamed.usage
    return { outcome, usage }
  } catch (err) {
    if (input.signal?.aborted || (err instanceof DOMException && err.name === 'AbortError')) {
      outcome = 'canceled'
      return { outcome, usage }
    }
    if (err instanceof OriginDeniedError) {
      outcome = 'error'
      throw new CodexTransportError('origin_denied', err.message)
    }
    if (err instanceof CodexTransportError) {
      outcome = 'error'
      throw err
    }
    outcome = 'error'
    throw upstreamFetchFailure(err) ?? err
  } finally {
    void accessToken
    await finalizeQuietly(input, redeemed, outcome, usage)
    logger.info(
      {
        event: 'codex_proxy_attempt_closed',
        outcome,
        durationMs: Date.now() - started,
      },
      'codex stream finalized'
    )
  }
}

async function finalizeQuietly(
  input: StreamCodexCompletionInput,
  redeemed: RedeemAttemptSuccess,
  outcome: StreamCodexCompletionResult['outcome'],
  usage?: SafeUsage
): Promise<void> {
  const payload = {
    attemptReceipt: redeemed.attemptReceipt,
    receipt: {
      schemaVersion: 'codex-attempt-receipt.v1' as const,
      providerAttemptId: input.ticket.providerAttemptId,
      requestHash: input.requestHash,
      outcome,
      ...(usage ? { usage } : {}),
    },
  }
  try {
    await input.finalize(payload)
  } catch {
    try {
      await input.finalize(payload)
    } catch (err) {
      logger.error({ event: 'codex_proxy_finalize_failed', err }, 'finalize retry exhausted')
    }
  }
}

async function readUpstreamStream(input: {
  held: HeldRequest
  accessToken: string
  chatgptAccountId?: string
  deadlineMs: number
  idleTimeoutMs: number
  signal?: AbortSignal
  fetchFn: typeof fetch
  lookup?: OriginPolicyOptions['lookup']
  onFrame?: FrameSink
  onUpstreamAccepted?: () => void
}): Promise<StreamCodexCompletionResult> {
  const deadline = new UpstreamDeadline(input.deadlineMs, input.idleTimeoutMs)
  try {
    return await dispatchUpstreamStream(input, deadline)
  } finally {
    deadline.clear()
  }
}

/**
 * Two upstream bounds, each aborting with its own typed reason. The total
 * bound runs from dispatch to the end of the stream. The idle bound runs only
 * while the proxy waits on the upstream (response headers or the next chunk),
 * so a client that is slow to drain frames never counts as upstream silence.
 */
class UpstreamDeadline {
  private readonly controller = new AbortController()
  private readonly started = Date.now()
  private readonly total: ReturnType<typeof setTimeout>
  private idle: ReturnType<typeof setTimeout> | undefined

  constructor(
    private readonly totalMs: number,
    private readonly idleMs: number
  ) {
    this.total = setTimeout(() => {
      this.controller.abort(
        new UpstreamTimeoutError(
          'total',
          'stream_duration_exceeded',
          'upstream stream exceeded maxStreamDurationMs',
          { limitMs: this.totalMs, elapsedMs: Date.now() - this.started }
        )
      )
    }, totalMs)
  }

  get signal(): AbortSignal {
    return this.controller.signal
  }

  /**
   * Wait on one upstream operation under the idle timeout. The wait also ends
   * as soon as `signal` aborts, rejecting with its reason, because the
   * operation itself may not observe the signal (a stalled body read).
   */
  async waitUpstream<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
    signal.throwIfAborted()
    this.idle = setTimeout(() => {
      this.controller.abort(
        new UpstreamTimeoutError('idle', 'provider_unavailable', 'upstream stream idle timeout', {
          idleTimeoutMs: this.idleMs,
          elapsedMs: Date.now() - this.started,
        })
      )
    }, this.idleMs)
    let onAbort: (() => void) | undefined
    const aborted = new Promise<never>((_, reject) => {
      onAbort = () => reject(signal.reason)
      signal.addEventListener('abort', onAbort, { once: true })
    })
    try {
      return await Promise.race([operation, aborted])
    } finally {
      clearTimeout(this.idle)
      this.idle = undefined
      if (onAbort) signal.removeEventListener('abort', onAbort)
    }
  }

  clear(): void {
    clearTimeout(this.total)
    if (this.idle !== undefined) clearTimeout(this.idle)
  }
}

/**
 * Serialize the upstream body and empty the holder. Synchronous, so the tree
 * and the intermediate payload are unreachable once it returns; only the
 * serialized string and the tool-name map outlive the call.
 */
function buildUpstreamBody(held: HeldRequest): { names: ToolNameMap; body: string } {
  const request = held.request
  if (!request) throw new Error('the upstream request was already released')
  const names = new ToolNameMap([
    ...(request.tools ?? []).map(tool => tool.name),
    ...request.messages.flatMap(message =>
      message.role === 'assistant' ? (message.toolCalls ?? []).map(call => call.name) : []
    ),
  ])
  const body = JSON.stringify(toUpstreamPayload(request, names))
  held.request = undefined
  return { names, body }
}

async function dispatchUpstreamStream(
  input: Parameters<typeof readUpstreamStream>[0],
  deadline: UpstreamDeadline
): Promise<StreamCodexCompletionResult> {
  const url = assertAllowedUpstreamUrl(CODEX_COMPLETIONS_ORIGIN, 'completions')
  const signal = input.signal ? AbortSignal.any([input.signal, deadline.signal]) : deadline.signal
  const headers = chatgptUpstreamHeaders(input.accessToken, {
    'content-type': 'application/json',
    accept: 'text/event-stream',
    session_id: input.held.requestId,
    ...(input.chatgptAccountId ? { 'chatgpt-account-id': input.chatgptAccountId } : {}),
  })
  if (!headers['chatgpt-account-id']) {
    throw new CodexTransportError(
      'connection_unavailable',
      'Codex access token is missing ChatGPT account id'
    )
  }
  const { names, body } = buildUpstreamBody(input.held)
  const response = await deadline.waitUpstream(
    fetchFrozenOrigin({
      url,
      fetchFn: input.fetchFn,
      lookup: input.lookup,
      init: {
        method: 'POST',
        signal,
        headers,
        body,
      },
    }),
    signal
  )
  input.onUpstreamAccepted?.()
  if (!response.ok || !response.body) {
    const credentialRejected = response.status === 401 || response.status === 403
    const errorBody =
      response.ok || credentialRejected
        ? { read: 'skipped' as const }
        : await readUpstreamErrorBody(response)
    logger.warn(
      {
        event: 'codex_upstream_http',
        operation: 'completion_stream',
        status: response.status,
        accountHeader: Boolean(headers['chatgpt-account-id']),
        errorBody: errorBody.read,
      },
      'Codex completions upstream returned a non-success status'
    )
    if (errorBody.read === 'parsed' && errorBody.code === CONTEXT_LENGTH_EXCEEDED) {
      throw new CodexTransportError('context_length_exceeded', 'upstream context window exceeded')
    }
    if (response.status === 400) {
      throw new CodexTransportError('invalid_request', 'upstream rejected the Codex request')
    }
    if (credentialRejected) {
      throw new CodexTransportError(
        'connection_unavailable',
        'upstream rejected the Codex credential'
      )
    }
    if (response.status === 429) {
      const retryAfter = retryAfterSeconds(response)
      throw new CodexTransportError(
        'rate_limited',
        'upstream rate limited the Codex request',
        retryAfter === undefined ? undefined : { retryAfterSeconds: retryAfter }
      )
    }
    // G1-3 (#720): any other 4xx is what the same request would get again, so
    // it is not retried or failed over from. A 408 is transient.
    if (response.status >= 400 && response.status < 500 && response.status !== 408) {
      throw new CodexTransportError(
        'upstream_rejected',
        `upstream rejected the Codex request with status ${response.status}`,
        { upstreamStatus: response.status }
      )
    }
    throw new CodexTransportError('provider_unavailable', 'upstream completion failed')
  }
  return consumeSse(response.body, input.onFrame, signal, names, deadline)
}

// G1-1 (#720): Retry-After is forwarded only as whole seconds in 1..3600, the
// rule mcp-host's gfsClient applies. An HTTP date or any other value is absent.
// mcp-host parses what this forwards with its own copy of the rule
// (`retryAfterMs` in mcp-host/src/llm/retryAfter.ts), and the Grok proxy has a
// third (#799); a change here goes to both, or the Host drops the retry.
const MAX_RETRY_AFTER_SECONDS = 3600

function retryAfterSeconds(response: Response): number | undefined {
  const raw = response.headers.get('retry-after')?.trim()
  if (raw === undefined || !/^[1-9][0-9]{0,3}$/.test(raw)) return undefined
  const seconds = Number(raw)
  return seconds <= MAX_RETRY_AFTER_SECONDS ? seconds : undefined
}

// R9-6: a non-success completion body is read only to find a context-window
// refusal. The recorded refusal object is well under 1 KiB; past this bound the
// body is cancelled and the status mapping stands.
const UPSTREAM_ERROR_BODY_MAX_BYTES = 16 * 1024

// `read` is a closed set that is safe to log; no upstream text leaves here.
type UpstreamErrorBody =
  | { read: 'skipped' | 'absent' | 'oversize' | 'unreadable' | 'unparsable' }
  | { read: 'parsed'; code: string | undefined }

async function readUpstreamErrorBody(response: Response): Promise<UpstreamErrorBody> {
  if (!response.body) return { read: 'absent' }
  const reader = response.body.getReader()
  const chunks: Uint8Array[] = []
  let total = 0
  try {
    for (;;) {
      const { done, value } = await reader.read()
      if (done) break
      total += value.byteLength
      if (total > UPSTREAM_ERROR_BODY_MAX_BYTES) {
        await reader.cancel().catch(() => undefined)
        return { read: 'oversize' }
      }
      chunks.push(value)
    }
  } catch {
    await reader.cancel().catch(() => undefined)
    return { read: 'unreadable' }
  }
  let parsed: unknown
  try {
    parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'))
  } catch {
    return { read: 'unparsable' }
  }
  return { read: 'parsed', code: isPlainObject(parsed) ? upstreamFailureCode(parsed) : undefined }
}

function toUpstreamPayload(
  request: CodexCompletionRequest,
  names: ToolNameMap
): Record<string, unknown> {
  const instructions = request.messages
    .filter(message => message.role === 'system' && message.content.trim())
    .map(message => message.content)
    .join('\n\n')
  const input: Record<string, unknown>[] = []
  for (const message of request.messages) {
    if (message.role === 'system') continue
    if (message.role === 'tool') {
      input.push({
        type: 'function_call_output',
        call_id: message.toolCallId || message.name || 'tool',
        output: message.content,
      })
      continue
    }
    if (message.role === 'assistant' && message.toolCalls && message.toolCalls.length > 0) {
      if (message.content.trim()) {
        input.push({ role: 'assistant', content: message.content })
      }
      for (const call of message.toolCalls) {
        input.push({
          type: 'function_call',
          call_id: call.id,
          name: names.toWire(call.name),
          arguments: JSON.stringify(call.arguments ?? {}),
        })
      }
      continue
    }
    if ('contentParts' in message && message.contentParts) {
      // Responses content items, not Chat Completions image_url objects.
      // Provenance remains bound by the local hash and never becomes model text.
      input.push({
        role: message.role,
        content: message.contentParts.map(part =>
          part.type === 'text'
            ? { type: 'input_text', text: part.text }
            : {
                type: 'input_image',
                image_url: `data:${part.mimeType};base64,${part.data}`,
                detail: 'high',
              }
        ),
      })
    } else {
      input.push({ role: message.role, content: message.content })
    }
  }
  const payload: Record<string, unknown> = {
    model: request.model,
    stream: true,
    store: false,
    input,
  }
  if (instructions) payload.instructions = instructions
  if (request.tools && request.tools.length > 0) {
    payload.tools = request.tools.map(tool => ({
      type: 'function',
      name: names.toWire(tool.name),
      description: tool.description,
      parameters: tool.parameters,
      // Codex can normalize omission to strict mode and require optional MCP
      // fields. Preserve the source schema's optionality explicitly.
      strict: false,
    }))
    payload.parallel_tool_calls = true
  }
  // ChatGPT `/codex/responses` rejects sampling fields that Chat Completions
  // treats as portable. Keep them on CodexCompletionRequestV1 (authorize hash)
  // and omit them on the upstream wire. The CLI Codex client also omits
  // max_output_tokens / temperature. The authorize hash still carries
  // generation.maxOutputTokens as request identity; this wire cannot enforce
  // that cap. Do not restore the fields here.
  if (request.generation?.toolChoice) {
    payload.tool_choice = request.generation.toolChoice
  }
  if (request.transportHints?.promptCacheKey) {
    payload.prompt_cache_key = request.transportHints.promptCacheKey
  }
  return payload
}

// The one upstream failure code forwarded to the Host. A context-window refusal
// is a property of this request, so retrying it cannot succeed (#731). Every
// other upstream code stays `provider_unavailable`: an upstream string never
// becomes a Host-visible code by itself.
const CONTEXT_LENGTH_EXCEEDED = 'context_length_exceeded'

async function consumeSse(
  body: ReadableStream<Uint8Array>,
  onFrame: FrameSink | undefined,
  signal: AbortSignal,
  names: ToolNameMap,
  deadline: UpstreamDeadline
): Promise<StreamCodexCompletionResult> {
  const reader = body.getReader()
  const decoder = new TextDecoder()
  const pending = new Map<string, PendingToolCall>()
  // Text stays streaming. Calls become executable only once the entire
  // response succeeds and its independent call budget has been validated.
  const toolFrames: Array<Extract<StreamFrame, { type: 'tool_call' }>> = []
  const acceptFrame = async (frame?: StreamFrame): Promise<void> => {
    if (pending.size > LIMITS.maxToolCalls) {
      throw new CodexTransportError(
        'tool_call_limit_exceeded',
        `tool calls exceed ${LIMITS.maxToolCalls}`,
        { limit: LIMITS.maxToolCalls, observed: pending.size }
      )
    }
    if (frame?.type === 'tool_call') {
      if (toolFrames.length >= LIMITS.maxToolCalls) {
        throw new CodexTransportError(
          'tool_call_limit_exceeded',
          `tool calls exceed ${LIMITS.maxToolCalls}`,
          { limit: LIMITS.maxToolCalls, observed: toolFrames.length + 1 }
        )
      }
      const canonicalName = names.fromWire(frame.name)
      if (canonicalName === undefined) {
        throw new CodexTransportError(
          'provider_unavailable',
          'upstream returned an unknown tool name'
        )
      }
      toolFrames.push({ ...frame, name: canonicalName })
    } else if (frame) await deliverFrame(onFrame, frame, signal)
  }
  let buffer = ''
  let completed = false
  let failed = false
  let contextLengthExceeded = false
  let usage: SafeUsage | undefined
  const maxSseBufferBytes = 1_048_576
  try {
    // An abort ends the read with the signal's reason: the caller's own abort
    // becomes `canceled`, a deadline abort surfaces as its typed error.
    for (;;) {
      const { done, value } = await deadline.waitUpstream(reader.read(), signal)
      if (done) break
      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, '\n').replace(/\r/g, '\n')
      if (buffer.length > maxSseBufferBytes) {
        throw new CodexTransportError('sse_buffer_exceeded', 'upstream SSE buffer exceeded')
      }
      const parts = buffer.split('\n\n')
      buffer = parts.pop() ?? ''
      for (const part of parts) {
        const mapped = ingestSseBlock(part, pending)
        await acceptFrame(mapped.frame)
        if (mapped.usage) usage = mapped.usage
        if (mapped.completed) completed = true
        if (mapped.failed) failed = true
        if (mapped.failureCode === CONTEXT_LENGTH_EXCEEDED) contextLengthExceeded = true
      }
      signal.throwIfAborted()
    }
    buffer += decoder.decode().replace(/\r\n/g, '\n').replace(/\r/g, '\n')
    if (buffer.trim()) {
      const mapped = ingestSseBlock(buffer, pending)
      await acceptFrame(mapped.frame)
      if (mapped.usage) usage = mapped.usage
      if (mapped.completed) completed = true
      if (mapped.failed) failed = true
      if (mapped.failureCode === CONTEXT_LENGTH_EXCEEDED) contextLengthExceeded = true
    }
  } catch (error) {
    await reader.cancel().catch(() => undefined)
    throw error
  } finally {
    try {
      reader.releaseLock()
    } catch {
      // A read that lost the race to an abort may still hold the lock after cancel.
    }
  }
  // A canceled or failed stream leaves its open call truncated; report the
  // stream's outcome before the flush can refuse those arguments. A deadline
  // abort carries its typed UpstreamTimeoutError as the signal reason, so
  // throwing the reason surfaces stream_duration_exceeded or
  // provider_unavailable to the route instead of a plain cancel.
  signal.throwIfAborted()
  if (failed) {
    if (contextLengthExceeded) {
      throw new CodexTransportError('context_length_exceeded', 'upstream context window exceeded')
    }
    throw new CodexTransportError('provider_unavailable', 'upstream response failed')
  }
  for (const call of pending.values()) {
    if (call.emitted) continue
    // R17-1: a stream with no terminal event delivers none of its calls, so
    // an open call there keeps dev's name and count checks but its arguments
    // are not parsed, and the attempt stays `unknown`. Refusing them would
    // report a dropped connection as a malformed model response.
    const args = completed ? parseToolArguments(call.arguments, { closed: false }) : {}
    await acceptFrame({ type: 'tool_call', id: call.id, name: call.name, arguments: args })
    call.emitted = true
  }
  if (completed) {
    for (const frame of toolFrames) await deliverFrame(onFrame, frame, signal)
    return { outcome: 'success', usage }
  }
  return { outcome: 'unknown', usage }
}

async function deliverFrame(
  onFrame: FrameSink | undefined,
  frame: StreamFrame,
  signal: AbortSignal
): Promise<void> {
  const pending: unknown = onFrame?.(frame)
  // Only a thenable signals backpressure; a `void` callback may return anything.
  if (!(pending instanceof Promise) || signal.aborted) return
  await new Promise<void>((resolve, reject) => {
    const onAbort = () => resolve()
    signal.addEventListener('abort', onAbort, { once: true })
    pending.then(
      () => {
        signal.removeEventListener('abort', onAbort)
        resolve()
      },
      err => {
        signal.removeEventListener('abort', onAbort)
        reject(err)
      }
    )
  })
}

function ingestSseBlock(
  part: string,
  pending: Map<string, PendingToolCall>
): ReturnType<typeof mapUpstreamEvent> {
  const dataLine = part
    .split('\n')
    .map(line => line.trim())
    .find(line => line.startsWith('data:'))
  if (!dataLine) return {}
  const payload = dataLine.slice(5).trim()
  if (!payload || payload === '[DONE]') return {}
  let event: unknown
  try {
    event = JSON.parse(payload)
  } catch {
    // An unparseable frame is upstream noise and the stream continues. Only
    // `JSON.parse` may be swallowed here: mapping the event can refuse the
    // response over its tool-call arguments, and that refusal has to reach
    // `consumeSse` instead of being read as an empty frame.
    return {}
  }
  return mapUpstreamEvent(event, pending)
}

type PendingToolCall = {
  id: string
  name: string
  arguments: string
  emitted: boolean
}

function mapUpstreamEvent(
  event: unknown,
  pending: Map<string, PendingToolCall>
): {
  frame?: StreamFrame
  usage?: SafeUsage
  completed?: boolean
  failed?: boolean
  failureCode?: string
} {
  if (!event || typeof event !== 'object') return {}
  const row = event as Record<string, unknown>
  const type = String(row.type || '')
  if (type === 'response.output_text.delta' && typeof row.delta === 'string') {
    return { frame: { type: 'text', text: row.delta } }
  }
  if (
    type === 'response.output_item.added' &&
    isPlainObject(row.item) &&
    row.item.type === 'function_call'
  ) {
    const call = upsertPendingTool(pending, row.item)
    if (isCompleteJson(call.arguments)) return { frame: emitToolCall(call, { closed: false }) }
    return {}
  }
  if (type === 'response.function_call_arguments.delta') {
    upsertPendingTool(pending, {
      id: row.item_id,
      item_id: row.item_id,
      arguments: typeof row.delta === 'string' ? row.delta : '',
      append: true,
    })
    return {}
  }
  if (
    type === 'response.function_call_arguments.done' ||
    (type === 'response.output_item.done' &&
      isPlainObject(row.item) &&
      row.item.type === 'function_call')
  ) {
    const source = isPlainObject(row.item) ? row.item : row
    const call = upsertPendingTool(pending, source)
    if (call && !call.emitted) return { frame: emitToolCall(call, { closed: true }) }
    return {}
  }
  if (type === 'response.completed') {
    const response = isPlainObject(row.response) ? row.response : row
    return { completed: true, usage: parseSafeUsage(response.usage) }
  }
  if (type === 'response.failed' || type === 'response.incomplete' || type === 'error') {
    return { failed: true, failureCode: upstreamFailureCode(row) }
  }
  return {}
}

// The upstream puts the code on `error.code` for an `error` event and on
// `response.error.code` for `response.failed` / `response.incomplete`.
function upstreamFailureCode(row: Record<string, unknown>): string | undefined {
  const response = isPlainObject(row.response) ? row.response : undefined
  const error = isPlainObject(row.error)
    ? row.error
    : response && isPlainObject(response.error)
      ? response.error
      : undefined
  return typeof error?.code === 'string' ? error.code : undefined
}

function upsertPendingTool(
  pending: Map<string, PendingToolCall>,
  source: Record<string, unknown> & { append?: boolean }
): PendingToolCall {
  const key = String(source.item_id || source.id || source.call_id || 'tool')
  const current =
    pending.get(key) ??
    ({
      id: String(source.call_id || source.id || key),
      name: 'tool',
      arguments: '',
      emitted: false,
    } satisfies PendingToolCall)
  if (typeof source.call_id === 'string' && source.call_id.trim()) current.id = source.call_id
  if (typeof source.name === 'string' && source.name.trim()) current.name = source.name
  const rawArgs = source.arguments
  if (typeof rawArgs === 'string') {
    // A closing event with empty or whitespace-only arguments carries nothing
    // new; it must not replace the buffer the deltas built, truncated or not.
    current.arguments = source.append
      ? `${current.arguments}${rawArgs}`
      : rawArgs.trim()
        ? rawArgs
        : current.arguments
  } else if (isPlainObject(rawArgs) && !source.append) {
    current.arguments = JSON.stringify(rawArgs)
  }
  pending.set(key, current)
  return current
}

// `closed` is true only when the upstream closed the item with
// `response.output_item.done` or `response.function_call_arguments.done`.
function emitToolCall(call: PendingToolCall, options: { closed: boolean }): StreamFrame {
  call.emitted = true
  return {
    type: 'tool_call',
    id: call.id,
    name: call.name,
    arguments: parseToolArguments(call.arguments, options),
  }
}

function isCompleteJson(raw: string): boolean {
  const trimmed = raw.trim()
  if (!trimmed) return false
  try {
    JSON.parse(trimmed)
    return true
  } catch {
    return false
  }
}

// A call runs with exactly the arguments the model produced. Arguments that are
// not a JSON object (truncated or a non-object value) refuse the whole response
// instead of executing the tool with `{}`. Empty or whitespace-only arguments
// on a call the upstream closed are a call without parameters, read as `{}`;
// the Host still validates `{}` against the tool's schema. Empty arguments on
// a call that was never closed are refused, because nothing says the call was
// complete.
function parseToolArguments(raw: string, options: { closed: boolean }): Record<string, unknown> {
  if (options.closed && raw.trim() === '') return {}
  let parsed: unknown
  try {
    parsed = JSON.parse(raw)
  } catch {
    throw new CodexTransportError(
      'invalid_tool_arguments',
      'upstream tool call arguments are not valid JSON'
    )
  }
  if (!isPlainObject(parsed)) {
    throw new CodexTransportError(
      'invalid_tool_arguments',
      'upstream tool call arguments are not a JSON object'
    )
  }
  return parsed
}

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && Array.isArray(value) === false
}

/**
 * Bounds for the admin catalog/test upstream call: a hard deadline covering
 * headers and body, a streamed body cap, and normalized-model caps aligned
 * with control-api's catalog sync limits.
 */
export const CATALOG_LIMITS = {
  timeoutMs: 15_000,
  // Live ChatGPT catalog rows can carry per-model instruction payloads and the
  // production size is unmeasured; keep generous headroom over the Grok cap.
  maxBodyBytes: 8 * 1_048_576,
  maxModels: 256,
  maxModelIdLength: 128,
  // A longer display name is omitted, never truncated: a stored name is
  // always one the upstream sent.
  maxDisplayNameLength: 256,
  // control-api stores the window in a Postgres INTEGER column; a larger value
  // would fail the whole catalog sync, so it is omitted here instead.
  maxContextWindowTokens: 2_147_483_647,
} as const

type CatalogModel = { model: string; displayName?: string; contextWindowTokens?: number }

/**
 * The row's display name by precedence: the camelCase and `title` spellings
 * first, then the `display_name` the Codex catalog sends, then `name`.
 */
function displayNameOf(row: Record<string, unknown>): string | undefined {
  for (const value of [row.displayName, row.title, row.display_name, row.name]) {
    if (typeof value === 'string') return value
  }
  return undefined
}

/**
 * The upstream row's `context_window`, when it is a positive integer the
 * catalog store can hold. `max_context_window` is an opt-in extension, not the
 * window a request gets, so it is not read.
 */
function contextWindowOf(row: Record<string, unknown>): number | undefined {
  const value = row.context_window
  return typeof value === 'number' &&
    Number.isInteger(value) &&
    value > 0 &&
    value <= CATALOG_LIMITS.maxContextWindowTokens
    ? value
    : undefined
}

export async function listCodexModels(input: {
  accessToken: string
  fetchFn: typeof fetch
  lookup?: OriginPolicyOptions['lookup']
  /** Test seam; production uses CATALOG_LIMITS.timeoutMs. */
  timeoutMs?: number
}): Promise<{
  outcome: 'ready' | 'auth-rejected' | 'unavailable'
  models: CatalogModel[]
}> {
  const url = assertAllowedUpstreamUrl(CODEX_CATALOG_ORIGIN, 'catalog')
  const headers = chatgptUpstreamHeaders(input.accessToken, { accept: 'application/json' })
  const signal = AbortSignal.timeout(input.timeoutMs ?? CATALOG_LIMITS.timeoutMs)
  let response: Response
  try {
    response = await fetchFrozenOrigin({
      url,
      fetchFn: input.fetchFn,
      lookup: input.lookup,
      init: {
        method: 'GET',
        headers,
        signal,
      },
    })
  } catch (err) {
    if (signal.aborted) throw catalogTimeoutError()
    throw catalogFetchFailure(err)
  }
  if (response.status === 401 || response.status === 403)
    return { outcome: 'auth-rejected', models: [] }
  if (!response.ok) {
    logger.warn(
      {
        event: 'codex_catalog_upstream',
        status: response.status,
        accountHeader: Boolean(headers['chatgpt-account-id']),
      },
      'Codex catalog upstream returned a non-success status'
    )
    return { outcome: 'unavailable', models: [] }
  }
  const raw = await readBoundedCatalogBody(response, signal)
  let body: unknown
  try {
    body = JSON.parse(raw)
  } catch {
    logger.warn(
      { event: 'codex_catalog_upstream', reason: 'invalid_json' },
      'Codex catalog upstream returned a body that is not JSON'
    )
    throw new CodexTransportError('provider_unavailable', 'catalog upstream body is not JSON')
  }
  return { outcome: 'ready', models: normalizeModels(body) }
}

export async function testCodexConnection(input: {
  accessToken: string
  fetchFn: typeof fetch
  lookup?: OriginPolicyOptions['lookup']
  timeoutMs?: number
}): Promise<{ outcome: 'ready' | 'auth-rejected' | 'unavailable' }> {
  const listed = await listCodexModels(input)
  return { outcome: listed.outcome }
}

function normalizeModels(body: unknown): CatalogModel[] {
  const rows = Array.isArray(body)
    ? body
    : isPlainObject(body) && Array.isArray(body.models)
      ? body.models
      : isPlainObject(body) && Array.isArray(body.data)
        ? body.data
        : []
  const models: CatalogModel[] = []
  let droppedOverlongIds = 0
  let droppedOverLimit = 0
  let omittedOverlongDisplayNames = 0
  for (const row of rows) {
    if (!isPlainObject(row)) continue
    const model = String(row.model || row.slug || row.id || '').trim()
    if (!model) continue
    if (model.length > CATALOG_LIMITS.maxModelIdLength) {
      droppedOverlongIds += 1
      continue
    }
    if (models.length >= CATALOG_LIMITS.maxModels) {
      droppedOverLimit += 1
      continue
    }
    let displayName = displayNameOf(row)
    if (displayName !== undefined && displayName.length > CATALOG_LIMITS.maxDisplayNameLength) {
      omittedOverlongDisplayNames += 1
      displayName = undefined
    }
    const contextWindowTokens = contextWindowOf(row)
    models.push({
      model,
      ...(displayName ? { displayName } : {}),
      ...(contextWindowTokens !== undefined ? { contextWindowTokens } : {}),
    })
  }
  if (droppedOverlongIds > 0 || droppedOverLimit > 0 || omittedOverlongDisplayNames > 0) {
    logger.warn(
      {
        event: 'codex_catalog_bounded',
        received: rows.length,
        accepted: models.length,
        droppedOverlongIds,
        droppedOverLimit,
        omittedOverlongDisplayNames,
      },
      'Codex catalog response exceeded proxy bounds'
    )
  }
  return models
}

// Review R3-L9: the admin route answers a catalog failure with a refusal line
// that carries only the code, so the cause code of a failed fetch is logged
// here before the mapped error is thrown.
function catalogFetchFailure(err: unknown): unknown {
  const failure = upstreamFetchFailure(err)
  if (!failure) return err
  logger.warn(
    { event: 'codex_catalog_upstream', causeCode: fetchCauseCode(err) },
    'Codex catalog upstream fetch failed'
  )
  return failure
}

function catalogTimeoutError(): CodexTransportError {
  return new CodexTransportError('provider_unavailable', 'catalog upstream deadline exceeded')
}

/** Read the catalog body under the deadline, cancelling past the byte cap. */
async function readBoundedCatalogBody(response: Response, signal: AbortSignal): Promise<string> {
  if (!response.body) return ''
  const reader = response.body.getReader()
  let onAbort: (() => void) | undefined
  const aborted = new Promise<never>((_, reject) => {
    onAbort = () => reject(catalogTimeoutError())
    if (signal.aborted) onAbort()
    else signal.addEventListener('abort', onAbort, { once: true })
  })
  aborted.catch(() => undefined)
  const chunks: Uint8Array[] = []
  let total = 0
  try {
    for (;;) {
      const { done, value } = await Promise.race([reader.read(), aborted])
      if (done) break
      total += value.byteLength
      if (total > CATALOG_LIMITS.maxBodyBytes) {
        throw new CodexTransportError('provider_unavailable', 'catalog upstream body exceeds limit')
      }
      chunks.push(value)
    }
  } catch (err) {
    await reader.cancel().catch(() => undefined)
    if (err instanceof CodexTransportError) throw err
    if (signal.aborted) throw catalogTimeoutError()
    throw catalogFetchFailure(err)
  } finally {
    if (onAbort) signal.removeEventListener('abort', onAbort)
    try {
      reader.releaseLock()
    } catch {
      // A pending read may still hold the lock after cancel; nothing to release.
    }
  }
  return Buffer.concat(chunks).toString('utf8')
}