Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

fix(model-hub): consume managed engine response headers (#2942)

Call Whited567688717ad
diff --git a/core/handlers/model_hub/adapter.py b/core/handlers/model_hub/adapter.py
index a4c3daace..0919aab72 100644
--- a/core/handlers/model_hub/adapter.py
+++ b/core/handlers/model_hub/adapter.py
@@ -32,6 +32,24 @@ SEARCH_TRANSPORT_TIMEOUT_SECONDS: Final = 30.0
# Response correlation is a diagnostic fact, not a header-forwarding surface. These
# are the only upstream response header names allowed to cross the engine boundary.
RESPONSE_CORRELATION_HEADER_NAMES: Final = frozenset({"request-id", "x-request-id"})
+# Claude's future subscription-cap classifier consumes this closed set. Keep the
+# names lowercase here; the engine/client boundary matches them case-insensitively.
+CLAUDE_UNIFIED_RATE_LIMIT_HEADER_NAMES: Final = frozenset({
+ "anthropic-ratelimit-unified-status",
+ "anthropic-ratelimit-unified-5h-status",
+ "anthropic-ratelimit-unified-7d-status",
+ "anthropic-ratelimit-unified-7d_oi-status",
+ "anthropic-ratelimit-unified-overage-status",
+ "anthropic-ratelimit-unified-overage-disabled-reason",
+ "anthropic-ratelimit-unified-representative-claim",
+ "anthropic-ratelimit-unified-5h-utilization",
+ "anthropic-ratelimit-unified-7d-utilization",
+ "anthropic-ratelimit-unified-5h-reset",
+ "anthropic-ratelimit-unified-7d-reset",
+ "anthropic-ratelimit-unified-7d_oi-reset",
+ "anthropic-ratelimit-unified-reset",
+ "anthropic-ratelimit-unified-overage-reset",
+})
RESPONSE_CORRELATION_ID_MAX_LENGTH: Final = 256
RESPONSE_CORRELATION_ID_MAX_ITEMS: Final = len(RESPONSE_CORRELATION_HEADER_NAMES)
_CORRELATION_ID_CREDENTIAL_PATTERN = re.compile(
@@ -261,8 +279,15 @@ class RawCallOutcome:
# from the error envelope in that header's syntax. L2 owns validation and
# the resulting retry policy.
retry_after: str | None = None
+ # Validated Retry-After-Ms advice. It stays separate from ``retry_after`` so
+ # a millisecond count can never reach code that interprets numeric advice as
+ # whole seconds.
+ retry_after_ms: int | None = field(default=None, repr=False)
# Aware UTC receipt time of those headers, before reading the error body.
response_received_at: datetime | None = None
+ # Exact, bounded Claude unified rate-limit facts for the future #2530
+ # classifier. These never reach an outward response or persisted event.
+ claude_rate_limit_headers: tuple[tuple[str, str], ...] = field(default=(), repr=False)
# Recognized model output or protocol success, independently of permissive
# forwarding. An unrecognized HTTP 200 alone cannot prove Source recovery.
recovery_verified: bool = False
diff --git a/core/handlers/model_hub/retry.py b/core/handlers/model_hub/retry.py
index 36df644f3..d56b5c6cf 100644
--- a/core/handlers/model_hub/retry.py
+++ b/core/handlers/model_hub/retry.py
@@ -50,27 +50,36 @@ def source_identity(source: ModelHubSourceConfig) -> tuple:
)
-def retry_after_deadline(value: str | None, received_at: datetime) -> datetime | None:
- """Validate the bounded advice without reflecting its contents in diagnostics."""
-
- if value is None:
- return None
- try:
- if not isinstance(value, str) or len(value) > 128 or not value.isascii():
- raise ValueError
- value = value.strip()
- if value.isdecimal():
- deadline = received_at + timedelta(seconds=int(value))
- else:
- deadline = parsedate_to_datetime(value)
- if deadline.tzinfo is None:
+def retry_after_deadline(
+ value: str | None,
+ received_at: datetime,
+ *,
+ milliseconds: int | None = None,
+) -> datetime | None:
+ """Validate bounded advice and choose the later valid upstream deadline."""
+
+ deadlines: list[datetime] = []
+ if value is not None:
+ try:
+ if not isinstance(value, str) or len(value) > 128 or not value.isascii():
raise ValueError
- if deadline < received_at:
- raise ValueError
- return deadline
- except (ValueError, TypeError, OverflowError):
- logger.debug("Ignored invalid or past Model Hub Retry-After advice")
- return None
+ value = value.strip()
+ if value.isdecimal():
+ deadlines.append(received_at + timedelta(seconds=int(value)))
+ else:
+ deadline = parsedate_to_datetime(value)
+ if deadline.tzinfo is None:
+ raise ValueError
+ deadlines.append(deadline)
+ except (ValueError, TypeError, OverflowError):
+ logger.debug("Ignored invalid or past Model Hub Retry-After advice")
+ if type(milliseconds) is int and milliseconds >= 0:
+ try:
+ deadlines.append(received_at + timedelta(milliseconds=milliseconds))
+ except (OverflowError, ValueError):
+ logger.debug("Ignored invalid Model Hub Retry-After-Ms advice")
+ future = [deadline for deadline in deadlines if deadline >= received_at]
+ return max(future) if future else None
@dataclass
@@ -251,6 +260,7 @@ class RecoveryPolicy:
*,
generation: int,
retry_after: str | None = None,
+ retry_after_ms: int | None = None,
response_received_at: datetime | None = None,
) -> tuple[datetime, bool]:
state = self._state(source)
@@ -264,7 +274,11 @@ class RecoveryPolicy:
received = response_received_at
if received is None or received.tzinfo is None:
received = now
- upstream = retry_after_deadline(retry_after, received)
+ upstream = retry_after_deadline(
+ retry_after,
+ received,
+ milliseconds=retry_after_ms,
+ )
deadline = max(now + timedelta(seconds=local), upstream or now)
eligible_at = mono + (deadline - now).total_seconds()
if state is not None:
diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.py
index 39afbe678..e1752e5f2 100644
--- a/core/handlers/model_hub/service.py
+++ b/core/handlers/model_hub/service.py
@@ -10280,6 +10280,7 @@ class ModelHubService:
current, event_reason,
generation=generation,
retry_after=outcome.retry_after if outcome is not None else None,
+ retry_after_ms=getattr(outcome, "retry_after_ms", None) if outcome is not None else None,
response_received_at=outcome.response_received_at if outcome is not None else None,
)
if not changed:
diff --git a/docs/plans/model-hub-contracts/adapter-interface.py b/docs/plans/model-hub-contracts/adapter-interface.py
index a4c3daace..0919aab72 100644
--- a/docs/plans/model-hub-contracts/adapter-interface.py
+++ b/docs/plans/model-hub-contracts/adapter-interface.py
@@ -32,6 +32,24 @@ SEARCH_TRANSPORT_TIMEOUT_SECONDS: Final = 30.0
# Response correlation is a diagnostic fact, not a header-forwarding surface. These
# are the only upstream response header names allowed to cross the engine boundary.
RESPONSE_CORRELATION_HEADER_NAMES: Final = frozenset({"request-id", "x-request-id"})
+# Claude's future subscription-cap classifier consumes this closed set. Keep the
+# names lowercase here; the engine/client boundary matches them case-insensitively.
+CLAUDE_UNIFIED_RATE_LIMIT_HEADER_NAMES: Final = frozenset({
+ "anthropic-ratelimit-unified-status",
+ "anthropic-ratelimit-unified-5h-status",
+ "anthropic-ratelimit-unified-7d-status",
+ "anthropic-ratelimit-unified-7d_oi-status",
+ "anthropic-ratelimit-unified-overage-status",
+ "anthropic-ratelimit-unified-overage-disabled-reason",
+ "anthropic-ratelimit-unified-representative-claim",
+ "anthropic-ratelimit-unified-5h-utilization",
+ "anthropic-ratelimit-unified-7d-utilization",
+ "anthropic-ratelimit-unified-5h-reset",
+ "anthropic-ratelimit-unified-7d-reset",
+ "anthropic-ratelimit-unified-7d_oi-reset",
+ "anthropic-ratelimit-unified-reset",
+ "anthropic-ratelimit-unified-overage-reset",
+})
RESPONSE_CORRELATION_ID_MAX_LENGTH: Final = 256
RESPONSE_CORRELATION_ID_MAX_ITEMS: Final = len(RESPONSE_CORRELATION_HEADER_NAMES)
_CORRELATION_ID_CREDENTIAL_PATTERN = re.compile(
@@ -261,8 +279,15 @@ class RawCallOutcome:
# from the error envelope in that header's syntax. L2 owns validation and
# the resulting retry policy.
retry_after: str | None = None
+ # Validated Retry-After-Ms advice. It stays separate from ``retry_after`` so
+ # a millisecond count can never reach code that interprets numeric advice as
+ # whole seconds.
+ retry_after_ms: int | None = field(default=None, repr=False)
# Aware UTC receipt time of those headers, before reading the error body.
response_received_at: datetime | None = None
+ # Exact, bounded Claude unified rate-limit facts for the future #2530
+ # classifier. These never reach an outward response or persisted event.
+ claude_rate_limit_headers: tuple[tuple[str, str], ...] = field(default=(), repr=False)
# Recognized model output or protocol success, independently of permissive
# forwarding. An unrecognized HTTP 200 alone cannot prove Source recovery.
recovery_verified: bool = False
diff --git a/tests/test_model_hub_engine_response_headers.py b/tests/test_model_hub_engine_response_headers.py
index a805aa962..2033722d2 100644
--- a/tests/test_model_hub_engine_response_headers.py
+++ b/tests/test_model_hub_engine_response_headers.py
@@ -20,7 +20,9 @@ from core.handlers.model_hub.turn_gateway import ModelHubTurnGateway
from tests.test_model_hub_declared_tools import COMPLETED, INPUT, _wire
from tests.test_model_hub_l3 import _canonicalize_fixed_test_routes, _service, _source
from vibe.model_hub_runtime.client import (
+ CLAUDE_UNIFIED_RATE_LIMIT_HEADER_NAMES,
ENGINE_RESPONSE_HEADER_ALLOW_LIST,
+ _allowed_claude_rate_limit_headers,
_allowed_engine_header,
)
from core.handlers.model_hub.adapter import sanitize_response_correlation_ids
@@ -31,7 +33,21 @@ INJECTED = {
"Anthropic-Request-Id": "anthropic-request-1",
"Anthropic-Organization-Id": "org-upstream",
"Retry-After-Ms": "1500",
+ "Anthropic-Ratelimit-Unified-Status": "rejected",
+ "Anthropic-Ratelimit-Unified-5h-Status": "rejected",
+ "Anthropic-Ratelimit-Unified-7d-Status": "allowed",
+ "Anthropic-Ratelimit-Unified-7d_oi-Status": "allowed",
+ "Anthropic-Ratelimit-Unified-Overage-Status": "rejected",
+ "Anthropic-Ratelimit-Unified-Overage-Disabled-Reason": "plan_limit",
+ "Anthropic-Ratelimit-Unified-Representative-Claim": "5h",
+ "Anthropic-Ratelimit-Unified-5h-Utilization": "1.0",
+ "Anthropic-Ratelimit-Unified-7d-Utilization": "0.25",
"Anthropic-Ratelimit-Unified-5h-Reset": "1797000000",
+ "Anthropic-Ratelimit-Unified-7d-Reset": "1798000000",
+ "Anthropic-Ratelimit-Unified-7d_oi-Reset": "1798000000",
+ "Anthropic-Ratelimit-Unified-Reset": "1798000000",
+ "Anthropic-Ratelimit-Unified-Overage-Reset": "1798000000",
+ "Anthropic-Ratelimit-Unified-Unknown": "must-not-cross",
"X-Request-Id": "relay-request-1",
"Request-Id": "provider-request-1",
"X-Upstream-Injected": "1",
@@ -73,11 +89,17 @@ async def _engine(status: int, stream: bool):
def test_only_allowlisted_headers_are_read_from_an_engine_response():
- assert ENGINE_RESPONSE_HEADER_ALLOW_LIST == {"retry-after", "request-id", "x-request-id"}
+ assert ENGINE_RESPONSE_HEADER_ALLOW_LIST == {
+ "retry-after", "retry-after-ms", "request-id", "x-request-id",
+ *CLAUDE_UNIFIED_RATE_LIMIT_HEADER_NAMES,
+ }
headers = {**INJECTED, "Retry-After": "120"}
assert _allowed_engine_header(headers, "Retry-After") == "120"
+ assert _allowed_engine_header({"rEtRy-AfTeR-Ms": "1500"}, "Retry-After-Ms") == "1500"
assert _allowed_engine_header(headers, "Request-Id") == "provider-request-1"
assert _allowed_engine_header(headers, "X-Request-Id") == "relay-request-1"
+ assert _allowed_engine_header(headers, "Anthropic-Ratelimit-Unified-5H-Status") == "rejected"
+ assert _allowed_engine_header(headers, "Anthropic-Ratelimit-Unified-Unknown") is None
assert sanitize_response_correlation_ids(headers) == (
("request-id", "provider-request-1"),
("x-request-id", "relay-request-1"),
@@ -85,6 +107,24 @@ def test_only_allowlisted_headers_are_read_from_an_engine_response():
assert _allowed_engine_header(headers, "Set-Cookie") is None
+def test_claude_unified_headers_are_exactly_projected_and_validated():
+ headers = {
+ "aNtHrOpIc-RaTeLiMiT-UnIfIeD-5h-StAtUs": "REJECTED",
+ "Anthropic-Ratelimit-Unified-5h-Reset": "1797000000",
+ "Anthropic-Ratelimit-Unified-Representative-Claim": "5h",
+ "Anthropic-Ratelimit-Unified-Unknown": "private",
+ "Anthropic-Ratelimit-Unified-7d-Reset": "not-a-date",
+ "Anthropic-Ratelimit-Unified-7d-Status": "rejected\nforged",
+ "Anthropic-Ratelimit-Unified-Overage-Status": "allowed",
+ }
+ assert _allowed_claude_rate_limit_headers(headers) == (
+ ("anthropic-ratelimit-unified-5h-reset", "1797000000"),
+ ("anthropic-ratelimit-unified-5h-status", "rejected"),
+ ("anthropic-ratelimit-unified-overage-status", "allowed"),
+ ("anthropic-ratelimit-unified-representative-claim", "5h"),
+ )
+
+
@pytest.mark.parametrize(
("headers", "expected"),
[
diff --git a/tests/test_model_hub_retry_advice.py b/tests/test_model_hub_retry_advice.py
index 5972dc3c8..c8fd61176 100644
--- a/tests/test_model_hub_retry_advice.py
+++ b/tests/test_model_hub_retry_advice.py
@@ -11,6 +11,7 @@ from aiohttp import web
import pytest
from core.handlers.model_hub.adapter import RawCallOutcome, RawOutcomeKind
+from core.handlers.model_hub.retry import retry_after_deadline
from core.handlers.model_hub.stream_wire import ProtocolUsageReport
from vibe.model_hub_runtime import client as client_module
from vibe.model_hub_runtime.client import EngineClient, EngineConnection
@@ -46,10 +47,10 @@ ERROR_BODY = (
)
-def _source(protocol: str) -> SourceRecord:
+def _source(protocol: str, *, vendor: str = "custom") -> SourceRecord:
return SourceRecord(
source_id="src_retryadvice",
- vendor="custom",
+ vendor=vendor,
protocol=protocol,
base_url="https://unused.example.test",
credential_ref="cred_retryadvice",
@@ -83,13 +84,21 @@ async def _engine(respond, *, timeout: float = 2):
await runner.cleanup()
-async def _invoke(client: EngineClient, protocol: str, stream: bool):
+async def _invoke(
+ client: EngineClient,
+ protocol: str,
+ stream: bool,
+ *,
+ vendor: str = "custom",
+ request_protocol: str | None = None,
+):
cleanups = []
handle = await client.invoke(
- _source(protocol),
+ _source(protocol, vendor=vendor),
"model-a",
{},
stream=stream,
+ request_protocol=request_protocol or protocol,
on_transport_done=lambda: cleanups.append(True),
)
try:
@@ -228,6 +237,123 @@ async def test_only_a_usage_cap_turns_its_body_reset_into_advice(status: int, er
assert outcome.retry_after is None
+ ("raw", "expected"),
+ [
+ pytest.param("1500", 1500, id="milliseconds"),
+ pytest.param("0", 0, id="zero"),
+ pytest.param("-1", None, id="negative"),
+ pytest.param("1.5", None, id="fraction"),
+ pytest.param("12", None, id="nonascii"),
+ pytest.param("9" * 129, None, id="oversized"),
+ pytest.param("9" * 128, None, id="overflow"),
+ pytest.param("", None, id="empty"),
+ ],
+)
+async def test_retry_after_ms_is_validated_without_becoming_retry_after_seconds(raw: str, expected: int | None) -> None:
+ async def respond(_request: web.Request) -> web.Response:
+ return web.Response(
+ status=429,
+ body=ERROR_BODY,
+ headers={"rEtRy-AfTeR-Ms": raw},
+ content_type="application/json",
+ )
+
+ async with _engine(respond) as (client, _requests):
+ outcome, _body = await _invoke(client, "anthropic", False)
+
+ assert outcome.retry_after is None
+ assert outcome.retry_after_ms == expected
+ if expected is not None:
+ assert outcome.response_received_at is not None
+ deadline = retry_after_deadline(
+ None, outcome.response_received_at, milliseconds=expected,
+ )
+ assert deadline is not None
+ assert (deadline - outcome.response_received_at).total_seconds() == expected / 1000
+
+
+async def test_retry_after_and_retry_after_ms_use_the_later_valid_deadline() -> None:
+ async def respond(_request: web.Request) -> web.Response:
+ return web.Response(
+ status=429,
+ body=ERROR_BODY,
+ headers={"Retry-After": "1", "Retry-After-Ms": "2500"},
+ content_type="application/json",
+ )
+
+ async with _engine(respond) as (client, _requests):
+ outcome, _body = await _invoke(client, "anthropic", False)
+
+ assert outcome.retry_after == "1"
+ assert outcome.retry_after_ms == 2500
+ assert outcome.response_received_at is not None
+ deadline = retry_after_deadline(
+ outcome.retry_after,
+ outcome.response_received_at,
+ milliseconds=outcome.retry_after_ms,
+ )
+ assert deadline is not None
+ assert (deadline - outcome.response_received_at).total_seconds() == 2.5
+
+
+async def test_failed_claude_response_carries_only_bounded_unified_headers() -> None:
+ async def respond(_request: web.Request) -> web.Response:
+ return web.Response(
+ status=429,
+ body=ERROR_BODY,
+ headers={
+ "Anthropic-Ratelimit-Unified-Status": "rejected",
+ "Anthropic-Ratelimit-Unified-5h-Reset": "1797000000",
+ "Anthropic-Ratelimit-Unified-Representative-Claim": "5h",
+ "Anthropic-Ratelimit-Unified-7d-Status": "bad",
+ "Anthropic-Ratelimit-Unified-Unknown": "private",
+ "Set-Cookie": "session=secret",
+ },
+ content_type="application/json",
+ )
+
+ async with _engine(respond) as (client, _requests):
+ outcome, _body = await _invoke(
+ client,
+ "anthropic",
+ False,
+ vendor="anthropic",
+ request_protocol="openai_responses",
+ )
+
+ assert outcome.claude_rate_limit_headers == (
+ ("anthropic-ratelimit-unified-5h-reset", "1797000000"),
+ ("anthropic-ratelimit-unified-representative-claim", "5h"),
+ ("anthropic-ratelimit-unified-status", "rejected"),
+ )
+ assert "Set-Cookie" not in repr(outcome)
+
+
+async def test_non_claude_source_does_not_project_unified_headers_for_claude_caller() -> None:
+ async def respond(_request: web.Request) -> web.Response:
+ return web.Response(
+ status=429,
+ body=ERROR_BODY,
+ headers={
+ "Anthropic-Ratelimit-Unified-Status": "rejected",
+ "Anthropic-Ratelimit-Unified-5h-Reset": "1797000000",
+ },
+ content_type="application/json",
+ )
+
+ async with _engine(respond) as (client, _requests):
+ outcome, _body = await _invoke(
+ client,
+ "anthropic",
+ False,
+ vendor="custom",
+ request_protocol="anthropic",
+ )
+
+ assert outcome.claude_rate_limit_headers == ()
+
+
@pytest.mark.parametrize("protocol", WIRE)
@pytest.mark.parametrize("stream", [False, True], ids=["buffered", "streaming"])
@pytest.mark.parametrize("body_mode", ["slow", "timeout", "disconnect", "malformed"])
diff --git a/tests/test_model_hub_retry_policy.py b/tests/test_model_hub_retry_policy.py
index e81512d69..ffcf2004e 100644
--- a/tests/test_model_hub_retry_policy.py
+++ b/tests/test_model_hub_retry_policy.py
@@ -144,7 +144,23 @@ def test_retry_after_uses_response_receipt_and_keeps_long_upstream_advice(tmp_pa
asyncio.run(run())
-def test_offsets_and_wall_clock_shifts_do_not_change_monotonic_admission(tmp_path):
+
+def test_retry_after_ms_reaches_recovery_as_fractional_seconds(tmp_path):
+ async def run():
+ service, clock = clock_service(tmp_path)
+ source = service.store.load().sources[0]
+ outcome = SimpleNamespace(
+ retry_after=None,
+ retry_after_ms=1500,
+ response_received_at=NOW,
+ stream_started=False,
+ )
+ await fail(service, source, "network", outcome=outcome)
+ retry_at = service.recovery.annotations(service.store.load())[source.id].retry_at
+ assert retry_at == (NOW + timedelta(milliseconds=1500)).isoformat()
+
+ asyncio.run(run())
+
async def run():
service, clock = clock_service(tmp_path)
source = service.store.load().sources[0]
diff --git a/vibe/model_hub_runtime/client.py b/vibe/model_hub_runtime/client.py
index e79f522af..5449288ac 100644
--- a/vibe/model_hub_runtime/client.py
+++ b/vibe/model_hub_runtime/client.py
@@ -16,7 +16,7 @@ from collections.abc import Awaitable, Callable
from dataclasses import dataclass, field, replace
from datetime import datetime, timezone
from decimal import Decimal
-from email.utils import format_datetime
+from email.utils import format_datetime, parsedate_to_datetime
from typing import Any, AsyncIterator, BinaryIO, Literal, Mapping, TypeVar, cast
import aiohttp
@@ -24,6 +24,7 @@ import ijson
from config.v2_config import normalize_model_hub_base_url
from core.handlers.model_hub.adapter import (
+ CLAUDE_UNIFIED_RATE_LIMIT_HEADER_NAMES,
DiscoveredModel,
ENGINE_TRANSPORT_TIMEOUT_SECONDS,
InvokeCancelledError,
@@ -101,6 +102,28 @@ _OFFICIAL_BASE_URLS = official_api_key_base_urls()
logger = logging.getLogger(__name__)
_ProjectedJSON = TypeVar("_ProjectedJSON")
+_ENGINE_HEADER_VALUE_MAX_LENGTH = 128
+_RETRY_AFTER_MS_MAX = 365 * 24 * 60 * 60 * 1000
+_CLAUDE_RATE_LIMIT_STATUS_VALUES = frozenset({"allowed", "allowed_warning", "rejected"})
+_CLAUDE_RATE_LIMIT_STATUS_HEADERS = frozenset({
+ "anthropic-ratelimit-unified-status",
+ "anthropic-ratelimit-unified-5h-status",
+ "anthropic-ratelimit-unified-7d-status",
+ "anthropic-ratelimit-unified-7d_oi-status",
+ "anthropic-ratelimit-unified-overage-status",
+})
+_CLAUDE_RATE_LIMIT_RESET_HEADERS = frozenset({
+ "anthropic-ratelimit-unified-5h-reset",
+ "anthropic-ratelimit-unified-7d-reset",
+ "anthropic-ratelimit-unified-7d_oi-reset",
+ "anthropic-ratelimit-unified-reset",
+ "anthropic-ratelimit-unified-overage-reset",
+})
+_CLAUDE_RATE_LIMIT_UTILIZATION_HEADERS = frozenset({
+ "anthropic-ratelimit-unified-5h-utilization",
+ "anthropic-ratelimit-unified-7d-utilization",
+})
+
# The engine forwards an upstream's response headers (``passthrough-headers``),
# minus hop-by-hop ones, and on errors it filters nothing. Avibe reads only these
# allowlisted names and builds every gateway response from its own headers, so no
@@ -109,14 +132,102 @@ _ProjectedJSON = TypeVar("_ProjectedJSON")
# again by ``sanitize_response_correlation_ids`` before they cross the outcome
# boundary.
ENGINE_RESPONSE_HEADER_ALLOW_LIST: frozenset[str] = frozenset(
- {"retry-after", *RESPONSE_CORRELATION_HEADER_NAMES}
+ {
+ "retry-after",
+ "retry-after-ms",
+ *RESPONSE_CORRELATION_HEADER_NAMES,
+ *CLAUDE_UNIFIED_RATE_LIMIT_HEADER_NAMES,
+ }
)
def _allowed_engine_header(headers: Mapping[str, str], name: str) -> str | None:
- """An engine response header Avibe reads; one off the allow-list reads as absent."""
+ """Read one exact allowlisted engine header case-insensitively."""
+
+ normalized_name = name.lower()
+ if normalized_name not in ENGINE_RESPONSE_HEADER_ALLOW_LIST:
+ return None
+ for header_name, value in headers.items():
+ if isinstance(header_name, str) and header_name.lower() == normalized_name:
+ return value if isinstance(value, str) else None
+ return None
+
+
+def _bounded_ascii_header_value(value: object) -> str | None:
+ if (
+ not isinstance(value, str)
+ or not value
+ or len(value) > _ENGINE_HEADER_VALUE_MAX_LENGTH
+ or not value.isascii()
+ or any(ord(char) < 0x20 or ord(char) == 0x7F for char in value)
+ ):
+ return None
+ return value.strip() or None
- return headers.get(name) if name.lower() in ENGINE_RESPONSE_HEADER_ALLOW_LIST else None
+
+def _retry_after_ms_value(headers: Mapping[str, str]) -> int | None:
+ raw = _bounded_ascii_header_value(_allowed_engine_header(headers, "Retry-After-Ms"))
+ if raw is None or not raw.isdecimal():
+ return None
+ try:
+ milliseconds = int(raw)
+ except (TypeError, ValueError, OverflowError):
+ return None
+ return milliseconds if milliseconds <= _RETRY_AFTER_MS_MAX else None
+
+
+def _normalize_claude_rate_limit_header(name: str, value: object) -> str | None:
+ normalized = _bounded_ascii_header_value(value)
+ if normalized is None:
+ return None
+ if name in _CLAUDE_RATE_LIMIT_STATUS_HEADERS:
+ normalized = normalized.lower()
+ return normalized if normalized in _CLAUDE_RATE_LIMIT_STATUS_VALUES else None
+ if name in _CLAUDE_RATE_LIMIT_RESET_HEADERS:
+ try:
+ numeric = Decimal(normalized)
+ if numeric.is_finite() and numeric > 0:
+ return normalized
+ except (ArithmeticError, ValueError):
+ pass
+ try:
+ parsed = datetime.fromisoformat(normalized.replace("Z", "+00:00"))
+ if parsed.tzinfo is not None:
+ return normalized
+ except ValueError:
+ pass
+ try:
+ parsed = parsedate_to_datetime(normalized)
+ if parsed.tzinfo is not None:
+ return normalized
+ except (TypeError, ValueError, IndexError, OverflowError):
+ pass
+ return None
+ if name in _CLAUDE_RATE_LIMIT_UTILIZATION_HEADERS:
+ try:
+ numeric = Decimal(normalized)
+ except (ArithmeticError, ValueError):
+ return None
+ return normalized if numeric.is_finite() and numeric >= 0 else None
+ return normalized
+
+
+def _allowed_claude_rate_limit_headers(
+ headers: Mapping[str, str],
+) -> tuple[tuple[str, str], ...]:
+ """Project only validated, exact Claude unified rate-limit fields."""
+
+ retained: dict[str, str] = {}
+ for raw_name, raw_value in headers.items():
+ if not isinstance(raw_name, str):
+ continue
+ name = raw_name.lower()
+ if name not in CLAUDE_UNIFIED_RATE_LIMIT_HEADER_NAMES or name in retained:
+ continue
+ value = _normalize_claude_rate_limit_header(name, raw_value)
+ if value is not None:
+ retained[name] = value
+ return tuple(sorted(retained.items()))
def upstream_api_url(root: str, path: str) -> str:
@@ -565,8 +676,10 @@ class EngineClient:
session = aiohttp.ClientSession(timeout=timeout, trust_env=False, trace_configs=trace_configs)
response: aiohttp.ClientResponse | None = None
retry_after: str | None = None
+ retry_after_ms: int | None = None
response_received_at: datetime | None = None
response_correlation_ids: tuple[tuple[str, str], ...] = ()
+ claude_rate_limit_headers: tuple[tuple[str, str], ...] = ()
first_received = False
model_output_started = False
ownership_transferred = False
@@ -597,7 +710,9 @@ class EngineClient:
outcome = replace(
outcome,
retry_after=retry_after,
+ retry_after_ms=retry_after_ms,
response_received_at=response_received_at,
+ claude_rate_limit_headers=claude_rate_limit_headers,
)
return completed_handle(outcome)
@@ -623,8 +738,13 @@ class EngineClient:
if response.status >= 300:
response_received_at = datetime.now(timezone.utc)
retry_after = _allowed_engine_header(response.headers, "Retry-After")
- if retry_after is not None and (len(retry_after) > 128 or not retry_after.isascii()):
+ retry_after_ms = _retry_after_ms_value(response.headers)
+ if retry_after is not None and (
+ len(retry_after) > _ENGINE_HEADER_VALUE_MAX_LENGTH or not retry_after.isascii()
+ ):
retry_after = None
+ if source.vendor == "anthropic":
+ claude_rate_limit_headers = _allowed_claude_rate_limit_headers(response.headers)
error_body = _StreamPrelude()
try:
await asyncio.wait_for(