codexLB-up 1.25.0b10__py3-none-any.whl

app/modules/proxy/request_policy.py

@@ -0,0 +1,1054 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import NamedTuple
+
+from pydantic import ValidationError
+
+from app.core.errors import OpenAIErrorEnvelope, openai_error
+from app.core.exceptions import ProxyModelNotAllowed, ProxyReasoningEffortNotAllowed
+from app.core.openai.exceptions import ClientPayloadError
+from app.core.openai.model_registry import ModelRegistry, canonical_service_tier_value, get_model_registry
+from app.core.openai.requests import (
+    ResponsesCompactRequest,
+    ResponsesReasoning,
+    ResponsesRequest,
+    extract_input_file_ids,
+    normalize_reasoning_aliases,
+    responses_input_uses_lite_tools,
+)
+from app.core.openai.strict_schema import (
+    validate_strict_function_tool_schema,
+    validate_strict_json_schema,
+)
+from app.core.openai.v1_requests import V1ResponsesRequest
+from app.core.types import JsonValue
+from app.core.utils.json_guards import is_json_list, is_json_mapping
+from app.core.utils.request_id import get_request_id
+from app.db.models import ModelSource
+from app.modules.api_keys.service import ApiKeyData
+from app.modules.model_sources.catalog import source_model_reasoning_levels
+
+logger = logging.getLogger(__name__)
+
+# Reasoning efforts that the upstream ChatGPT/Codex backend silently drops
+# (the WebSocket never produces ``response.completed``). When a client sends
+# one of these we transparently rewrite it to a value the resolved model
+# advertises in its ``supported_reasoning_levels`` so the request does not
+# hang. ``minimal`` is a valid value on the OpenAI Platform Responses API for
+# GPT-5 family models, but the ChatGPT backend codex-lb proxies to does not
+# accept it as of 2026-04. See https://github.com/Soju06/codex-lb/issues/493
+_UNSUPPORTED_UPSTREAM_REASONING_EFFORTS: frozenset[str] = frozenset({"minimal"})
+_DEFAULT_REASONING_EFFORT_FALLBACK = "low"
+
+# Client-plane reasoning efforts the reference Codex client never sends on the
+# wire. GPT-5.6 Sol/Terra advertise ``ultra`` in their catalog entries, but the
+# official client rewrites it to ``max`` before building the Responses request
+# (``reasoning_effort_for_request`` in codex-rs ``core/src/client.rs`` at
+# rust-v0.144.1); ``ultra``'s extra effect (proactive multi-agent mode) is
+# purely client-side. Mirror that aliasing for API-key enforcement and raw
+# API callers so the upstream backend only ever sees wire-safe values.
+_REASONING_EFFORT_WIRE_ALIASES: dict[str, str] = {"ultra": "max"}
+
+# Cursor exposes GPT-5 family model labels with UI suffixes such as "Extra
+# High Fast". The ChatGPT/Codex upstream accepts the canonical GPT-5-family
+# slug plus request fields, not those synthetic suffixes in the model name.
+# Keep this deliberately narrow: only strip known Cursor-style suffix tokens
+# from known GPT-5 base model slugs, and leave every other model untouched.
+_GPT5_ALIAS_BASE_MODELS: tuple[str, ...] = (
+    "gpt-5.6-sol",
+    "gpt-5.6-terra",
+    "gpt-5.6-luna",
+    "gpt-5.4-mini",
+    "gpt-5.3-codex",
+    "gpt-5.2-codex",
+    "gpt-5.1-codex-max",
+    "gpt-5.1-codex-mini",
+    "gpt-5.1-codex",
+    "gpt-5-codex",
+    "gpt-5.5",
+    "gpt-5.4",
+    "gpt-5.3",
+    "gpt-5.2",
+    "gpt-5.1",
+    "gpt-5",
+)
+_MODEL_ALIAS_REASONING_TOKENS: dict[str, str] = {
+    "minimal": "minimal",
+    "low": "low",
+    "medium": "medium",
+    "high": "high",
+    "xhigh": "high",
+    "extra": "high",
+}
+_MODEL_ALIAS_REASONING_RANK: dict[str, int] = {"minimal": 0, "low": 1, "medium": 2, "high": 3}
+_MODEL_ALIAS_SERVICE_TIER_TOKENS: dict[str, str] = {
+    "fast": "priority",
+    "priority": "priority",
+}
+_MODEL_ALIAS_IGNORED_TOKENS: frozenset[str] = frozenset({"reasoning", "thinking"})
+_MODEL_ALIAS_TOKENS: frozenset[str] = frozenset(
+    {
+        *tuple(_MODEL_ALIAS_REASONING_TOKENS),
+        *tuple(_MODEL_ALIAS_SERVICE_TIER_TOKENS),
+        *tuple(_MODEL_ALIAS_IGNORED_TOKENS),
+    }
+)
+
+# Service tier values codex-lb accepts at the API-key surface but that the
+# ChatGPT/Codex backend rejects with ``Unsupported service_tier: <value>``.
+# Semantically both ``auto`` and ``default`` mean "let upstream pick" -- the
+# same thing as omitting the field entirely -- so when an enforced API-key
+# policy resolves to one of these, we forward the request without a
+# ``service_tier`` instead of sending a literal that fails upstream. See
+# https://github.com/Soju06/codex-lb/issues/546
+_UPSTREAM_OMIT_SERVICE_TIERS: frozenset[str] = frozenset({"auto", "default"})
+
+
+def resolve_wire_reasoning_effort(effort: str) -> str:
+    """Return the wire-safe value for a client-plane reasoning effort.
+
+    The reference Codex client rewrites client-plane efforts (``ultra`` ->
+    ``max``) before building the upstream Responses request; every codex-lb
+    code path that builds an upstream payload directly (proxy enforcement,
+    automation compact pings) applies the same aliasing so the upstream
+    backend never sees a client-plane literal. Unknown values pass through
+    unchanged.
+    """
+    return _REASONING_EFFORT_WIRE_ALIASES.get(effort.strip().lower(), effort)
+
+
+def validate_model_access(api_key: ApiKeyData | None, model: str | None) -> None:
+    if api_key is None:
+        return
+    if not api_key.allowed_models:
+        return
+    allowed_models = {resolve_model_alias(allowed_model) for allowed_model in api_key.allowed_models}
+    effective_model = resolve_model_alias(model)
+    if model is None or effective_model in allowed_models:
+        return
+    raise ProxyModelNotAllowed(f"This API key does not have access to model '{model}'")
+
+
+def validate_reasoning_effort_access(api_key: ApiKeyData | None, effort: str | None) -> None:
+    if api_key is None:
+        return
+    allowed_reasoning_efforts = getattr(api_key, "allowed_reasoning_efforts", None)
+    if allowed_reasoning_efforts is None or effort is None:
+        return
+    normalized_effort = effort.strip().lower()
+    if normalized_effort in allowed_reasoning_efforts:
+        return
+    logger.info(
+        "api_key_reasoning_effort_not_allowed request_id=%s key_id=%s reasoning_effort=%s",
+        get_request_id(),
+        api_key.id,
+        normalized_effort,
+    )
+    raise ProxyReasoningEffortNotAllowed(
+        f"This API key does not have access to reasoning effort '{normalized_effort}'",
+        param="reasoning.effort",
+    )
+
+
+def _client_reasoning_effort(payload: ResponsesRequest | ResponsesCompactRequest) -> str | None:
+    """Return the effort selected by the client before wire normalization.
+
+    Cursor encodes its effort in an accepted model alias, where ``xhigh`` is
+    later lowered to the upstream's ``high`` value. API-key policies are an
+    operator-facing client-plane control, so they must compare against the
+    original selection rather than that wire representation.
+    """
+    model_effort = _client_reasoning_effort_from_model(payload.model)
+    if model_effort is not None:
+        return model_effort
+
+    reasoning = payload.reasoning.model_dump(mode="json", exclude_none=True) if payload.reasoning is not None else None
+    if is_json_mapping(reasoning):
+        effort = reasoning.get("effort")
+        if isinstance(effort, str) and effort.strip():
+            return effort.strip().lower()
+    return _client_reasoning_effort_from_provider_aliases(payload)
+
+
+def _client_reasoning_effort_from_provider_aliases(
+    payload: ResponsesRequest | ResponsesCompactRequest,
+) -> str | None:
+    reasoning = payload.reasoning.model_dump(mode="json", exclude_none=True) if payload.reasoning is not None else None
+    extra = payload.model_extra
+    if isinstance(extra, dict):
+        alias_payload = dict(extra)
+        if reasoning is not None:
+            alias_payload["reasoning"] = reasoning
+        normalize_reasoning_aliases(alias_payload)
+        normalized_reasoning = alias_payload.get("reasoning")
+        if is_json_mapping(normalized_reasoning):
+            extra_effort = normalized_reasoning.get("effort")
+            if isinstance(extra_effort, str) and extra_effort.strip():
+                return extra_effort.strip().lower()
+
+    return None
+
+
+def _materialize_provider_reasoning_effort(
+    payload: ResponsesRequest | ResponsesCompactRequest,
+    effort: str | None,
+) -> None:
+    existing_effort = payload.reasoning.effort if payload.reasoning is not None else None
+    if effort is None or (isinstance(existing_effort, str) and existing_effort.strip()):
+        return
+    if payload.reasoning is None:
+        payload.reasoning = ResponsesReasoning(effort=effort)
+    else:
+        payload.reasoning.effort = effort
+    if isinstance(payload, ResponsesRequest):
+        payload._codex_lb_provider_reasoning_effort_materialized = True
+
+
+def _client_reasoning_effort_from_model(model: str | None) -> str | None:
+    alias = _resolve_model_alias_parts(model)
+    if alias is not None:
+        normalized_model = model.strip().lower() if isinstance(model, str) else ""
+        suffix = normalized_model[len(alias[0]) + 1 :]
+        tokens = {token for token in suffix.split("-") if token}
+        if "xhigh" in tokens or "extra" in tokens:
+            return "xhigh"
+        if alias[1] is not None:
+            return alias[1]
+    return None
+
+
+def normalize_source_reasoning_aliases(payload: dict[str, JsonValue]) -> None:
+    """Align effort-bearing aliases while preserving unrelated source controls."""
+    provider_thinking = payload.get("thinking")
+    preserve_provider_thinking = False
+    if "thinking" in payload:
+        probe: dict[str, JsonValue] = {"thinking": provider_thinking}
+        normalize_reasoning_aliases(probe)
+        normalized_reasoning = probe.get("reasoning")
+        normalized_effort = normalized_reasoning.get("effort") if is_json_mapping(normalized_reasoning) else None
+        thinking_mapping = provider_thinking if is_json_mapping(provider_thinking) else None
+        thinking_type = thinking_mapping.get("type") if thinking_mapping is not None else None
+        is_inactive = thinking_mapping is not None and (
+            thinking_mapping.get("enabled") is False
+            or (isinstance(thinking_type, str) and thinking_type.strip().lower() == "disabled")
+        )
+        preserve_provider_thinking = (
+            thinking_mapping is not None
+            and not is_inactive
+            and not (isinstance(normalized_effort, str) and bool(normalized_effort.strip()))
+        )
+    if preserve_provider_thinking:
+        payload.pop("thinking", None)
+    normalize_reasoning_aliases(payload)
+    if preserve_provider_thinking and thinking_mapping is not None:
+        preserved_thinking = dict(thinking_mapping.items())
+        preserved_effort = preserved_thinking.get("effort")
+        if isinstance(preserved_effort, str) and not preserved_effort.strip():
+            preserved_thinking.pop("effort")
+        payload["thinking"] = preserved_thinking
+
+
+class ApiKeyEnforcementResult(NamedTuple):
+    """What :func:`apply_api_key_enforcement` observed while mutating the payload.
+
+    ``pre_normalization_reasoning_effort`` carries the effort that
+    :func:`normalize_unsupported_reasoning_effort` replaced, so a caller that
+    later routes the request to an OpenAI-compatible model source can restore
+    it. It is the post-enforcement value: restoring it cannot resurrect an
+    effort an API key overrode.
+    """
+
+    service_tier_was_enforced: bool
+    pre_normalization_reasoning_effort: str | None
+
+
+def apply_api_key_enforcement(
+    payload: ResponsesRequest | ResponsesCompactRequest,
+    api_key: ApiKeyData | None,
+    *,
+    registry: ModelRegistry | None = None,
+    prohibit_fast_mode: bool = False,
+) -> ApiKeyEnforcementResult:
+    """Apply API-key policy and report whether it supplied the service tier.
+
+    The returned provenance is captured before mutating ``payload``. Callers
+    must not infer it later by comparing values: an explicit client request can
+    equal the enforced value (including after ``fast`` canonicalizes to
+    ``priority``).
+    """
+    client_reasoning_effort = payload._codex_lb_client_reasoning_effort or _client_reasoning_effort(payload)
+    payload._codex_lb_client_reasoning_effort = client_reasoning_effort
+    provider_reasoning_effort = _client_reasoning_effort_from_provider_aliases(payload)
+    normalize_upstream_model_alias(payload)
+
+    if api_key is None:
+        _materialize_provider_reasoning_effort(payload, provider_reasoning_effort)
+        pre_normalization_effort = normalize_unsupported_reasoning_effort(payload, registry=registry)
+        apply_prohibit_fast_mode(payload, prohibit_fast_mode=prohibit_fast_mode)
+        return ApiKeyEnforcementResult(False, pre_normalization_effort)
+
+    if api_key.enforced_model:
+        enforced_model_reasoning_effort = _client_reasoning_effort_from_model(api_key.enforced_model)
+        requested_model = payload.model
+        if requested_model != api_key.enforced_model:
+            logger.info(
+                "api_key_model_enforced request_id=%s key_id=%s requested_model=%s enforced_model=%s",
+                get_request_id(),
+                api_key.id,
+                requested_model,
+                api_key.enforced_model,
+            )
+        payload.model = api_key.enforced_model
+        if enforced_model_reasoning_effort is not None:
+            client_reasoning_effort = enforced_model_reasoning_effort
+            payload._codex_lb_client_reasoning_effort = client_reasoning_effort
+        normalize_upstream_model_alias(payload)
+        if (
+            responses_input_uses_lite_tools(payload.input)
+            and _model_responses_lite_capability(
+                payload.model,
+                registry=registry or get_model_registry(),
+            )
+            is False
+        ):
+            raise ProxyModelNotAllowed(
+                f"API key enforced model '{payload.model}' does not support Responses Lite",
+                code="responses_lite_model_mismatch",
+            )
+
+    if api_key.enforced_reasoning_effort is not None:
+        requested_effort = payload.reasoning.effort if payload.reasoning else None
+        if payload.reasoning is None:
+            payload.reasoning = ResponsesReasoning(effort=api_key.enforced_reasoning_effort)
+        else:
+            payload.reasoning.effort = api_key.enforced_reasoning_effort
+        if requested_effort != api_key.enforced_reasoning_effort:
+            logger.info(
+                "api_key_reasoning_enforced request_id=%s key_id=%s requested_effort=%s enforced_effort=%s",
+                get_request_id(),
+                api_key.id,
+                requested_effort,
+                api_key.enforced_reasoning_effort,
+            )
+
+    _materialize_provider_reasoning_effort(payload, provider_reasoning_effort)
+    if client_reasoning_effort is not None:
+        validate_reasoning_effort_access(api_key, client_reasoning_effort)
+        if (
+            payload.reasoning is not None
+            and isinstance(payload.reasoning.effort, str)
+            and payload.reasoning.effort.strip().lower() == client_reasoning_effort
+        ):
+            payload.reasoning.effort = client_reasoning_effort
+    pre_normalization_effort = normalize_unsupported_reasoning_effort(payload, registry=registry)
+
+    service_tier_was_enforced = False
+    if api_key.enforced_service_tier is not None:
+        requested_service_tier = getattr(payload, "service_tier", None)
+        service_tier_was_enforced = requested_service_tier is None or (
+            requested_service_tier.strip().lower() in _UPSTREAM_OMIT_SERVICE_TIERS
+        )
+        # ``auto``/``default`` are accepted at the API-key surface but
+        # the ChatGPT/Codex backend rejects them as literal values. Map
+        # them onto the wire-level absence of ``service_tier`` (which
+        # already means "use upstream default") so the enforcement
+        # actually reaches upstream instead of failing with
+        # ``Unsupported service_tier``. See issue #546.
+        if api_key.enforced_service_tier in _UPSTREAM_OMIT_SERVICE_TIERS:
+            effective_service_tier: str | None = None
+        else:
+            effective_service_tier = api_key.enforced_service_tier
+        setattr(payload, "service_tier", effective_service_tier)
+        if requested_service_tier != api_key.enforced_service_tier:
+            logger.info(
+                "api_key_service_tier_enforced request_id=%s key_id=%s "
+                "requested_service_tier=%s enforced_service_tier=%s "
+                "outbound_service_tier=%s",
+                get_request_id(),
+                api_key.id,
+                requested_service_tier,
+                api_key.enforced_service_tier,
+                effective_service_tier,
+            )
+    apply_prohibit_fast_mode(payload, prohibit_fast_mode=prohibit_fast_mode)
+    return ApiKeyEnforcementResult(service_tier_was_enforced, pre_normalization_effort)
+
+
+def apply_prohibit_fast_mode(
+    payload: ResponsesRequest | ResponsesCompactRequest | dict[str, JsonValue],
+    *,
+    prohibit_fast_mode: bool,
+    request_id: str | None = None,
+) -> bool:
+    """Remove a resolved priority tier when the global policy prohibits it."""
+    raw_service_tier = payload.get("service_tier") if isinstance(payload, dict) else payload.service_tier
+    service_tier = raw_service_tier if isinstance(raw_service_tier, str) else None
+    if not prohibit_fast_mode or service_tier is None or canonical_service_tier_value(service_tier) != "priority":
+        return False
+
+    logger.info(
+        "fast_mode_service_tier_prohibited request_id=%s stripped_service_tier=%s",
+        request_id or get_request_id(),
+        service_tier,
+    )
+    if isinstance(payload, dict):
+        payload.pop("service_tier", None)
+    else:
+        payload.service_tier = None
+    return True
+
+
+def apply_enforced_service_tier_model_fallback(
+    payload: ResponsesRequest | ResponsesCompactRequest,
+    *,
+    service_tier_was_enforced: bool,
+    registry: ModelRegistry | None = None,
+) -> bool:
+    """Drop an enforced tier only when an account model truly lacks it.
+
+    This runs after model-source selection, and only on subscription-account
+    routes. Mutating the request at that boundary makes account selection,
+    bridge compatibility, API-key accounting, request logs, and the upstream
+    wire payload agree on the same effective tier.
+    """
+    service_tier = payload.service_tier
+    if not service_tier_was_enforced or service_tier is None:
+        return False
+
+    model_registry = registry or get_model_registry()
+    advertises_service_tier = getattr(model_registry, "model_advertises_service_tier", None)
+    if not callable(advertises_service_tier) or advertises_service_tier(payload.model, service_tier):
+        return False
+
+    logger.info(
+        "api_key_enforced_service_tier_model_fallback request_id=%s model=%s enforced_service_tier=%s",
+        get_request_id(),
+        payload.model,
+        service_tier,
+    )
+    payload.service_tier = None
+    return True
+
+
+def _model_responses_lite_capability(
+    model: str,
+    *,
+    registry: ModelRegistry,
+) -> bool | None:
+    normalized_model = model.strip().lower()
+    models = registry.get_models_for_metadata()
+    model_entry = models.get(model) or models.get(normalized_model)
+    if model_entry is None:
+        return None
+    capability = model_entry.raw.get("use_responses_lite")
+    return capability if isinstance(capability, bool) else None
+
+
+# Non-standard reasoning toggles some OpenAI-compatible clients attach
+# (OpenRouter/SGLang style). Forwarding them to a source whose model does not
+# support reasoning flips the upstream into reasoning-extraction mode: the
+# answer lands in ``message.reasoning`` instead of ``message.content``.
+_SOURCE_REASONING_TOGGLE_KEYS: tuple[str, ...] = (
+    "include_reasoning",
+    "separate_reasoning",
+    "stream_reasoning",
+    "reasoning",
+    "reasoning_effort",
+)
+
+
+def sanitize_source_chat_payload(
+    payload: dict[str, JsonValue],
+    *,
+    allow_reasoning: bool,
+) -> None:
+    """Clean a chat-completions wire payload before forwarding to a source.
+
+    ``ChatCompletionsRequest`` allows extra fields and defaults ``tools`` to an
+    empty list, so an unfiltered ``model_dump`` forwards ``"tools": []`` and any
+    client-side reasoning toggles verbatim.
+    """
+    tools = payload.get("tools")
+    if isinstance(tools, list) and not tools:
+        payload.pop("tools", None)
+        payload.pop("tool_choice", None)
+        payload.pop("parallel_tool_calls", None)
+    if not allow_reasoning:
+        for key in _SOURCE_REASONING_TOGGLE_KEYS:
+            payload.pop(key, None)
+
+
+def apply_api_key_enforcement_to_chat_payload(
+    payload: dict[str, JsonValue],
+    api_key: ApiKeyData | None,
+    *,
+    allowed_reasoning_effort: str | None = None,
+    materialize_allowed_reasoning_effort: bool = False,
+) -> None:
+    """Mirror :func:`apply_api_key_enforcement` onto a chat-completions wire payload.
+
+    Source-routed chat requests forward the original chat-shaped payload
+    instead of the converted ``ResponsesRequest``, so enforced fields must be
+    applied to the outbound dict as well or the upstream receives the
+    caller's values while accounting uses the enforced ones.
+    """
+    if allowed_reasoning_effort is not None:
+        wire_effort = resolve_wire_reasoning_effort(allowed_reasoning_effort)
+        # Chat requests can express the same setting through several provider
+        # aliases. Once the Responses conversion has authorized one effective
+        # choice, make every caller-supplied alias agree without adding fields
+        # that the selected source may not accept.
+        if "reasoning_effort" in payload:
+            payload["reasoning_effort"] = wire_effort
+        if "reasoningEffort" in payload:
+            payload["reasoningEffort"] = wire_effort
+        if "thinking" in payload:
+            thinking = payload["thinking"]
+            if isinstance(thinking, dict):
+                thinking_effort = thinking.get("effort")
+                if isinstance(thinking_effort, str) and not thinking_effort.strip():
+                    thinking = {**thinking}
+                    thinking.pop("effort")
+                    payload["thinking"] = thinking
+                if isinstance(thinking_effort, str) and thinking_effort.strip():
+                    aligned_thinking = {**thinking, "effort": wire_effort}
+                    thinking_type = aligned_thinking.get("type")
+                    if isinstance(thinking_type, str) and thinking_type.strip().lower() == "disabled":
+                        aligned_thinking.pop("type")
+                    if aligned_thinking.get("enabled") is False:
+                        aligned_thinking.pop("enabled")
+                    payload["thinking"] = aligned_thinking
+                else:
+                    thinking_type = thinking.get("type")
+                    is_inactive = thinking.get("enabled") is False or (
+                        isinstance(thinking_type, str) and thinking_type.strip().lower() == "disabled"
+                    )
+                    selects_implicit_medium = thinking.get("enabled") is True or (
+                        isinstance(thinking_type, str) and thinking_type.strip().lower() == "enabled"
+                    )
+                    if is_inactive or (selects_implicit_medium and wire_effort != "medium"):
+                        payload.pop("thinking")
+            else:
+                payload["thinking"] = wire_effort
+        if "enable_thinking" in payload:
+            if wire_effort == "medium":
+                payload["enable_thinking"] = True
+            else:
+                payload.pop("enable_thinking", None)
+        reasoning = payload.get("reasoning")
+        if isinstance(reasoning, dict):
+            payload["reasoning"] = {**reasoning, "effort": wire_effort}
+        if materialize_allowed_reasoning_effort and not any(
+            key in payload
+            for key in ("reasoning_effort", "reasoningEffort", "thinking", "enable_thinking", "reasoning")
+        ):
+            payload["reasoning_effort"] = wire_effort
+
+    if api_key is None:
+        return
+
+    if api_key.enforced_reasoning_effort is not None:
+        enforced_effort = resolve_wire_reasoning_effort(api_key.enforced_reasoning_effort)
+        payload["reasoning_effort"] = enforced_effort
+        reasoning = payload.get("reasoning")
+        if isinstance(reasoning, dict):
+            payload["reasoning"] = {**reasoning, "effort": enforced_effort}
+        else:
+            payload["reasoning"] = {"effort": enforced_effort}
+
+    if api_key.enforced_service_tier is not None:
+        if api_key.enforced_service_tier in _UPSTREAM_OMIT_SERVICE_TIERS:
+            payload.pop("service_tier", None)
+        else:
+            payload["service_tier"] = api_key.enforced_service_tier
+
+
+def resolve_model_alias(model: str | None) -> str | None:
+    alias = _resolve_model_alias_parts(model)
+    if alias is None:
+        return model
+    return alias[0]
+
+
+def model_alias_requests_fast_mode(model: str | None) -> bool:
+    alias = _resolve_model_alias_parts(model)
+    return alias is not None and alias[3]
+
+
+def normalize_upstream_model_alias(payload: ResponsesRequest | ResponsesCompactRequest) -> None:
+    requested_model = payload.model
+    alias = _resolve_model_alias_parts(requested_model)
+    if alias is None:
+        return
+
+    canonical_model, alias_effort, alias_service_tier, _alias_requests_fast_mode = alias
+    if payload.model != canonical_model:
+        logger.info(
+            "model_alias_normalized request_id=%s requested_model=%s normalized_model=%s",
+            get_request_id(),
+            payload.model,
+            canonical_model,
+        )
+        payload.model = canonical_model
+
+    if alias_effort is not None:
+        requested_effort = payload.reasoning.effort if payload.reasoning else None
+        if payload.reasoning is None:
+            payload.reasoning = ResponsesReasoning(effort=alias_effort)
+        else:
+            payload.reasoning.effort = alias_effort
+        if requested_effort != alias_effort:
+            logger.info(
+                "model_alias_reasoning_normalized request_id=%s requested_model=%s "
+                "normalized_model=%s requested_effort=%s normalized_effort=%s",
+                get_request_id(),
+                requested_model,
+                canonical_model,
+                requested_effort,
+                alias_effort,
+            )
+
+    if alias_service_tier is not None and getattr(payload, "service_tier", None) is None:
+        setattr(payload, "service_tier", alias_service_tier)
+        logger.info(
+            "model_alias_service_tier_normalized request_id=%s requested_model=%s "
+            "normalized_model=%s normalized_service_tier=%s",
+            get_request_id(),
+            requested_model,
+            canonical_model,
+            alias_service_tier,
+        )
+
+
+def _resolve_model_alias_parts(model: str | None) -> tuple[str, str | None, str | None, bool] | None:
+    if not isinstance(model, str):
+        return None
+    normalized = model.strip().lower()
+    if not normalized:
+        return None
+
+    for base_model in _GPT5_ALIAS_BASE_MODELS:
+        prefix = f"{base_model}-"
+        if not normalized.startswith(prefix):
+            continue
+        suffix = normalized[len(prefix) :]
+        tokens = [token for token in suffix.split("-") if token]
+        if not tokens or any(token not in _MODEL_ALIAS_TOKENS for token in tokens):
+            return None
+        return (
+            base_model,
+            _resolve_alias_reasoning_effort(tokens),
+            _resolve_alias_service_tier(tokens),
+            "fast" in tokens,
+        )
+
+    return None
+
+
+def _resolve_alias_reasoning_effort(tokens: list[str]) -> str | None:
+    selected: str | None = None
+    selected_rank = -1
+    for token in tokens:
+        effort = _MODEL_ALIAS_REASONING_TOKENS.get(token)
+        if effort is None:
+            continue
+        rank = _MODEL_ALIAS_REASONING_RANK[effort]
+        if rank > selected_rank:
+            selected = effort
+            selected_rank = rank
+    return selected
+
+
+def _resolve_alias_service_tier(tokens: list[str]) -> str | None:
+    for token in tokens:
+        service_tier = _MODEL_ALIAS_SERVICE_TIER_TOKENS.get(token)
+        if service_tier is not None:
+            return service_tier
+    return None
+
+
+def normalize_unsupported_reasoning_effort(
+    payload: ResponsesRequest | ResponsesCompactRequest,
+    *,
+    registry: ModelRegistry | None = None,
+) -> str | None:
+    """Rewrite ``reasoning.effort`` values the upstream backend rejects.
+
+    Some efforts that codex-lb accepts at the API surface (notably
+    ``"minimal"``) are silently dropped by the ChatGPT/Codex WebSocket
+    backend, which causes the response stream to hang with no completion.
+    For those values we map to a value the resolved model actually supports
+    so clients (e.g. Codex CLI's ``--reasoning-effort minimal``) keep
+    working. Mapping picks the model's lowest advertised effort, falling
+    back to ``low`` when the registry has no metadata yet.
+
+    Client-plane efforts the reference Codex client aliases before sending
+    (``ultra`` -> ``max``) are rewritten the same way here.
+
+    Returns the effort that the unsupported-effort fallback replaced, in
+    normalized (trimmed, lowercased) form, or ``None`` when nothing restorable
+    was rewritten. Model sources do not have the backend quirk that fallback
+    works around, but whether a request is served by one is only known after
+    source selection, which happens later; callers that can reach a source
+    carry this value forward and restore it there (see
+    ``restore_source_reasoning_effort``).
+
+    The ``ultra`` -> ``max`` wire alias is never reported. That aliasing mirrors
+    the reference client and is required on every upstream surface, so it must
+    survive source routing too.
+
+    The reported value is the post-enforcement effort rather than the client's
+    original, so restoring it cannot resurrect an effort an API key overrode.
+    """
+
+    if payload.reasoning is None or payload.reasoning.effort is None:
+        return None
+
+    requested_effort = payload.reasoning.effort
+    normalized_effort = requested_effort.strip().lower()
+
+    wire_alias = _REASONING_EFFORT_WIRE_ALIASES.get(normalized_effort)
+    if wire_alias is not None:
+        payload.reasoning.effort = wire_alias
+        logger.info(
+            "reasoning_effort_wire_aliased request_id=%s model=%s requested_effort=%s aliased_effort=%s",
+            get_request_id(),
+            payload.model,
+            requested_effort,
+            wire_alias,
+        )
+        # Deliberately not reported as restorable: the ultra -> max alias must
+        # hold on every surface, source-routed payloads included.
+        return None
+
+    if normalized_effort not in _UNSUPPORTED_UPSTREAM_REASONING_EFFORTS:
+        return None
+
+    fallback = _resolve_reasoning_effort_fallback(
+        payload.model,
+        registry=registry or get_model_registry(),
+    )
+    payload.reasoning.effort = fallback
+    logger.info(
+        "reasoning_effort_normalized request_id=%s model=%s requested_effort=%s normalized_effort=%s",
+        get_request_id(),
+        payload.model,
+        requested_effort,
+        fallback,
+    )
+    return normalized_effort
+
+
+def restore_source_reasoning_effort(
+    payload: ResponsesRequest | ResponsesCompactRequest,
+    source: ModelSource,
+    *,
+    pre_normalization_effort: str | None,
+) -> None:
+    """Undo :func:`normalize_unsupported_reasoning_effort` for a source-routed request.
+
+    The rewrite exists solely to work around a ChatGPT/Codex backend quirk, so
+    it must not reach an OpenAI-compatible model source. This runs at the point
+    where the source has actually been selected, which is the only place the
+    routing outcome is known -- inferring it earlier from registry membership
+    misfires in both directions (a subscription model missing from a populated
+    snapshot, and a source model whose slug shadows a subscription one).
+
+    The restore is gated on the operator having declared the effort for this
+    model: sources without reasoning metadata keep the pre-existing behaviour,
+    and an effort the backend never advertised is not sent to it.
+    """
+    if pre_normalization_effort is None or payload.reasoning is None:
+        return
+    if payload.model is None:
+        return
+    restored_effort = pre_normalization_effort.strip().lower()
+    declared = {level.effort for level in source_model_reasoning_levels(source, payload.model)}
+    if restored_effort not in declared:
+        return
+    current_effort = payload.reasoning.effort
+    # Normalized on assignment rather than trusting the caller: the sole
+    # producer already reports the normalized form, but that invariant is
+    # non-local and a casing variant must never reach the wire.
+    payload.reasoning.effort = restored_effort
+    logger.info(
+        "reasoning_effort_restored_for_source request_id=%s model=%s source_id=%s "
+        "normalized_effort=%s restored_effort=%s",
+        get_request_id(),
+        payload.model,
+        source.id,
+        current_effort,
+        restored_effort,
+    )
+
+
+def _resolve_reasoning_effort_fallback(
+    model: str | None,
+    *,
+    registry: ModelRegistry,
+) -> str:
+    if not model:
+        return _DEFAULT_REASONING_EFFORT_FALLBACK
+    snapshot = registry.get_snapshot()
+    if snapshot is None:
+        return _DEFAULT_REASONING_EFFORT_FALLBACK
+    upstream = snapshot.models.get(model) or snapshot.models.get(model.strip().lower())
+    if upstream is None:
+        return _DEFAULT_REASONING_EFFORT_FALLBACK
+    advertised = [level.effort for level in upstream.supported_reasoning_levels if level.effort]
+    # Prefer the order the model registry advertises (already lowest -> highest
+    # for the GPT-5 family), but always pick the first advertised effort that
+    # is not itself an unsupported value.
+    for effort in advertised:
+        if effort.strip().lower() not in _UNSUPPORTED_UPSTREAM_REASONING_EFFORTS:
+            return effort
+    return _DEFAULT_REASONING_EFFORT_FALLBACK
+
+
+def openai_validation_error(exc: ValidationError) -> OpenAIErrorEnvelope:
+    error = openai_invalid_payload_error()
+    if exc.errors():
+        first = exc.errors()[0]
+        loc = first.get("loc", [])
+        if isinstance(loc, (list, tuple)):
+            param = ".".join(str(part) for part in loc if part != "body")
+            if param:
+                error["error"]["param"] = param
+    return error
+
+
+def openai_invalid_payload_error(param: str | None = None) -> OpenAIErrorEnvelope:
+    error = openai_error("invalid_request_error", "Invalid request payload", error_type="invalid_request_error")
+    if param:
+        error["error"]["param"] = param
+    return error
+
+
+def openai_client_payload_error(exc: ClientPayloadError) -> OpenAIErrorEnvelope:
+    """Render a ``ClientPayloadError`` as an OpenAI error envelope.
+
+    Falls back to ``openai_invalid_payload_error`` for legacy callsites
+    that raise ``ClientPayloadError`` without ``code`` / ``error_type``.
+    """
+    if exc.code is None and exc.error_type is None:
+        return openai_invalid_payload_error(exc.param)
+    code = exc.code or "invalid_request_error"
+    error_type = exc.error_type or "invalid_request_error"
+    error = openai_error(code, str(exc), error_type=error_type)
+    if exc.param:
+        error["error"]["param"] = exc.param
+    return error
+
+
+def normalize_responses_request_payload(
+    payload: dict[str, JsonValue],
+    *,
+    openai_compat: bool,
+) -> ResponsesRequest:
+    if openai_compat:
+        responses = V1ResponsesRequest.model_validate(payload).to_responses_request()
+    else:
+        responses = ResponsesRequest.model_validate(payload)
+    enforce_strict_text_format(responses)
+    enforce_strict_function_tools_format(responses.tools)
+    return responses
+
+
+def validate_top_level_compaction_trigger_input_shape(payload: Mapping[str, JsonValue]) -> None:
+    input_value = payload.get("input")
+    if not is_json_list(input_value):
+        return
+    _validate_terminal_compaction_trigger_input_items(input_value)
+
+
+def strip_terminal_compaction_trigger_input(
+    payload: ResponsesRequest | ResponsesCompactRequest,
+    *,
+    strip_trigger: bool = True,
+) -> list[JsonValue] | None:
+    input_value = payload.input
+    if not is_json_list(input_value):
+        return None
+    return _strip_terminal_compaction_trigger_input_items(input_value, strip_trigger=strip_trigger)
+
+
+def _strip_terminal_compaction_trigger_input_items(
+    input_value: list[JsonValue],
+    *,
+    strip_trigger: bool,
+) -> list[JsonValue] | None:
+    trigger_seen = _validate_terminal_compaction_trigger_input_items(input_value)
+    if not trigger_seen:
+        return None
+    if not strip_trigger:
+        return input_value
+    return [item for item in input_value if not (is_json_mapping(item) and item.get("type") == "compaction_trigger")]
+
+
+def _validate_terminal_compaction_trigger_input_items(input_value: list[JsonValue]) -> bool:
+    trigger_seen = False
+    last_index = len(input_value) - 1
+
+    for index, item in enumerate(input_value):
+        if not (is_json_mapping(item) and item.get("type") == "compaction_trigger"):
+            continue
+
+        if trigger_seen or index != last_index:
+            raise ClientPayloadError(
+                "compaction_trigger must appear exactly once as the final top-level input item",
+                param="input",
+                code="invalid_request_error",
+                error_type="invalid_request_error",
+            )
+        trigger_seen = True
+
+    return trigger_seen
+
+
+def responses_source_route_excluded(
+    payload: ResponsesRequest,
+    *,
+    exclude_compaction: bool = True,
+) -> bool:
+    """True when a Responses request must stay on subscription accounts.
+
+    A terminal compaction trigger is served by the upstream compact flow on
+    the turn's owner account (Codex path only — callers set
+    ``exclude_compaction=False`` on ``/v1/responses``, which has no Codex
+    compaction path). An ``input_file``/``input_image`` file reference is
+    pinned to the subscription account that received the upload. Previous
+    response ownership is resolved separately from recorded continuity
+    evidence because response identifier syntax is provider-opaque.
+
+    Raises ``ClientPayloadError`` for a malformed compaction trigger, exactly
+    like ``strip_terminal_compaction_trigger_input``.
+    """
+    if exclude_compaction and strip_terminal_compaction_trigger_input(payload) is not None:
+        return True
+    return bool(extract_input_file_ids(payload.input))
+
+
+def enforce_strict_text_format(request: ResponsesRequest) -> None:
+    """Reject strict-mode JSON schemas that violate OpenAI structured-outputs rules.
+
+    The Codex backend mirrors OpenAI's strict-mode policy and closes the
+    websocket with ``close_code=1000`` (delivering the original
+    ``invalid_json_schema`` payload via ``response.failed``). The local
+    pre-check raises a deterministic 400 before any upstream connection
+    is opened, keeping ``/v1/responses`` and the chat-conversion path
+    consistent and avoiding pointless retry/reconnect cycles for
+    permanently invalid schemas.
+    """
+    if request.text is None or request.text.format is None:
+        return
+    text_format = request.text.format
+    if text_format.type != "json_schema" or text_format.strict is not True:
+        return
+    if text_format.schema_ is None:
+        return
+    violation = validate_strict_json_schema(
+        text_format.schema_,
+        name=text_format.name,
+        param="text.format.schema",
+    )
+    if violation is None:
+        return
+    raise ClientPayloadError(
+        violation.message,
+        param=violation.param,
+        code=violation.code,
+        error_type="invalid_request_error",
+    )
+
+
+def enforce_strict_function_tools_format(
+    tools: list[JsonValue] | None,
+    *,
+    param_template: str = "tools[{index}].parameters",
+    nested: bool = False,
+) -> None:
+    """Reject strict-mode function tools whose parameter schemas violate OpenAI rules.
+
+    Mirrors :func:`enforce_strict_text_format` for function tools that
+    set ``strict: true``. The Codex backend rejects an invalid strict
+    tool schema by closing the WebSocket with ``close_code=1000``; the
+    surfaced error is a generic ``upstream_rejected_input`` 502, which
+    well-behaved retry loops misclassify as transient. Real OpenAI
+    returns a deterministic ``400 invalid_function_parameters`` for the
+    same payload, so codex-lb pre-validates here.
+
+    ``param_template`` controls how the rejected parameter is named in
+    the error envelope: native ``/v1/responses`` callers see
+    ``tools[<i>].parameters``; chat-completions callers pass
+    ``"tools[{index}].function.parameters"`` to mirror the inbound
+    shape.
+
+    ``nested`` selects the shape of an inbound function tool:
+
+    * ``False`` (default) — flat ``{"type": "function", "name": ...,
+      "parameters": ..., "strict": ...}``. This is the
+      ``/v1/responses`` request shape (and the shape produced by
+      ``_normalize_chat_tools``).
+    * ``True`` — chat-completions shape with the function payload
+      wrapped under ``"function"``:
+      ``{"type": "function", "function": {"name": ..., "parameters":
+      ..., "strict": ...}}``. The chat handler MUST pass ``True`` and
+      hand in the *original* request payload's ``tools`` list (not the
+      list returned by ``ChatCompletionsRequest.to_responses_request``,
+      which may drop or reorder entries) so the ``{index}`` slot in
+      ``param_template`` lines up with the inbound payload.
+
+      A tool is treated as a function tool whenever ``tool["function"]``
+      is a dict — the same rule ``_normalize_chat_tools`` uses, where
+      missing or other ``type`` values get coerced to ``"function"``
+      (``"type": tool_type or "function"``). Anchoring on the wrapper
+      key keeps pre-validation in lockstep with normalization; otherwise
+      a payload like ``{"function": {"strict": true, "parameters":
+      <invalid>}}`` (no top-level ``type``) bypasses the local 400 and
+      surfaces as a misleading upstream 5xx.
+    """
+    if not tools:
+        return
+    for index, tool in enumerate(tools):
+        if not isinstance(tool, dict):
+            continue
+        if nested:
+            # Chat path: detect function tools the same way
+            # ``_normalize_chat_tools`` does — presence of a ``"function"``
+            # dict is the signal, not a strict ``"type" == "function"``
+            # check. The normalizer coerces missing or other ``type``
+            # values to ``"function"`` whenever ``tool["function"]`` is a
+            # dict (`"type": tool_type or "function"`), so pre-validation
+            # must mirror that or strict violations on type-omitted
+            # nested tools bypass the local 400 and surface as upstream
+            # 5xx instead.
+            function_value = tool.get("function")
+            if not isinstance(function_value, dict):
+                continue
+            descriptor = function_value
+        else:
+            if tool.get("type") != "function":
+                continue
+            descriptor = tool
+        if descriptor.get("strict") is not True:
+            continue
+        parameters = descriptor.get("parameters")
+        if parameters is None:
+            continue
+        raw_name = descriptor.get("name")
+        name = raw_name if isinstance(raw_name, str) else None
+        violation = validate_strict_function_tool_schema(
+            parameters,
+            name=name,
+            param=param_template.format(index=index),
+        )
+        if violation is None:
+            continue
+        raise ClientPayloadError(
+            violation.message,
+            param=violation.param,
+            code=violation.code,
+            error_type="invalid_request_error",
+        )