codexLB-up 1.25.0b10__py3-none-any.whl

app/modules/proxy/_service/streaming/helpers.py

@@ -0,0 +1,1317 @@
+from __future__ import annotations
+
+import inspect
+import json
+import sys
+from collections.abc import Callable
+from copy import deepcopy
+from typing import Any, AsyncIterator, Literal, Mapping, cast
+
+from app.core.balancer import PERMANENT_FAILURE_CODES
+from app.core.balancer.types import ClassifiedFailure, UpstreamError
+from app.core.clients.files import create_file as core_create_file  # noqa: F401
+from app.core.clients.files import finalize_file as core_finalize_file  # noqa: F401
+from app.core.clients.http import lease_http_session as lease_http_session  # noqa: F401
+from app.core.clients.proxy import CodexControlRequestPrivacyPolicy as CodexControlRequestPrivacyPolicy
+from app.core.clients.proxy import CodexControlResponse as CodexControlResponse
+from app.core.clients.proxy import (  # noqa: F401  # noqa: F401
+    ImageFetchSession,
+    ProxyResponseError,
+    UpstreamProxyRouteTrace,
+    _agent_control_tool_output_occurrences,
+    _as_image_fetch_session,
+    _inline_content_images,
+    _inline_input_image_urls,
+    _ws_transport_payload_budget_bytes,
+    filter_inbound_headers,
+    pop_compact_timeout_overrides,
+    pop_stream_timeout_overrides,
+    pop_transcribe_timeout_overrides,
+    push_compact_timeout_overrides,
+    push_stream_timeout_overrides,
+    push_transcribe_timeout_overrides,
+)
+from app.core.clients.proxy import codex_control_request as core_codex_control_request  # noqa: F401
+from app.core.clients.proxy import compact_responses as core_compact_responses  # noqa: F401
+from app.core.clients.proxy import transcribe_audio as core_transcribe_audio  # noqa: F401
+from app.core.clients.proxy_websocket import (
+    UpstreamWebSocket,
+)
+from app.core.clock import Clock
+from app.core.errors import (
+    PREVIOUS_RESPONSE_MALFORMED_PARAM_REASON,
+    PREVIOUS_RESPONSE_STREAM_INCOMPLETE_MESSAGE,
+    SYNTHETIC_TRANSPORT_FAILURE_CODES,
+    SYNTHETIC_TRANSPORT_FAILURE_MARKER,
+    OpenAIErrorParam,
+    openai_error,
+    response_failed_event,
+    synthetic_stream_failure_event,
+    synthetic_transport_failure_event,
+)
+from app.core.errors import (
+    PREVIOUS_RESPONSE_NOT_FOUND_CODE as PREVIOUS_RESPONSE_NOT_FOUND_CODE,
+)
+from app.core.errors import (
+    PREVIOUS_RESPONSE_NOT_FOUND_MESSAGE as PREVIOUS_RESPONSE_NOT_FOUND_MESSAGE,
+)
+from app.core.openai.models import OpenAIError, OpenAIEvent, OpenAIResponsePayload, ResponseUsage
+from app.core.openai.parsing import classify_event_type, parse_sse_event
+from app.core.openai.requests import ResponsesRequest
+from app.core.resilience.network_recovery import (
+    PROCESS_NETWORK_UNAVAILABLE_CODE,
+)
+from app.core.types import JsonValue
+from app.core.upstream_proxy import ResolvedUpstreamRoute, UpstreamProxyRouteError
+from app.core.upstream_proxy.cache import get_upstream_route_cache
+from app.core.utils.request_id import get_request_id
+from app.core.utils.sse import CODEX_KEEPALIVE_FRAME as CODEX_KEEPALIVE_FRAME  # noqa: F401
+from app.core.utils.sse import ParsedSseBlock, format_sse_event, parse_sse_data_json
+from app.core.utils.time import utcnow as utcnow
+from app.db.models import (
+    Account,
+    AccountStatus,  # noqa: F401
+)
+from app.modules.api_keys.service import ApiKeyData
+from app.modules.proxy._load_balancer.overload_backoff import (
+    UPSTREAM_OVERLOAD_CODES,
+    UPSTREAM_SOFT_OVERLOAD_CODES,
+    record_upstream_burst_rejection,
+    record_upstream_overload,
+)
+from app.modules.proxy._service.api_key_usage import (
+    _API_KEY_RESERVATION_HEARTBEAT_SECONDS as _API_KEY_RESERVATION_HEARTBEAT_SECONDS,
+)
+from app.modules.proxy._service.compact import (
+    _service_tier_from_compact_payload as _service_tier_from_compact_payload,
+)
+from app.modules.proxy._service.compact import (
+    _sticky_key_for_compact_request as _sticky_key_for_compact_request,
+)
+from app.modules.proxy._service.compact import (
+    _sticky_key_from_compact_payload as _sticky_key_from_compact_payload,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _active_http_bridge_instance_ring as _active_http_bridge_instance_ring,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _build_http_bridge_prewarm_text as _build_http_bridge_prewarm_text,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _durable_bridge_lookup_active_owner as _durable_bridge_lookup_active_owner,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _durable_bridge_lookup_allows_local_reuse as _durable_bridge_lookup_allows_local_reuse,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _effective_http_bridge_idle_ttl_seconds as _effective_http_bridge_idle_ttl_seconds,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _forwarded_http_bridge_session_key as _forwarded_http_bridge_session_key,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _has_http_bridge_response_output_marker as _has_http_bridge_response_output_marker,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_allow_durable_takeover as _http_bridge_allow_durable_takeover,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_can_local_recover_without_ring as _http_bridge_can_local_recover_without_ring,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_can_recover_during_drain as _http_bridge_can_recover_during_drain,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_continuity_lost_error_envelope as _http_bridge_continuity_lost_error_envelope,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_durable_lease_ttl_seconds as _http_bridge_durable_lease_ttl_seconds,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_endpoint_matches_current_instance as _http_bridge_endpoint_matches_current_instance,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_eviction_priority as _http_bridge_eviction_priority,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_has_durable_recovery_anchor as _http_bridge_has_durable_recovery_anchor,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_input_item_type as _http_bridge_input_item_type,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_is_context_overflow_error as _http_bridge_is_context_overflow_error,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_is_previous_response_owner_unavailable as _http_bridge_is_previous_response_owner_unavailable,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_key_strength as _http_bridge_key_strength,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_owner_check_required as _http_bridge_owner_check_required,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_owner_instance as _http_bridge_owner_instance,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_owner_lookup_unavailable_error_envelope as _http_bridge_owner_lookup_unavailable_error_envelope,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_payload_looks_like_full_resend as _http_bridge_payload_looks_like_full_resend,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_payload_without_previous_response_id as _http_bridge_payload_without_previous_response_id,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_precreated_retry_failure_error as _http_bridge_precreated_retry_failure_error,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_previous_response_alias_key as _http_bridge_previous_response_alias_key,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_previous_response_error_envelope as _http_bridge_previous_response_error_envelope,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_request_counts_against_queue as _http_bridge_request_counts_against_queue,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_request_stage as _http_bridge_request_stage,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_requires_cluster_registration as _http_bridge_requires_cluster_registration,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_runtime_config as _http_bridge_runtime_config,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_session_allows_api_key as _http_bridge_session_allows_api_key,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_session_has_visible_requests as _http_bridge_session_has_visible_requests,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_session_matches_preferred_account as _http_bridge_session_matches_preferred_account,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_session_retiring_with_visible_requests as _http_bridge_session_retiring_with_visible_requests,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_session_reusable_for_request as _http_bridge_session_reusable_for_request,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_should_attempt_local_bootstrap_rebind as _http_bridge_should_attempt_local_bootstrap_rebind,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_should_attempt_local_previous_response_recovery,  # noqa: F401
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_should_attempt_soft_affinity_reroute as _http_bridge_should_attempt_soft_affinity_reroute,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_should_rollover_after_context_overflow as _http_bridge_should_rollover_after_context_overflow,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_should_wait_for_registration as _http_bridge_should_wait_for_registration,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_startup_wait_timeout_error as _http_bridge_startup_wait_timeout_error,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _http_bridge_turn_state_alias_key as _http_bridge_turn_state_alias_key,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _is_http_bridge_previous_response_output_item as _is_http_bridge_previous_response_output_item,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _is_missing_durable_bridge_table_error as _is_missing_durable_bridge_table_error,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _log_http_bridge_event as _log_http_bridge_event,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _log_http_bridge_startup_wait_timeout as _log_http_bridge_startup_wait_timeout,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _make_http_bridge_session_key as _make_http_bridge_session_key,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _normalize_http_bridge_error_event as _normalize_http_bridge_error_event,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _normalized_http_bridge_instance_ring as _normalized_http_bridge_instance_ring,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _preferred_http_bridge_reconnect_turn_state as _preferred_http_bridge_reconnect_turn_state,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _record_bridge_drain_recovery_allowed as _record_bridge_drain_recovery_allowed,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _record_bridge_first_turn_timeout as _record_bridge_first_turn_timeout,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _record_bridge_reattach as _record_bridge_reattach,
+)
+from app.modules.proxy._service.http_bridge.helpers import (
+    _trim_http_bridge_previous_response_input_items as _trim_http_bridge_previous_response_input_items,
+)
+from app.modules.proxy._service.observability import (
+    _hash_identifier as _hash_identifier,
+)
+from app.modules.proxy._service.observability import (
+    _hash_identifier_or_none as _hash_identifier_or_none,
+)
+from app.modules.proxy._service.observability import (
+    _interesting_header_keys as _interesting_header_keys,
+)
+from app.modules.proxy._service.observability import (
+    _is_reasoning_replay_rejection as _is_reasoning_replay_rejection,
+)
+from app.modules.proxy._service.observability import (
+    _maybe_log_proxy_request_payload as _maybe_log_proxy_request_payload,
+)
+from app.modules.proxy._service.observability import (
+    _maybe_log_proxy_request_shape as _maybe_log_proxy_request_shape,
+)
+from app.modules.proxy._service.observability import (
+    _maybe_log_proxy_service_tier_trace as _maybe_log_proxy_service_tier_trace,
+)
+from app.modules.proxy._service.observability import (
+    _observe_terminal_stream_error_frame as _observe_terminal_stream_error_frame,
+)
+from app.modules.proxy._service.observability import (
+    _record_continuity_fail_closed as _record_continuity_fail_closed,
+)
+from app.modules.proxy._service.observability import (
+    _record_continuity_owner_resolution as _record_continuity_owner_resolution,
+)
+from app.modules.proxy._service.observability import (
+    _record_upstream_reasoning_replay_rejection as _record_upstream_reasoning_replay_rejection,
+)
+from app.modules.proxy._service.observability import (
+    _summarize_input as _summarize_input,
+)
+from app.modules.proxy._service.observability import (
+    _tools_hash as _tools_hash,
+)
+from app.modules.proxy._service.observability import (
+    _truncate_identifier as _truncate_identifier,
+)
+from app.modules.proxy._service.streaming.protocol import _StreamingServiceProtocol
+from app.modules.proxy._service.support import (
+    _HARD_HTTP_BRIDGE_AFFINITY_KINDS,  # noqa: F401
+    _REQUEST_TRANSPORT_WEBSOCKET,  # noqa: F401
+    _WEBSOCKET_FULL_REPLAY_WAIT_MIN_ITEMS,  # noqa: F401
+    _WEBSOCKET_FULL_REPLAY_WAIT_POLL_SECONDS,  # noqa: F401
+    _event_type_from_payload,
+    _RequestLogFailureMetadata,
+    _signal_propagated_capacity_startup_ready,
+    _StreamSettlement,
+    _WebSocketRequestState,
+)
+from app.modules.proxy._service.support import (
+    _HTTPBridgeOwnerForward as _HTTPBridgeOwnerForward,
+)
+from app.modules.proxy._service.support import (
+    _record_websocket_route_metadata as _record_websocket_route_metadata,
+)
+from app.modules.proxy._service.support import (
+    _websocket_route_log_kwargs as _websocket_route_log_kwargs,
+)
+from app.modules.proxy._service.warmup import (
+    WarmupExecutionData as WarmupExecutionData,
+)
+from app.modules.proxy._service.warmup import (
+    WarmupFailedAccountData as WarmupFailedAccountData,
+)
+from app.modules.proxy._service.warmup import (
+    WarmupSkippedAccountData as WarmupSkippedAccountData,
+)
+from app.modules.proxy._service.warmup import (
+    WarmupSubmittedAccountData as WarmupSubmittedAccountData,
+)
+from app.modules.proxy._service.warmup import (
+    _is_warmup_usage_eligible as _is_warmup_usage_eligible,
+)
+from app.modules.proxy._service.warmup import (
+    _materialize_warmup_account as _materialize_warmup_account,
+)
+from app.modules.proxy._service.warmup import (
+    _snapshot_warmup_account as _snapshot_warmup_account,
+)
+from app.modules.proxy._service.warmup import (
+    _WarmupAccountSnapshot as _WarmupAccountSnapshot,
+)
+from app.modules.proxy._service.warmup import (
+    _WarmupSubmitResult as _WarmupSubmitResult,
+)
+from app.modules.proxy._service.warmup import (
+    _WarmupUsageSnapshot as _WarmupUsageSnapshot,
+)
+from app.modules.proxy._service.websocket.helpers import (
+    _app_error_to_websocket_event,  # noqa: F401
+    _assign_websocket_response_id,  # noqa: F401
+    _draining_websocket_request_states,  # noqa: F401
+    _find_websocket_request_state_by_response_id,  # noqa: F401
+    _is_websocket_previous_response_output_item,  # noqa: F401
+    _is_websocket_response_create,  # noqa: F401
+    _match_websocket_request_state_for_anonymous_event,  # noqa: F401
+    _match_websocket_request_state_for_precreated_terminal_event,  # noqa: F401
+    _match_websocket_request_state_for_previous_response_error,  # noqa: F401
+    _matching_websocket_request_states_for_missing_tool_output_error,  # noqa: F401
+    _matching_websocket_request_states_for_previous_response_error,  # noqa: F401
+    _maybe_rewrite_websocket_previous_response_not_found_event,  # noqa: F401
+    _parse_websocket_payload,  # noqa: F401
+    _pop_matching_websocket_request_states,  # noqa: F401
+    _pop_replayable_precreated_websocket_request_state,  # noqa: F401
+    _pop_terminal_websocket_request_state,  # noqa: F401
+    _prepare_websocket_request_state_for_auth_replay,  # noqa: F401
+    _prepare_websocket_request_state_for_visible_output_replay,  # noqa: F401
+    _record_websocket_continuity_completion,  # noqa: F401
+    _refresh_websocket_request_input_fingerprint_from_text,  # noqa: F401
+    _release_websocket_response_create_gate,  # noqa: F401
+    _rewrite_websocket_continuity_corruption_event,  # noqa: F401
+    _rewrite_websocket_downstream_response_id,  # noqa: F401
+    _rewrite_websocket_previous_response_owner_unavailable_event,  # noqa: F401
+    _rewrite_websocket_suppressed_duplicate_tool_call_completion_event,  # noqa: F401
+    _sanitize_websocket_connect_failure,  # noqa: F401
+    _sanitize_websocket_previous_response_error,  # noqa: F401
+    _sanitize_websocket_terminal_error_fields,  # noqa: F401
+    _serialize_websocket_error_event,  # noqa: F401
+    _trim_websocket_previous_response_input_items,  # noqa: F401
+    _upstream_websocket_disconnect_message,  # noqa: F401
+    _websocket_auth_failure_permanent_code,  # noqa: F401
+    _websocket_auth_failure_requires_reauth,  # noqa: F401
+    _websocket_auth_request_can_switch_account,  # noqa: F401
+    _websocket_client_previous_response_full_resend_is_retry_safe,  # noqa: F401
+    _websocket_connect_deadline,  # noqa: F401
+    _websocket_continuity_anchor_for_payload,  # noqa: F401
+    _websocket_continuity_error_fields,  # noqa: F401
+    _websocket_continuity_response_ids,  # noqa: F401
+    _websocket_downstream_response_id,  # noqa: F401
+    _websocket_event_error_code,  # noqa: F401
+    _websocket_event_error_message,  # noqa: F401
+    _websocket_event_error_param,  # noqa: F401
+    _websocket_event_error_payload,  # noqa: F401
+    _websocket_event_error_type,  # noqa: F401
+    _websocket_full_resend_conflicts_with_visible_pending,  # noqa: F401
+    _websocket_input_item_type,  # noqa: F401
+    _websocket_owner_pinned_quota_error_code,  # noqa: F401
+    _websocket_precreated_auth_error_code,  # noqa: F401
+    _websocket_precreated_retry_error_code,  # noqa: F401
+    _websocket_receive_timeout_for_pending_requests,  # noqa: F401
+    _websocket_response_id,  # noqa: F401
+    _websocket_top_level_error_payload,  # noqa: F401
+    _wrapped_websocket_error_event,  # noqa: F401
+)
+from app.modules.proxy.affinity import (
+    _sticky_key_from_session_header,  # noqa: F401
+)
+from app.modules.proxy.durable_bridge_coordinator import (
+    DurableBridgeLookup as DurableBridgeLookup,
+)
+from app.modules.proxy.helpers import (
+    _normalize_error_code,
+    classify_upstream_failure,
+    is_account_neutral_safety_policy_rejection,
+    is_model_scoped_upstream_rejection,
+    is_upstream_model_capacity_error,
+    is_upstream_usage_limit_rejection,
+)
+from app.modules.proxy.http_bridge_forwarding import (
+    HTTPBridgeForwardContext as HTTPBridgeForwardContext,
+)
+from app.modules.proxy.http_bridge_forwarding import (
+    OwnerForwardRelayFailure as OwnerForwardRelayFailure,
+)
+from app.modules.proxy.load_balancer import AccountSelection
+from app.modules.usage.updater import UsageUpdater
+
+
+def _facade() -> Any:
+    return sys.modules["app.modules.proxy.service"]
+
+
+def _canonical_background_ack(
+    event_payload: dict[str, JsonValue] | None,
+    event_type: str | None,
+) -> tuple[str, OpenAIResponsePayload] | None:
+    if event_type not in {"response.queued", "response.in_progress"}:
+        return None
+    response = event_payload.get("response") if event_payload is not None else None
+    response_id = response.get("id") if isinstance(response, dict) else None
+    if not (
+        isinstance(response, dict)
+        and response.get("object") == "response"
+        and isinstance(response_id, str)
+        and bool(response_id)
+        and response_id == response_id.strip()
+        and response.get("status") == event_type.removeprefix("response.")
+        and response.get("output") == []
+    ):
+        return None
+    # The relayed payload model drops known submodels that fail validation
+    # instead of raising, so a malformed `usage` or `error` would otherwise be
+    # discarded silently on a response classified as successful.
+    payload = OpenAIResponsePayload.model_validate(response)
+    if (response.get("usage") is None) != (payload.usage is None):
+        return None
+    if (response.get("error") is None) != (payload.error is None):
+        return None
+    return response_id, payload
+
+
+def _canonical_background_ack_response_id(
+    event_payload: dict[str, JsonValue] | None,
+    event_type: str | None,
+) -> str | None:
+    canonical_ack = _canonical_background_ack(event_payload, event_type)
+    return canonical_ack[0] if canonical_ack is not None else None
+
+
+def _is_background_json_ack(
+    stream: bool | None,
+    event_payload: dict[str, JsonValue] | None,
+    event_type: str | None,
+) -> bool:
+    return stream is False and _canonical_background_ack_response_id(event_payload, event_type) is not None
+
+
+def _publish_http_response_owner(
+    proxy: _StreamingServiceProtocol,
+    event: OpenAIEvent | None,
+    event_payload: dict[str, JsonValue] | None,
+    block: str,
+    account_id: str,
+    api_key: ApiKeyData | None,
+    session_id: str | None,
+) -> None:
+    if event is None or event.response is None or not event.response.id or event_payload is None:
+        return
+    if isinstance(block, ParsedSseBlock) and (block.is_local or block.response_id_is_local):
+        return
+    if event_payload.get(SYNTHETIC_TRANSPORT_FAILURE_MARKER):
+        return
+    proxy._remember_websocket_previous_response_owner(
+        previous_response_id=event.response.id,
+        api_key_id=api_key.id if api_key is not None else None,
+        account_id=account_id,
+        session_id=session_id,
+    )
+
+
+def _settle_background_ack(
+    settlement: _StreamSettlement,
+    payload: ResponsesRequest,
+    event_payload: dict[str, JsonValue] | None,
+    response_id: str,
+) -> tuple[bool, str, ResponseUsage | None]:
+    """Treat a canonical background acknowledgement as the terminal event of a `stream: false` request."""
+    canonical_ack = (
+        _canonical_background_ack(event_payload, classify_event_type(event_payload))
+        if payload.stream is False
+        else None
+    )
+    if canonical_ack is None:
+        return False, response_id, None
+    ack_response_id, ack_payload = canonical_ack
+    settlement.response_id = ack_response_id
+    return True, ack_response_id, ack_payload.usage
+
+
+def _stream_iterator_after_capacity_admission(
+    stream: AsyncIterator[str],
+) -> AsyncIterator[str]:
+    """Expose a slow stream once local response-create admission has succeeded."""
+    _signal_propagated_capacity_startup_ready()
+    return stream.__aiter__()
+
+
+_REQUEST_TRANSPORT_HTTP = "http"
+
+
+def _should_penalize_stream_error(code: str | None, message: str | None = None) -> bool:
+    """Whether this stream failure owes the account a health write.
+
+    ``message`` is the sentence the failure carried, and every caller that
+    reads an upstream-authored one passes it: the code table cannot answer for
+    the serialized usage-limit rejection, which upstream sends with no error
+    code at all. That frame normalizes to ``upstream_error``, which is in
+    neither code set, so an account that just said its subscription window is
+    spent would be left ACTIVE and handed the next request -- while the
+    identical coded frame benches it.
+
+    Callers whose message is proxy-authored rather than upstream's own (the
+    WebSocket terminal-cleanup path, whose codes and sentences are this
+    proxy's: ``client_disconnected``, ``stream_incomplete``, an idle timeout)
+    pass no message and keep the pure code answer, because there is nothing of
+    upstream's there to read.
+    """
+    if code is None:
+        return False
+    should_penalize = (
+        code in _facade()._ACCOUNT_RECOVERY_RETRY_CODES
+        or code in _facade()._TRANSIENT_RETRY_CODES
+        or is_upstream_usage_limit_rejection(error_code=code, message=message)
+    )
+    if not should_penalize and _is_account_neutral_request_rejection(
+        code=code,
+        http_status=None,
+        message=message,
+    ):
+        _facade().logger.info(
+            "Skipped account error penalty for account-neutral request rejection code=%s request_id=%s",
+            code,
+            get_request_id(),
+        )
+    return should_penalize
+
+
+_MODEL_CAPACITY_LIMIT_CODES = {
+    "rate_limit_exceeded",
+    "usage_limit_reached",
+    "insufficient_quota",
+    "usage_not_included",
+    "quota_exceeded",
+}
+
+
+def _should_retry_transient_stream_error(
+    code: str | None,
+    message: str | None,
+    *,
+    response_id: str | None = None,
+) -> bool:
+    if code is None or code == "stream_idle_timeout":
+        return False
+    if code == PROCESS_NETWORK_UNAVAILABLE_CODE:
+        # Serialized terminal events arrive only after upstream dispatch. The
+        # stable code keeps settlement account-neutral, but cannot prove that
+        # replaying the POST is safe.
+        return False
+    if response_id is not None:
+        return False
+    if code in _facade()._TRANSIENT_RETRY_CODES:
+        return True
+    if is_upstream_model_capacity_error(message):
+        if code in _MODEL_CAPACITY_LIMIT_CODES:
+            return False
+        return True
+    if code != "upstream_unavailable" or not message:
+        return False
+    normalized_message = message.lower()
+    if any(marker in normalized_message for marker in _facade()._UPSTREAM_UNAVAILABLE_NON_TRANSIENT_MESSAGE_MARKERS):
+        return False
+    return any(marker in normalized_message for marker in _facade()._UPSTREAM_UNAVAILABLE_TRANSIENT_MESSAGE_MARKERS)
+
+
+def _classify_upstream_close(
+    close_code: int | None,
+    *,
+    response_events_seen: int,
+) -> Literal["clean", "transient"]:
+    if close_code == 1000 and response_events_seen == 0:
+        # A clean websocket close before response.created does not prove that
+        # the request was invalid.  The upstream can close a socket during a
+        # handoff, so the caller may safely recreate the socket and replay the
+        # still-unstarted request once.
+        return "clean"
+    return "transient"
+
+
+def _is_account_neutral_transport_drop(
+    close_code: int | None,
+    *,
+    response_events_seen: int,
+) -> bool:
+    """Return whether an upstream websocket ending is account-neutral evidence.
+
+    An abrupt transport drop that carries no close frame and arrived before
+    any application-layer response event is the weakest possible evidence of
+    account ill-health: the account never spoke at the application layer for
+    this request. Charging the account lets a few infrastructure resets push
+    it into error backoff and 502 continuity-bound follow-ups while healthy
+    pool siblings idle (issue #1754). Any close frame — even a non-clean one —
+    is upstream-authored evidence and keeps the existing penalty semantics, as
+    does a drop after response events started streaming.
+
+    Close code 1006 (abnormal closure) is reserved by RFC 6455 and can never
+    appear in an actual close frame: adapters synthesize it locally when the
+    socket dies without one (aiohttp stores 1006 on ``close_code`` for an
+    abnormal CLOSED), so it counts as frame-less here.
+    """
+
+    return close_code in (None, 1006) and response_events_seen == 0
+
+
+def _should_infer_upstream_status_from_proxy_error(exc: ProxyResponseError, upstream_error_code: str | None) -> bool:
+    if exc.failure_phase == "status":
+        return True
+    if exc.failure_phase is not None:
+        return False
+    return upstream_error_code not in _facade()._LOCAL_PROXY_ERROR_CODES
+
+
+def _rewrite_previous_response_stream_error(
+    *,
+    previous_response_id: str | None,
+    preferred_account_id: str | None,
+    error_code: str | None,
+    error_type: str | None,
+    error_message: str | None,
+    error_param: OpenAIErrorParam | JsonValue,
+) -> tuple[str, str, str | None] | None:
+    if previous_response_id is None:
+        return None
+    if _facade()._is_previous_response_not_found_error(
+        code=error_code,
+        param=error_param,
+        message=error_message,
+    ):
+        _record_continuity_fail_closed(
+            surface="http_stream",
+            reason="previous_response_not_found",
+            previous_response_id=previous_response_id,
+            upstream_error_code=error_code,
+        )
+        return (
+            "stream_incomplete",
+            PREVIOUS_RESPONSE_STREAM_INCOMPLETE_MESSAGE,
+            None,
+        )
+    if _facade()._is_missing_tool_output_error(
+        code=error_code,
+        param=error_param,
+        message=error_message,
+    ):
+        _record_continuity_fail_closed(
+            surface="http_stream",
+            reason="missing_tool_output",
+            previous_response_id=previous_response_id,
+            upstream_error_code=error_code,
+        )
+        return (
+            "stream_incomplete",
+            PREVIOUS_RESPONSE_STREAM_INCOMPLETE_MESSAGE,
+            None,
+        )
+    if _facade()._is_previous_response_not_found_public_shape(
+        code=error_code,
+        param=error_param,
+        message=error_message,
+    ):
+        # Preserve masking when malformed ``param`` metadata makes the
+        # recovery classifier fail closed. This branch never authorizes
+        # replay or account switching.
+        _record_continuity_fail_closed(
+            surface="http_stream",
+            reason=PREVIOUS_RESPONSE_MALFORMED_PARAM_REASON,
+            previous_response_id=previous_response_id,
+            upstream_error_code=error_code,
+        )
+        return (
+            "stream_incomplete",
+            PREVIOUS_RESPONSE_STREAM_INCOMPLETE_MESSAGE,
+            None,
+        )
+    normalized_code = _normalize_error_code(error_code, error_type)
+    if preferred_account_id is not None and normalized_code in _facade()._ACCOUNT_RECOVERY_RETRY_CODES:
+        _record_continuity_fail_closed(
+            surface="http_stream",
+            reason="owner_account_unavailable",
+            previous_response_id=previous_response_id,
+            upstream_error_code=normalized_code,
+        )
+        return (
+            "previous_response_owner_unavailable",
+            "Previous response owner account is unavailable; retry later.",
+            normalized_code,
+        )
+    return None
+
+
+def _raw_stream_error_fields(
+    event_type: str | None,
+    event_payload: dict[str, JsonValue] | None,
+) -> tuple[str | None, str | None, OpenAIErrorParam | None, str]:
+    raw_error_type = _websocket_event_error_type(event_type, event_payload)
+    raw_error_message = _websocket_event_error_message(event_type, event_payload)
+    raw_error_param = _websocket_event_error_param(event_type, event_payload)
+    return (
+        raw_error_type,
+        raw_error_message,
+        raw_error_param,
+        _normalize_error_code(_websocket_event_error_code(event_type, event_payload), raw_error_type),
+    )
+
+
+def _openai_error_fields(
+    error: OpenAIError | None,
+) -> tuple[str | None, str | None, OpenAIErrorParam | None]:
+    if error is None:
+        return None, None, None
+    return error.type, error.message, error.param_state
+
+
+def _raw_stream_error_code_or_upstream(
+    event_type: str | None,
+    event_payload: dict[str, JsonValue] | None,
+    error_code: str,
+) -> str:
+    if (
+        event_type == "error"
+        and error_code == "error"
+        and _websocket_event_error_code(event_type, event_payload) is None
+    ):
+        return "upstream_error"
+    return error_code
+
+
+def _classify_terminal_stream_error_frame(
+    event_type: str | None,
+    event_payload: dict[str, JsonValue] | None,
+    error_code: str,
+    error_message: str | None,
+) -> str:
+    """Resolve a terminal frame's error code and record its observability in one step.
+
+    ``streaming/mixin.py`` sits at its line ceiling, so the two parsed
+    terminal-frame sites resolve the code (``_raw_stream_error_code_or_upstream``)
+    and observe the frame (``_observe_terminal_stream_error_frame``) through
+    this single call instead of one statement each.
+    """
+    resolved_code = _raw_stream_error_code_or_upstream(event_type, event_payload, error_code)
+    _observe_terminal_stream_error_frame(resolved_code, error_message)
+    return resolved_code
+
+
+def _mark_stream_settlement_interrupted(
+    settlement: _StreamSettlement,
+    *,
+    status: str,
+    error_code: str,
+    error_message: str,
+    failure_phase: Literal["upstream", "downstream"],
+    failure_detail: str,
+    account_health_error: bool,
+) -> tuple[str, str, str, _RequestLogFailureMetadata]:
+    settlement.record_success = False
+    settlement.account_health_error = account_health_error
+    settlement.error = {"message": error_message}
+    return (
+        status,
+        error_code,
+        error_message,
+        _RequestLogFailureMetadata(failure_phase=failure_phase, failure_detail=failure_detail),
+    )
+
+
+def _stamp_terminal(settlement: _StreamSettlement, event_type: str | None, clock: Clock) -> bool:
+    """Return whether ``event_type`` is an upstream terminal frame, stamping its parse instant on the settlement.
+
+    Called at the HTTP stream's terminal-detection sites before the frame is
+    yielded downstream, so the throughput cohort sample's span ends when the
+    upstream finished generating, not when a slow downstream consumer drained
+    the frame or the upstream connection finally closed.
+    """
+    if event_type not in {"response.completed", "response.failed", "response.incomplete", "error"}:
+        return False
+    settlement.upstream_terminal_at = clock.monotonic()
+    return True
+
+
+def _upstream_terminal_latency_ms(settlement: _StreamSettlement, started_at: float) -> int | None:
+    """Attempt-start-to-upstream-terminal latency for the request-log funnel; ``None`` without a terminal stamp."""
+    if settlement.upstream_terminal_at is None:
+        return None
+    return max(0, int((settlement.upstream_terminal_at - started_at) * 1000))
+
+
+def _mark_upstream_stream_incomplete(
+    settlement: _StreamSettlement,
+) -> tuple[str, str, str, _RequestLogFailureMetadata]:
+    return _mark_stream_settlement_interrupted(
+        settlement,
+        status="error",
+        error_code="stream_incomplete",
+        error_message="Upstream stream ended before response.completed",
+        failure_phase="upstream",
+        failure_detail="upstream_eof_before_terminal_event",
+        account_health_error=True,
+    )
+
+
+def _mark_downstream_stream_cancelled(
+    settlement: _StreamSettlement,
+) -> tuple[str, str, str, _RequestLogFailureMetadata]:
+    return _mark_stream_settlement_interrupted(
+        settlement,
+        status="cancelled",
+        error_code="client_disconnected",
+        error_message="Downstream client disconnected before response.completed",
+        failure_phase="downstream",
+        failure_detail="client_disconnected_before_terminal_event",
+        account_health_error=False,
+    )
+
+
+def _rewrite_malformed_stream_error_event(
+    *,
+    enforce_openai_sdk_contract: bool,
+    event: OpenAIEvent | None,
+    event_type: str | None,
+    event_payload: dict[str, JsonValue] | None,
+    response_id: str,
+) -> tuple[str, OpenAIEvent | None, dict[str, JsonValue] | None, str | None] | None:
+    """Rewrite a schema-less upstream ``error`` frame under the SDK contract.
+
+    A malformed frame like ``{"type":"error","message":"..."}`` classifies as
+    ``error`` but carries no error envelope (``event`` is None or has no
+    ``error``), so it must become a terminal ``response.failed`` instead of
+    leaking the raw frame with a success settlement. Returns None when the
+    frame is not a malformed error (well-formed errors keep their
+    envelope-driven handling).
+    """
+    if not enforce_openai_sdk_contract or event_type != "error":
+        return None
+    if (event is not None and event.error is not None) or not isinstance(event_payload, dict):
+        return None
+    message_value = event_payload.get("message")
+    message = message_value.strip() if isinstance(message_value, str) and message_value.strip() else "Upstream error"
+    return _build_rewritten_stream_response_failed_event(
+        response_id=response_id,
+        error_code="upstream_error",
+        error_message=message,
+    )
+
+
+def _build_rewritten_stream_response_failed_event(
+    *,
+    response_id: str,
+    error_code: str,
+    error_message: str,
+) -> tuple[str, OpenAIEvent | None, dict[str, JsonValue] | None, str | None]:
+    rewritten_event_payload = response_failed_event(
+        error_code,
+        error_message,
+        error_type="server_error",
+        response_id=response_id,
+    )
+    if error_code in SYNTHETIC_TRANSPORT_FAILURE_CODES:
+        rewritten_event_payload = synthetic_transport_failure_event(rewritten_event_payload)
+    rewritten_event_block = format_sse_event(rewritten_event_payload)
+    rewritten_payload = parse_sse_data_json(rewritten_event_block)
+    rewritten_event = parse_sse_event(rewritten_event_block)
+    rewritten_event_type = _event_type_from_payload(rewritten_event, rewritten_payload)
+    return rewritten_event_block, rewritten_event, rewritten_payload, rewritten_event_type
+
+
+def _stream_transport_failure_event_or_raise(
+    error_code: str,
+    error_message: str,
+    *,
+    response_id: str,
+    preserve_native_failure_lifecycle: bool,
+) -> str:
+    if preserve_native_failure_lifecycle:
+        raise ProxyResponseError(
+            502,
+            openai_error(error_code, error_message),
+            failure_phase="upstream",
+        )
+    return format_sse_event(synthetic_stream_failure_event(error_code, error_message, response_id=response_id))
+
+
+def _build_stream_incomplete_terminal_event_for_request(
+    request_state: _WebSocketRequestState,
+    *,
+    reason: str = "stream_incomplete",
+) -> tuple[str, str, OpenAIEvent | None, dict[str, JsonValue] | None, str | None]:
+    error_code, error_message = _websocket_continuity_error_fields(
+        reason=reason,
+        expose_stale_previous_response_classifier=request_state.expose_stale_previous_response_classifier,
+    )
+    event_block, event, payload, event_type = _build_rewritten_stream_response_failed_event(
+        response_id=_websocket_downstream_response_id(request_state),
+        error_code=error_code,
+        error_message=error_message,
+    )
+    if payload is None:  # pragma: no cover - formatter/parser contract
+        raise RuntimeError("rewritten stream failure event did not contain a JSON payload")
+    downstream_text = json.dumps(
+        payload,
+        ensure_ascii=True,
+        separators=(",", ":"),
+    )
+    return downstream_text, event_block, event, payload, event_type
+
+
+def _slim_response_create_payload_for_upstream(
+    payload: dict[str, JsonValue],
+    *,
+    max_bytes: int,
+    protected_agent_control_output_occurrences: Mapping[tuple[str, str], tuple[bool, ...]] | None = None,
+) -> tuple[dict[str, JsonValue], dict[str, int] | None]:
+    input_value = payload.get("input")
+    if not isinstance(input_value, list) or not input_value:
+        return payload, None
+
+    input_items = cast(list[JsonValue], deepcopy(input_value))
+    preserve_from = _facade()._response_create_recent_suffix_start(input_items)
+    historical = input_items[:preserve_from]
+    recent = input_items[preserve_from:]
+
+    tool_outputs_slimmed = 0
+    images_slimmed = 0
+    if protected_agent_control_output_occurrences is None:
+        protected_agent_control_output_occurrences = _agent_control_tool_output_occurrences(historical)
+    agent_control_output_counts: dict[tuple[str, str], int] = {}
+
+    slimmed_historical: list[JsonValue] = []
+    for item in historical:
+        (
+            slimmed_item,
+            item_tool_outputs_slimmed,
+            item_images_slimmed,
+        ) = _facade()._slim_historical_response_input_item(
+            item,
+            protected_agent_control_output_occurrences=protected_agent_control_output_occurrences,
+            agent_control_output_counts=agent_control_output_counts,
+        )
+        tool_outputs_slimmed += item_tool_outputs_slimmed
+        images_slimmed += item_images_slimmed
+        slimmed_historical.append(slimmed_item)
+
+    candidate_payload = dict(payload)
+    candidate_payload["input"] = slimmed_historical + recent
+
+    if tool_outputs_slimmed == 0 and images_slimmed == 0:
+        return payload, None
+
+    return candidate_payload, {
+        "historical_tool_outputs_slimmed": tool_outputs_slimmed,
+        "historical_images_slimmed": images_slimmed,
+    }
+
+
+def _call_stream_with_supported_optional_kwargs(
+    func: Callable[..., AsyncIterator[str]],
+    /,
+    *args: Any,
+    optional_kwargs: Mapping[str, Any],
+    **required_kwargs: Any,
+) -> AsyncIterator[str]:
+    return func(*args, **_facade()._supported_optional_kwargs(func, optional_kwargs, required_kwargs))
+
+
+def _stream_request_budget_seconds(settings: object, *, request_transport: str) -> float:
+    del request_transport
+    budget = getattr(settings, "http_responses_stream_request_budget_seconds", None)
+    if budget is not None:
+        return float(budget)
+    return float(getattr(settings, "proxy_request_budget_seconds"))
+
+
+async def _resolve_upstream_route_for_account(
+    proxy: Any,
+    account: Account,
+    *,
+    operation: str,
+) -> ResolvedUpstreamRoute | None:
+    # Outcomes (route / direct-egress None / fail-closed error) are cached
+    # verbatim, so a hit can never change the degradation path the resolver
+    # chose; errors re-raise with their original reason.
+    cache = get_upstream_route_cache()
+    cached = cache.get(account.id)
+    if cached is not None:
+        return cached.unwrap(account.id)
+    generation = cache.generation
+    async with _facade().SessionLocal() as session:
+        try:
+            route = await _facade().resolve_upstream_route(
+                session,
+                account_id=account.id,
+                operation=operation,
+                scope="account",
+                encryptor=proxy._encryptor,
+            )
+        except UpstreamProxyRouteError as exc:
+            cache.store_error(account.id, exc, generation=generation)
+            raise
+    cache.store_route(account.id, route, generation=generation)
+    return route
+
+
+async def _select_account_with_budget_for_stream(proxy: Any, deadline: float, **kwargs: Any) -> AccountSelection:
+    selector = proxy._select_account_with_budget_compatible
+    optional_kwargs = (
+        "require_security_work_authorized",
+        "lease_kind",
+        "estimated_lease_tokens",
+        "fallback_on_preferred_account_unavailable",
+        "preferred_account_is_continuity_owner",
+        "preferred_account_overrides_single_account_routing",
+        "spill_bare_session_on_account_cap",
+        "require_unambiguous_account",
+    )
+    if any(name in kwargs for name in optional_kwargs):
+        try:
+            signature = inspect.signature(selector)
+        except (TypeError, ValueError):
+            signature = None
+        accepts_var_keyword = signature is not None and any(
+            parameter.kind is inspect.Parameter.VAR_KEYWORD for parameter in signature.parameters.values()
+        )
+        if signature is not None and not accepts_var_keyword:
+            kwargs = dict(kwargs)
+            for name in optional_kwargs:
+                if name not in signature.parameters:
+                    kwargs.pop(name, None)
+    return await selector(deadline, **kwargs)
+
+
+def _is_account_neutral_request_rejection(
+    *,
+    code: str,
+    http_status: int | None,
+    message: str | None,
+) -> bool:
+    """Return whether upstream rejected the request payload, not the account.
+
+    An account-neutral request rejection reproduces identically on every
+    account, so it must never mutate one account's health: otherwise a single
+    client looping on a rejected conversation drives its serving accounts into
+    ``error_count`` backoff and starves unrelated tenants.
+
+    Keep this set narrow: membership is decided by the specific classified
+    code and message, never by a broad HTTP status alone. The model-entitlement
+    rejection is deliberately not a member -- it is handled by
+    ``_is_model_scoped_rejection`` below, which likewise keeps the account's
+    health untouched but still lets failover try accounts whose entitlements
+    may differ.
+    """
+    if http_status is not None and http_status != 400:
+        return False
+    if is_account_neutral_safety_policy_rejection(code=code, http_status=http_status, message=message):
+        return True
+    return code == "invalid_request_error" and bool(_facade()._is_missing_tool_output_message(message))
+
+
+def _is_model_scoped_rejection(
+    *,
+    http_status: int | None,
+    message: str | None,
+) -> bool:
+    """Return whether upstream rejected the requested model, not the account.
+
+    The ChatGPT model-entitlement rejection is scoped to the model named in the
+    message. It proves nothing about the account's ability to serve the models
+    it *is* entitled to, so it must never move that account's ``error_count``:
+    otherwise one client looping on a model no account can serve drives every
+    serving account into ``ERROR_BACKOFF_THRESHOLD`` backoff and starves all
+    unrelated traffic on those accounts -- the exact failure mode when a model
+    reaches subscription selection because its OpenAI-compatible model source
+    is disabled or unreachable.
+
+    Failover is deliberately untouched: the classified failure is still
+    returned, so the caller keeps trying other accounts, whose entitlements may
+    differ.
+
+    The normalized code is not part of the match. Upstream delivers this
+    rejection with neither ``code`` nor ``type`` on the streaming path, which
+    normalizes to ``upstream_error``; on other paths it arrives as
+    ``invalid_request_error``. Only the exact message shape decides membership.
+    """
+    if http_status is not None and http_status != 400:
+        return False
+    return is_model_scoped_upstream_rejection(message)
+
+
+def _request_usage_refresh(proxy: Any, account_id: str) -> None:
+    """Schedule a tracked, coalesced usage refresh after a streamed ``usage_limit_reached``.
+
+    ``mark_rate_limit`` persists status only, while the pool-exhaustion
+    predicate also needs a >= 100 % usage row that would otherwise wait for
+    the next scheduler tick. The refresh runs on its own background session
+    and never touches this request's ``Account``.
+    """
+    schedule = getattr(proxy, "_schedule_cancel_safe_cleanup", None)
+    if schedule is None:
+        return
+    refresh = UsageUpdater.request_refresh(account_id)
+    if refresh is None:
+        return
+    schedule(refresh, action="request_usage_refresh", request_id=get_request_id() or "unknown")
+
+
+async def _handle_stream_error(
+    proxy: Any,
+    account: Account,
+    error: UpstreamError,
+    code: str,
+    http_status: int | None = None,
+    *,
+    privacy_policy: CodexControlRequestPrivacyPolicy = CodexControlRequestPrivacyPolicy.STANDARD,
+    retry_after_seconds: float | None = None,
+    burst_cooldown_recorded: bool = False,
+    upstream_http_status: int | None = None,
+) -> ClassifiedFailure:
+    """Write account health for a stream failure and return its classification.
+
+    ``burst_cooldown_recorded`` is set by a keyed stream whose health write was
+    deferred until after usage settlement: the replica-local burst cooldown
+    was already engaged at rejection time, so the deferred write must not
+    re-engage it (that would bench an account that has since succeeded).
+
+    ``upstream_http_status`` is evidence-only: it lets a caller that knows the
+    upstream HTTP status of this failure say so WITHOUT taking any of the
+    ``http_status`` side effects. It is read by the soft-overload gate below
+    and by nothing else -- never by ``classify_upstream_failure``, the
+    reasoning-replay metric, the account-neutral / model-scoped rejection
+    predicates, or the HTTP 429 burst-cooldown branch. Callers that want those
+    behaviours must pass the positional ``http_status`` instead.
+    """
+    classified = classify_upstream_failure(
+        error_code=code,
+        error=error,
+        http_status=http_status,
+        phase="first_event",
+    )
+    # Terminal frames are counted where they are classified
+    # (``_observe_terminal_stream_error_frame``); only HTTP status rejections
+    # reach the counter from here, so a failure is never counted twice.
+    if http_status is not None and _is_reasoning_replay_rejection(
+        code=code, http_status=http_status, message=error.get("message")
+    ):
+        _record_upstream_reasoning_replay_rejection()
+    if _facade()._is_account_neutral_error_code(code):
+        return classified
+    if _is_account_neutral_request_rejection(
+        code=code,
+        http_status=http_status,
+        message=error.get("message"),
+    ):
+        _facade().logger.info(
+            "Skipped account error penalty for account-neutral request rejection account_id=%s request_id=%s code=%s",
+            "<redacted>" if privacy_policy.redacts_sensitive_details else account.id,
+            get_request_id(),
+            code,
+        )
+        return classified
+    if _is_model_scoped_rejection(
+        http_status=http_status,
+        message=error.get("message"),
+    ):
+        _facade().logger.info(
+            "Skipped account error penalty for model-scoped upstream rejection account_id=%s request_id=%s code=%s",
+            "<redacted>" if privacy_policy.redacts_sensitive_details else account.id,
+            get_request_id(),
+            code,
+        )
+        return classified
+    if classified["failure_class"] == "rate_limit":
+        await proxy._load_balancer.mark_rate_limit(account, error)
+        # The refresh is owed to the account whose window is spent, and the
+        # literal code is the one piece of that evidence upstream omits at will:
+        # the serialized terminal frame asserts the same limit in its message
+        # alone. Reading only the code leaves the pool's usage picture stale for
+        # exactly the accounts it most needs to be current about. Plain
+        # throttling still asks for nothing.
+        if is_upstream_usage_limit_rejection(error_code=code, message=error.get("message")):
+            _request_usage_refresh(proxy, account.id)
+    elif classified["failure_class"] == "quota":
+        await proxy._load_balancer.mark_quota_exceeded(account, error)
+    elif code in PERMANENT_FAILURE_CODES:
+        await proxy._load_balancer.mark_permanent_failure(account, code)
+    else:
+        await proxy._load_balancer.record_error(account)
+        _facade().logger.info(
+            "Recorded transient account error account_id=%s request_id=%s code=%s",
+            "<redacted>" if privacy_policy.redacts_sensitive_details else account.id,
+            get_request_id(),
+            code,
+        )
+        hard_overload = code in UPSTREAM_OVERLOAD_CODES
+        # A bare ``server_error`` *stream terminal* is the same observable
+        # condition as an explicit overload: upstream admitted the turn and then
+        # refused to run it. The terminal shape is what makes it an admission
+        # rejection, so it is keyed on the absence of an HTTP status. A coded
+        # HTTP failure carrying the same string is an ordinary transient error
+        # (and an HTTP 429 is a burst rejection with its own cooldown branch
+        # below); neither may deprioritize an otherwise healthy account.
+        #
+        # Two status keywords are checked because several callers KNOW the
+        # upstream status yet deliberately do not forward it as ``http_status``:
+        # doing so would also flip the account-neutral / model-scoped predicates
+        # above from "skip the penalty" to "record it", arm the 429 branch below,
+        # and double-count the reasoning-replay metric for a frame already
+        # counted at ``_observe_terminal_stream_error_frame``. They pass
+        # ``upstream_http_status`` instead, which gates this window only. A
+        # status from EITHER keyword means the failure was not a status-less
+        # terminal and so must stay out of the soft window.
+        soft_overload = code in UPSTREAM_SOFT_OVERLOAD_CODES and http_status is None and upstream_http_status is None
+        if hard_overload or soft_overload:
+            # Overload is an admission rejection that successes on the same
+            # account's warm sessions keep masking from ``error_count``; feed
+            # the dedicated sliding window so fresh selection can deprioritize.
+            # Soft observations count at a fractional weight, so a sustained
+            # refusal still trips the window while a lone fault never does.
+            await record_upstream_overload(
+                proxy._load_balancer,
+                account,
+                redact_account_id=privacy_policy.redacts_sensitive_details,
+                soft=not hard_overload,
+            )
+        elif http_status == 429 and not burst_cooldown_recorded:
+            # A code-less HTTP 429 (rate_limit / quota classes returned above)
+            # is a per-account burst/concurrency rejection: keyed on the status
+            # so ``server_error`` rewrites and ``detail``-parsed bodies are
+            # covered. Short replica-local cooldown only -- never
+            # ``mark_rate_limit`` / persisted RATE_LIMITED.
+            await record_upstream_burst_rejection(
+                proxy._load_balancer,
+                account,
+                retry_after_seconds=retry_after_seconds,
+                redact_account_id=privacy_policy.redacts_sensitive_details,
+            )
+    return classified
+
+
+def _push_stream_attempt_timeout_overrides(
+    timeout_seconds: float,
+) -> tuple[float | None, float | None, float | None]:
+    return _facade().push_stream_timeout_overrides(
+        connect_timeout_seconds=timeout_seconds,
+        idle_timeout_seconds=timeout_seconds,
+        total_timeout_seconds=timeout_seconds,
+    )
+
+
+def _should_retry_stream_error(code: str, message: str | None = None) -> bool:
+    """Whether a pre-visible terminal frame may be retried on a sibling account.
+
+    The code allowlist cannot answer this for the serialized form of the
+    usage-limit rejection: upstream sends that frame with no error code, which
+    normalizes to ``upstream_error`` and is in no transport retry list -- so a
+    frame saying the account is spent gets surfaced on the first account while
+    the identical HTTP body walks the pool. The frame's sentence is put through
+    the same predicate the health write beside it uses, because that sentence
+    is the only evidence a status-less, code-less frame carries.
+    """
+    return code in _facade()._ACCOUNT_RECOVERY_RETRY_CODES or is_upstream_usage_limit_rejection(
+        error_code=code, message=message
+    )
+
+
+def _upstream_turn_state_from_socket(upstream: UpstreamWebSocket | None) -> str | None:
+    if upstream is None:
+        return None
+    getter = getattr(upstream, "response_header", None)
+    if not callable(getter):
+        return None
+    value = getter("x-codex-turn-state")
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    return stripped or None